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 函数，除非此函数处于可警告状态。线程处于可警报状态后，线程处理先入先出 (FIFO) 顺序的所有挂起的 APC，等待操作 将返回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.h、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
Library	Kernel32.lib
DLL	Kernel32.dll