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

Статья
08/08/2023

Функция WskSocketConnect создает новый сокет, ориентированный на подключение, привязывает его к локальному транспортному адресу, подключает его к заданному удаленному транспортному адресу и возвращает указатель на связанный объект сокета.

Синтаксис

PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;

NTSTATUS PfnWskSocketConnect(
  [in]           PWSK_CLIENT Client,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
                 ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *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] SocketType

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

SOCK_STREAM

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

SOCK_DGRAM

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

SOCK_RAW

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

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

[in] Protocol

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

[in] LocalAddress

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

[in] RemoteAddress

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

Flags

Этот параметр зарезервирован для системного использования. Приложения WSK должны задать для этого параметра нулевое значение.

[in, optional] SocketContext

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

[in, optional] Dispatch

Указатель на константу структура WSK_CLIENT_CONNECTION_DISPATCH . Эта структура представляет собой таблицу диспетчеризации, содержащую указатели на функции обратного вызова событий для нового сокета. Если приложение WSK не будет включать все функции обратного вызова событий для нового сокета, оно должно задать для указателей в таблице диспетчеризации значение NULL для тех функций обратного вызова событий, которые оно не включает. Если приложение WSK не будет включать функции обратного вызова событий в новом сокете, оно должно задать для этого указателя значение 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 см. в статье Использование irPs с функциями ядра Winsock.

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

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

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

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

Подсистема WSK определяет семейство адресов для нового сокета из семейства адресов, указанного в структуре SOCKADDR , на которую указывает параметр LocalAddress .

Если приложению WSK необходимо задать параметр сокета или выполнить операцию управления вводом-выводом для сокета перед привязкой или подключением сокета, приложение WSK должно вызывать функции WskSocket, WskBind и WskConnect вместо вызова функции WskSocketConnect .

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

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

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

Требования

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