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

Статья
02/27/2024

Функция WskSocket создает новый сокет и возвращает указатель на связанный объект сокета.

Синтаксис

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

Параметры

[in] Client

Указатель на структуру WSK_CLIENT , возвращенную с помощью параметра WskProviderNpi объектаФункция WskCaptureProviderNPI.

[in] AddressFamily

Семейство адресов для создаваемого сокета. Дополнительные сведения о поддерживаемых семействах адресов см. в разделе Семейства адресов WSK.

[in] SocketType

Тип создаваемого сокета. Поддерживаются следующие типы сокетов:

SOCK_STREAM

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

SOCK_DGRAM

Поддерживает ненадежный обмен данными с датаграммами без подключения.

SOCK_RAW

Поддерживает необработанный доступ к транспортному протоколу.

Дополнительные сведения о типах сокетов, поддерживаемых для каждого поддерживаемого семейства адресов, см. в разделе
Семейства адресов WSK.

[in] Protocol

Транспортный протокол для создаваемого сокета. Дополнительные сведения о протоколах, поддерживаемых для каждого поддерживаемого семейства адресов, см. в разделе Семейства адресов WSK.

[in] Flags

Флаг , указывающий категорию сокета WSK для создаваемого сокета. Этот параметр может иметь один из следующих флагов:

WSK_FLAG_BASIC_SOCKET

Будет создан базовый сокет, который можно использовать только для получения и задания параметров сокета транспортного стека или для выполнения операций управления вводом-выводом сокета.

WSK_FLAG_LISTEN_SOCKET

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

WSK_FLAG_DATAGRAM_SOCKET

Будет создан сокет датаграммы, который можно использовать для отправки и получения датаграмм.

WSK_FLAG_CONNECTION_SOCKET

Будет создан ориентированный на подключение сокет, который можно использовать для отправки и получения сетевых данных по подключению.

WSK_FLAG_STREAM_SOCKET

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

Если приложение WSK не указывает ни один из предыдущих флагов, WskSocket создает базовый сокет.

[in, optional] SocketContext

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

[in, optional] Dispatch

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

Flag	Структура таблицы диспетчеризации
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

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

[in, optional] OwningProcess

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

[in, optional] OwningThread

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

[in, optional] SecurityDescriptor

Указатель на структуру SECURITY_DESCRIPTOR, указывающую дескриптор безопасности, применяемый к создаваемому сокету. Дескриптор безопасности управляет общим доступом к локальному адресу транспорта, к которому привязан сокет. Если приложение WSK указывает указатель, отличный от NULL , он должен указать указатель на кэшированную копию дескриптора безопасности, полученную путем вызова функции WskControlClient с кодом элемента управления WSK_CACHE_SD . Чтобы указать дескриптор безопасности по умолчанию, который не разрешает общий доступ к локальному адресу транспорта, приложение WSK устанавливает для SecurityDescriptorзначение NULL.

Дополнительные сведения о структуре SECURITY_DESCRIPTOR см. на справочной странице для SECURITY_DESCRIPTOR документации по Microsoft Windows SDK.

[in, out] Irp

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

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

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

Код возврата	Описание
STATUS_SUCCESS	Новый сокет успешно создан. IRP будет завершена с состоянием успешного выполнения.
STATUS_PENDING	Подсистеме WSK не удалось создать сокет немедленно. Подсистема WSK завершит IRP после создания нового сокета. Состояние создания сокета будет возвращено в поле IoStatus.Status IRP.
Другие коды состояния	Произошла ошибка. IRP будет завершен с состоянием сбоя.

Приложение WSK может получить список доступных транспортных протоколов, вызвав функцию WskControlClient с кодом элемента управления WSK_TRANSPORT_LIST_QUERY . WskControlClient возвращает список WSK_TRANSPORT структур, содержащих все допустимые сочетания параметров AddressFamily, SocketType и Protocol .

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

Если приложение WSK указывает указатель, отличный от NULL , для параметра SecurityDescriptor , оно не должно освобождать кэшированный дескриптор безопасности до завершения IRP.

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

Требования

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