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

Статья
02/07/2025

Функция 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 сокета (как указано в параметре флагов), этот параметр является указателем на одну из следующих структур.

Флаг	Структура таблицы отправки
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 не будет включать функции обратного вызова событий в новом сокете, оно должно задать указатель диспетчера на 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 документации по пакету SDK для Microsoft Windows.

[in, out] Irp

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

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

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

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

Замечания

Если IRP завершен с состоянием успешности, поле IoStatus.Information IRP содержит указатель на структуру объектов сокета (WSK_SOCKET) для нового сокета.

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows Vista и более поздних версиях операционных систем Windows.
целевая платформа	Всеобщий
заголовка	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL