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.
