Функция 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

Одно значение, передаваемое функции APC, на которую указывает параметр pfnAPC .

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Windows Server 2003 и Windows XP: Для этой функции не определены значения ошибок, которые можно получить, вызвав Метод GetLastError.

Комментарии

Дополнительные сведения о специальных APC в пользовательском режиме см. в разделе Функция QueueUserAPC2 .

Поддержка 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
Header processthreadsapi.h (включая Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также