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

Статья
08/08/2023

Функция обратного вызова событий WskReceiveEvent уведомляет приложение WSK о получении данных в сокете, ориентированном на подключение.

Синтаксис

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

Параметры

[in, optional] SocketContext

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

Он вызвал функцию WskSocket для создания сокета.
Он вызвал функцию WskSocketConnect для создания сокета.
Она вызвала функцию WskAccept для принятия сокета в качестве входящего подключения.
Его функция обратного вызова события WskAcceptEvent была вызвана для принятия сокета в качестве входящего подключения.

[in] Flags

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

Значение	Значение
WSK_FLAG_RELEASE_ASAP	Буферы данных, содержащие полученные данные, не должны храниться приложением WSK, если это возможно. Если приложение WSK сохраняет буферы, оно должно освободить их как можно скорее, вызвав функцию WskRelease .
WSK_FLAG_ENTIRE_MESSAGE	Буферы данных содержат либо целое сообщение, либо конечную часть сообщения. Интерпретация всего сообщения зависит от транспортного протокола. Для TCP этот флаг указывает, что бит отправки был задан для одного или нескольких сегментов TCP, составляющих данные в буферах данных.
WSK_FLAG_AT_DISPATCH_LEVEL	Подсистема WSK вызвала функцию обратного вызова события WskReceiveEvent в IRQL = DISPATCH_LEVEL. Если этот флаг не задан, подсистема WSK могла вызвать функцию обратного вызова события WskReceiveEvent в любом

[in, optional] DataIndication

Указатель на связанный список WSK_DATA_INDICATION структур, описывающих полученные данные. Если этот параметр имеет значение NULL, сокет больше не работает, и приложение WSK должно вызвать функцию WskCloseSocket , чтобы закрыть сокет как можно скорее.

[in] BytesIndicated

Количество байтов полученных данных, описываемое связанным списком WSK_DATA_INDICATION структур.

[in, out] BytesAccepted

Указатель на SIZE_T типизированной переменной, которая получает количество байтов полученных данных, принимаемых приложением WSK. Эту переменную необходимо задать только в том случае, если приложение WSK принимает часть общего числа байтов полученных данных. Если приложение WSK принимает все полученные данные, ему не нужно задавать эту переменную. Если функция обратного вызова событий WskReceiveEvent возвращает состояние, отличное от STATUS_SUCCESS, подсистема WSK игнорирует значение этой переменной.

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

Функция обратного вызова событий WskReceiveEvent приложения WSK может возвращать один из следующих кодов NTSTATUS:

Код возврата	Описание
STATUS_SUCCESS	Приложение WSK приняло по крайней мере некоторые полученные данные. Если приложение WSK приняло все полученные данные, подсистема WSK может снова вызвать функцию обратного вызова события WskReceiveEvent при получении новых данных в сокете. Однако если приложение WSK приняло только часть полученных данных, подсистема WSK не вызовет функцию обратного вызова события WskReceiveEvent до тех пор, пока приложение WSK не вызовет функцию WskReceive . После того как приложение WSK вызовет функцию WskReceive , подсистема WSK возобновит вызов функции обратного вызова события WskReceiveEvent с оставшимися буферизируемыми данными и при получении новых данных в сокете. Приложение WSK может вызывать функцию WskReceive с буфером нулевой длины, что приведет к тому, что подсистема WSK возобновит вызов функции обратного вызова события WskReceiveEvent без вызова WskReceive для получения данных из сокета.
STATUS_PENDING	Приложение WSK приняло данные, но не извлекает все данные, содержащиеся в связанном списке WSK_DATA_INDICATION структур. Приложение WSK сохраняет связанный список WSK_DATA_INDICATION структур до тех пор, пока не будут получены все данные. После того как приложение WSK извлекло все данные, оно вызывает функцию WskRelease , чтобы освободить связанный список WSK_DATA_INDICATION структур обратно в подсистему WSK. Подсистема WSK может снова вызывать функцию обратного вызова событий WskReceiveEvent при получении новых данных в сокете.
STATUS_DATA_NOT_ACCEPTED	Приложение WSK не приняло данные. В этом случае подсистема WSK будет иметь базовый транспортный буфер данных, если это возможно или если это требуется протоколом. Подсистема WSK не будет вызывать функцию обратного вызова события WskReceiveEvent до тех пор, пока приложение WSK не вызовет функцию WskReceive . После того как приложение WSK вызовет функцию WskReceive , подсистема WSK возобновит вызов функции обратного вызова события WskReceiveEvent с оставшимися буферизируемыми данными и при получении новых данных в сокете. Приложение WSK может вызывать функцию WskReceive с буфером нулевой длины, что приведет к тому, что подсистема WSK возобновит вызов функции обратного вызова события WskReceiveEvent без вызова WskReceive для получения данных из сокета.

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

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

Примечание

Ядро Winsock (WSK) вызывает этот обратный вызов последовательно, поэтому он не всегда вызывается сразу после получения данных.

Подсистема WSK вызывает функцию обратного вызова события WskReceiveEvent приложения WSK в IRQL <= DISPATCH_LEVEL.

Функция обратного вызова событий WskReceiveEvent приложения WSK не должна ждать завершения других запросов WSK в контексте функций завершения WSK или обратного вызова событий. Обратный вызов может инициировать другие запросы WSK (при условии, что он не тратит слишком много времени на DISPATCH_LEVEL), но не должен ждать их завершения, даже если обратный вызов вызывается в IRQL = PASSIVE_LEVEL.

Требования

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