QueueUserAPC

The QueueUserAPCfunction adds a user-mode asynchronous procedure call

QueueUserAPC函数把一个APC对象加入到指定线程的APC队列中。

(APC) object to the APC queue of the specified thread.

DWORD QueueUserAPC(

PAPCFUNCpfnAPC, // APC function

HANDLEhThread, // handle to thread

ULONG_PTRdwData // APC function parameter

);

Parameters

pfnAPC

[in] Pointer to the application-supplied APC function to be called

指向一个用户提供的APC函数的指针。这个函数将在指定线程执行an alertable wait operation操作时被调用。

when the specified thread performs an alertable wait operation. For more information, see APCProc.

hThread

[in] Specifies the handle to the thread. The handle must have

指定特定线程的句柄。这个句柄必须有THREAD_SET_CONTEXT的权限。

THREAD_SET_CONTEXT access. For more information, see Synchronization Object Security and Access Rights.

dwData

[in] Specifies a single value that is passed to the APC function

指定一个被传到pfnAPC参数指向的APC函数的值。

pointed to by the pfnAPCparameter.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. There are no error values defined for this function that can be retrieved by calling GetLastError.

Remarks

The APC support provided in the operating system allows an application

to queue an APC object to a thread. Each thread has its own APC queue. The queuing of an APC is a request for the thread to call the APC function. The operating system issues a software interrupt to direct the thread to call the APC function.

有操作系统提供的APC支持允许一个应用程序把一个APC对象排队的一个线程的APC队列。每个线程都有它的APC队列。一个APC对象排队是一个对线程的请求，请求线程调用APC函数。操作系统发出一个软件中断命令线程调用APC函数。

When a user-mode APC is queued, the thread is not directed to call the APC function unless it is in an alertable state. After the thread is in an alertable state, the thread handles all pending APCs in first in, first out (FIFO) order, and the wait operation returns WAIT_IO_COMPLETION. A thread enters an alertable state by using SleepEx, SignalObjectAndWait, WaitForSingleObjectEx, WaitForMultipleObjectsEx, or MsgWaitForMultipleObjectsExto perform an alertable wait operation.

当一个用户模式APC对象被排队时，只要在线程处于警告状态时，线程才会被命令调用APC函数。在线程处于警告状态时，线程将会按FIFO的顺序去处理所有尚未处理的APC对象，并且此时等操作返回WAIT_IO_COMLEMENT.一个进入警告状态的线程通过调用SleepEx, SignalObjectAndWait, WaitForSingleObjectEx, WaitForMultipleObjectsEx, or MsgWaitForMultipleObjectsEx来等待警告。

If an application queues an APC before the thread begins running, the thread begins by calling the APC function. After the thread calls an APC function, it calls the APC functions for all APCs in its APC queue.

如果应用程序在线程开始运行之前将一个APC对象排队其APC队列，那么这个线程在调用完APC函数时，才会正式开始运行。而且，一旦这个线程开始调用一个APC函数，他会为APC队列中的所有APC对象调用其相应的APC函数。（即要么不处理，要么一下子处理完）

When the thread is terminated using the ExitThreador TerminateThreadfunction, the APCs in its APC queue are lost. The APC functions are not called.

当一个线程用ExitThreador TerminateThread终结后，它的APC队列中的APC对象会抛弃。APC函数也就不会再被调用

Note that the ReadFileEx, SetWaitableTimer, and WriteFileExfunctions are implemented using an APC as the completion notification callback mechanism.

注意ReadFileEx, SetWaitableTimer, and WriteFileEx用APC作为其完成通知回调机制来执行。

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Winbase.h; include Windows.h.

Library: Use Kernel32.lib.