QueueUserAPC 函式 (processthreadsapi.h)

將使用者模式 異步過程調用 (APC) 物件新增至指定線程的 APC 佇列。

語法

DWORD QueueUserAPC(
  [in] PAPCFUNC  pfnAPC,
  [in] HANDLE    hThread,
  [in] ULONG_PTR dwData
);

參數

[in] pfnAPC

當指定的線程執行可警示的等候作業時，所要呼叫之應用程式提供的APC函式指標。 如需詳細資訊，請參閱 PAPCFUNC回呼函式。

[in] hThread

線程的句柄。 句柄必須具有 THREAD_SET_CONTEXT 訪問許可權。 如需詳細資訊，請參閱 同步處理物件安全性和訪問許可權。

[in] dwData

傳遞至 pfnAPC 參數所指向之 APC 函式的單一值。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 Windows Server 2003 和 Windows XP： 呼叫 GetLastError 無法擷取此函式的錯誤值。

備註

如需特殊使用者模式 APC 的詳細資訊，請參閱 QueueUserAPC2 函 式。

操作系統中提供的 APC 支援可讓應用程式將 APC 物件排入線程。 為了確保 APC 所使用的函式順利執行，APC 應該只會排入佇列給呼叫端進程中的線程。

注意

基於許多原因，不建議將APC排入呼叫端進程外部的線程。 DLL 重新處理可能會導致 APC 在呼叫端進程外執行函式時所使用的函式地址不正確。 同樣地，如果64位進程將APC排入32位進程，反之亦然，位址將會不正確，而且應用程式會當機。 其他因素可能會防止成功的函式執行，即使知道位址也一樣。

每個線程都有自己的 APC 佇列。 APC 的佇列是呼叫 APC 函式之線程的要求。 操作系統發出軟體中斷，以指示線程呼叫 APC 函式。

當使用者模式 APC 排入佇列時，除非線程處於可警示的狀態，否則線程不會導向呼叫 APC 函式。 線程處於可警示狀態之後，線程會先處理中所有擱置的 APC，先 (FIFO) 順序，等候作業會傳回 WAIT_IO_COMPLETION。 線程會使用 SleepEx 函式、 SignalObjectAndWait 函式、 WaitForSingleObjectEx 函式、 WaitForMultipleObjectsEx 函式或 MsgWaitForMultipleObjectsEx 函式來進入可警示的狀態。

如果應用程式在線程開始執行之前將APC排入佇列，則線程會從呼叫 APC 函式開始。 在線程呼叫 APC 函式之後，它會為其 APC 佇列中的所有 APC 呼叫 APC 函式。

可以在 APC 內睡眠或等候物件。 如果您在 APC 內執行可警示的等候，則會以遞歸方式分派 APC。 這可能會造成堆疊溢位。

使用 ExitThread 函 式或 TerminateThread 函 式終止線程時，其 APC 佇列中的 APC 會遺失。 未呼叫 APC 函式。

當線程在終止的過程中，呼叫 QueueUserAPC 以新增至線程的 APC 佇列將會失敗， (31) ERROR_GEN_FAILURE。

請注意， ReadFileEx 函式、 SetWaitableTimer 函式和 WriteFileEx 函式是使用 APC 作為完成通知回呼機制來實作。

若要編譯使用此函式的應用程式，請將_WIN32_WINNT定義為 0x0400 或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台	Windows
標頭	processthreadsapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

• PAPCFUNC 回呼函式
• 異步過程調用
• 同步處理函式