Функция WPUQueueApc (ws2spi.h)

  • Статья

Функция WPUQueueApc помещает в очередь асинхронный вызов процедуры в пользовательском режиме (APC) в указанный поток, чтобы упростить вызов перекрывающихся процедур завершения ввода-вывода.

Синтаксис

int WPUQueueApc(
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPWSAUSERAPC  lpfnUserApc,
  [in]  DWORD_PTR     dwContext,
  [out] LPINT         lpErrno
);

Параметры

[in] lpThreadId

Указатель на структуру WSATHREADID , которая идентифицирует контекст потока. Указатель на эту структуру предоставляется поставщику услуг Ws2_32.dll в качестве входного параметра для перекрывающейся операции. Поставщик должен хранить структуру WSATHREADID локально и предоставить указатель на это локальное хранилище. Локальная копия WSATHREADID больше не требуется после возврата WPUQueueApc .

[in] lpfnUserApc

Указатель на вызываемую функцию APC.

[in] dwContext

32-разрядное значение контекста, которое затем предоставляется в качестве входного параметра для функции APC.

[out] lpErrno

Указатель на код ошибки.

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

Если ошибка не возникает, WPUQueueApc возвращает ноль и помещает в очередь подпрограмму завершения для указанного потока. В противном случае он возвращает SOCKET_ERROR, и в lpErrno доступен определенный код ошибки.

Код ошибки Значение
WSAEFAULT
 Параметр dwThreadId не указывает допустимый поток.
 
 

Комментарии

Эта функция помещает функцию APC в очередь указанного потока. В Windows это будет выполняться с помощью асинхронного вызова процедуры в пользовательском режиме (APC). APC будет выполняться только в том случае, если указанный поток заблокирован в режиме ожидания с оповещениями, а обратный вызов будет выполнен напрямую. Этот вызов безопасен для использования в контексте прерывания.

LPWSAUSERAPC определяется следующим образом:

typedef void ( CALLBACK FAR * LPWSAUSERAPC )( DWORD dwContext );

Поскольку механизм APC поддерживает только одно значение контекста, lpfnUserApc сам по себе не может быть указанной клиентом подпрограммой завершения, которая включает в себя больше параметров. Поставщик услуг должен вместо этого предоставить указатель на собственную функцию APC, которая использует предоставленное значение dwContext для доступа к необходимым сведениям о результатах для перекрывающейся операции, а затем вызывает подпрограмму завершения, указанную клиентом.

Для поставщиков услуг, где компонент пользовательского режима реализует перекрывающиеся ввод-вывод, обычно механизм APC используется следующим образом.

    — После завершения операции ввода-вывода поставщик выделяет небольшой буфер и упаковывает его с указателем на предоставленную клиентом процедуру завершения и значения параметров для передачи процедуре. — он помещает в очередь APC, указывая указатель на буфер в качестве значения dwContext и собственную промежуточную процедуру в качестве целевой процедуры lpfnUserApc. — Когда целевой поток в конечном итоге переходит в состояние ожидания с возможностью оповещения, промежуточная процедура поставщика услуг вызывается в соответствующем контексте потока. — Промежуточная процедура просто распаковывает параметры, освобождает буфер и вызывает предоставленную клиентом процедуру завершения.

Требования

   
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header ws2spi.h

См. также раздел

WSATHREADID

LPWSPIoctl

LPWSPRecv

LPWSPRecvFrom

LPWSPSend

LPWSPSendTo