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

Статья
03/05/2024

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

Синтаксис

PFN_WSK_ACCEPT_EVENT PfnWskAcceptEvent;

NTSTATUS PfnWskAcceptEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_SOCKET AcceptSocket,
  [out]          PVOID *AcceptSocketContext,
  [out]          const WSK_CLIENT_CONNECTION_DISPATCH **AcceptSocketDispatch
)
{...}

Параметры

[in, optional] SocketContext

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

[in] Flags

Значение ULONG, содержащее следующий флаг, или ноль:

WSK_FLAG_AT_DISPATCH_LEVEL

Подсистема WSK называется функцией обратного вызова события WskAcceptEvent в IRQL = DISPATCH_LEVEL. Если этот флаг не задан, подсистема WSK могла вызвать функцию обратного вызова события WskAcceptEvent в любом irQL <= DISPATCH_LEVEL.

[in] LocalAddress

Указатель на буфер, содержащий адрес локального транспорта, по которому поступило входящее соединение. Буфер содержит конкретный тип структуры SOCKADDR, соответствующий семейству адресов, которое приложение WSK указало при создании сокета прослушивания.

[in] RemoteAddress

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

[in, optional] AcceptSocket

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

[out] AcceptSocketContext

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

[out] AcceptSocketDispatch

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

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

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

Код возврата	Описание
STATUS_SUCCESS	Приложение WSK приняло входящее подключение.
STATUS_REQUEST_NOT_ACCEPTED	Приложение WSK отклонило входящее подключение. Если это значение возвращается, подсистема WSK закроет принятый сокет от имени приложения WSK.

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

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

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

Структуры SOCKADDR , на которые указывают параметры LocalAddress и RemoteAddress , действительны только на протяжении всего вызова функции обратного вызова события WskAcceptEvent . Если приложению WSK требуются эти транспортные адреса позже, оно может скопировать содержимое этих структур в собственные структуры SOCKADDR перед возвратом из функции обратного вызова события WskAcceptEvent или позже вызвать функции WskGetLocalAddress и WskGetRemoteAddress в принятом сокете.

Подсистема WSK выделяет память для структуры объекта сокета ( WSK_SOCKET) для принятого подключения от имени приложения WSK. Подсистема WSK освобождает эту память при закрытии сокета.

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

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

Требования

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