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.
