функция обратного вызова PFN_WSK_RECEIVE (wsk.h)

Статья
08/08/2023

Функция WskReceive получает данные через подключение или потоковый сокет из удаленного адреса транспорта.

Синтаксис

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

Параметры

[in] Socket

Указатель на структуру WSK_SOCKET , указывающую объект сокета для сокета, из которого будут поступать данные.

[in] Buffer

Указатель на инициализированную структуру WSK_BUF , описывающую буфер данных, получающий данные из сокета.

[in] Flags

Значение ULONG, содержащее побитовое или сочетание следующих флагов:

WSK_FLAG_WAITALL

Дождитесь полного заполнения буфера данных. Если этот флаг указан, IRP, указанный в параметре Irp , не будет завершен до тех пор, пока не произойдет одно из следующих событий:

Буфер данных, описываемый структурой WSK_BUF, на которую указывает параметр Buffer , заполняется полностью.
Подключение корректно отключается удаленным отправителем.
Подключение прерывается приложением WSK или удаленным отправителем.
Указанная IRP отменена.

Этот флаг поддерживается транспортным протоколом Microsoft TCP/IP. Этот флаг может не поддерживаться другими транспортными протоколами.

WSK_FLAG_DRAIN

Дождитесь отключения сокета, отменив все данные, полученные в сокете. Если этот флаг указан, указанный IRP не будет завершен до тех пор, пока не произойдет одно из следующих событий:

Подключение корректно отключается удаленным отправителем.
Подключение прерывается приложением WSK или удаленным отправителем.
Указанная IRP отменена.

Все полученные данные удаляются подсистемой WSK. Полученные данные не копируются в буфер данных. Параметр Buffer по-прежнему является обязательным при указании этого флага, но длина буфера, описанного в структуре WSK_BUF, должна быть нулевой.

Флаги WSK_FLAG_WAITALL и WSK_FLAG_DRAIN являются взаимоисключающими. Приложение WSK не должно указывать оба этих флага одновременно.

[in, out] Irp

Указатель на выделенный вызывающим объектом IRP, который подсистема WSK использует для асинхронного завершения операции получения. Дополнительные сведения об использовании IRP с функциями WSK см. в разделе Использование IRP с функциями ядра Winsock.

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

WskReceive возвращает один из следующих кодов NTSTATUS:

Код возврата	Описание
STATUS_SUCCESS	Данные успешно получены из сокета. IRP будет завершена с состоянием успешного выполнения. Поле IoStatus.Information IRP содержит количество полученных байтов.
STATUS_PENDING	Подсистеме WSK не удалось получить данные из сокета немедленно. Подсистема WSK завершит IRP после получения данных из сокета. Состояние операции получения будет возвращено в поле IoStatus.Status IRP. Если операция выполнена успешно, поле IoStatus.Information IRP будет содержать количество полученных байтов.
STATUS_FILE_FORCED_CLOSED	Сокет больше не работает. IRP будет завершен с состоянием сбоя. Приложение WSK должно вызвать функцию WskCloseSocket , чтобы закрыть сокет как можно скорее.
STATUS_NOT_SUPPORTED	Указанный флаг не поддерживается базовым сетевым транспортом.
Другие коды состояния	Произошла ошибка. IRP будет завершен с состоянием сбоя.

Приложение WSK может вызывать функцию WskReceive только для подключения или потокового сокета, который ранее был подключен к удаленному транспортному адресу. Сокет, ориентированный на подключение, подключается к удаленному транспортному адресу одним из следующих способов:

Приложение WSK подключает сокет, вызывая функцию WskConnect .
Приложение WSK создает, привязывает и подключает сокет, вызывая функцию WskSocketConnect .
Подсистема WSK подключает сокет, когда приложение WSK принимает входящий запрос на подключение к прослушивателю сокета.

Если функция обратного вызова событий WskReceiveEvent приложения WSK включена в сокете, ориентированном на подключение, а приложение также имеет ожидающий вызов функции WskReceive в том же сокете, ориентированном на подключение, то при поступлении данных ожидающий вызов функции WskReceive будет иметь приоритет над функцией обратного вызова события WskReceiveEvent . Подсистема WSK вызывает функцию обратного вызова событий WskReceiveEvent приложения только в том случае, если из ожидающих вызовов функции WskReceive нет поставщиков irp. Однако приложение WSK не должно предполагать, что подсистема WSK не будет вызывать функцию обратного вызова событий WskReceiveEvent приложения для сокета, ориентированного на подключение, который имеет ожидающий вызов функции WskReceive . Существуют условия гонки, в которых подсистема WSK может по-прежнему вызывать функцию обратного вызова событий WskReceiveEvent приложения WSK для сокета. Единственный способ убедиться, что подсистема WSK не будет вызывать функцию обратного вызова событий WskReceiveEvent приложения для сокета, ориентированного на подключение, — отключить функцию обратного вызова событий WskReceiveEvent приложения в сокете.

Приложение WSK может вызывать функцию WskReceive с нулевой длиной, указанной в элементе Lengthструктуры WSK_BUF , на которую указывает параметр Buffer . Указание нулевой длины в этом элементе полезно в следующих ситуациях:

При повторном включении функции обратного вызова событий WskReceiveEvent для сокета после того, как функция обратного вызова события WskReceiveEvent ранее вернула STATUS_DATA_NOT_ACCEPTED
При указании WSK_FLAG_DRAIN флаг для отмены всех дополнительных данных, полученных в сокете.

Если функция WskReceive возвращает STATUS_PENDING, цепочка MDL, описанная в WSK_BUF структуре, на которую указывает параметр Buffer , должна оставаться заблокированной в памяти до завершения IRP.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows Vista и более поздних версиях операционных систем Windows.
Целевая платформа	Универсальное
Верхняя часть	wsk.h (включая Wsk.h)
IRQL	<= DISPATCH_LEVEL