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

Статья
08/08/2023

Функция WskControlSocket выполняет операции управления сокетом.

Синтаксис

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

Параметры

[in] Socket

Указатель на структуру WSK_SOCKET , указывающую объект сокета для сокета, в котором выполняется операция управления.

[in] RequestType

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

WskSetOption

Задайте состояние или значение для параметра сокета.

WskGetOption

Получение состояния или значения параметра сокета.

WskIoctl

Выполнение операции управления вводом-выводом.

[in] ControlCode

Если параметр RequestType имеет значение WskSetOption или WskGetOption, параметр ControlCode указывает конкретный параметр сокета, значение которого устанавливается или извлекается. Дополнительные сведения о параметрах сокета, поддерживаемых подсистемой WSK, см. в разделе Параметры сокета WSK. Базовый сетевой протокол может поддерживать дополнительные параметры сокета.

Если параметр RequestType имеет значение WskIoctl, параметр ControlCode указывает конкретную выполняемую операцию управления вводом-выводом. Дополнительные сведения об операциях управления вводом-выводом, поддерживаемых подсистемой WSK, см. в разделе Операции IOCTL сокета WSK. Базовый сетевой протокол может поддерживать дополнительные операции управления вводом-выводом сокета.

[in] Level

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

Если параметр RequestType имеет значение WskIoctl, параметр Level игнорируется.

[in] InputSize

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

[in, optional] InputBuffer

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

[in] OutputSize

Размер буфера, на который указывает параметр OutputBuffer .

[out, optional] OutputBuffer

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

[out, optional] OutputSizeReturned

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

Параметр Irp имеет значение NULL.
Выполняемая операция возвращает выходные данные в буфере, на который указывает параметр OutputBuffer .
Число байтов выходных данных, возвращаемых выполняемой операцией, неизвестно.

[in, out] Irp

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

Если для параметра RequestType задано значение WskSetOption или WskGetOption, параметр Irp является обязательным, необязательным или должен иметь значение NULL в зависимости от конкретного параметра сокета, который устанавливается или извлекается. Дополнительные сведения о требованиях к параметру Irp для каждого из поддерживаемых параметров сокета см. в разделе Параметры сокета WSK.

Если для параметра RequestType задано значение WskIoctl, параметр Irp является обязательным, необязательным или должен иметь значение NULL в зависимости от конкретной выполняемой операции управления вводом-выводом. Дополнительные сведения о требованиях к параметру Irp для каждой из поддерживаемых операций управления вводом-выводом см. в разделе Операции IOCTL сокета WSK.

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

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

Код возврата	Описание
STATUS_SUCCESS	Операция управления успешно завершена. Если приложение WSK указало указатель на IRP в параметре Irp , IRP будет завершен с состоянием успешного выполнения, а количество байтов, возвращаемых в буфере, на который указывает параметр OutputBuffer , будет возвращено в поле IoStatus.Information IRP.
STATUS_PENDING	Подсистеме WSK не удалось завершить операцию управления немедленно. Подсистема WSK завершит IRP после завершения операции управления. Состояние операции управления будет возвращено в поле IoStatus.Status IRP. Если операция выполнена успешно, количество байтов, возвращаемых в буфере, на который указывает параметр OutputBuffer , будет возвращено в поле IoStatus.Information IRP.
STATUS_EVENT_PENDING	Подсистеме WSK не удалось завершить операцию управления немедленно. Это значение возвращается только в том случае, если приложение WSK отключит функцию обратного вызова событий в сокете, если в данный момент выполняются вызовы этой функции обратного вызова события и параметр Irp имеет значение NULL. Дополнительные сведения об отключении функций обратного вызова событий см. в разделе SO_WSK_EVENT_CALLBACK.
STATUS_FILE_FORCED_CLOSED	Сокет больше не работает. IRP будет завершен с состоянием сбоя. Приложение WSK должно вызвать функцию WskCloseSocket , чтобы как можно скорее закрыть сокет.
Другие коды состояния	Произошла ошибка. IRP будет завершен с состоянием сбоя.

Если приложение WSK указывает WskSetOption или WskGetOption в параметре RequestType , дополнительные сведения об использовании входных и выходных буферов для каждого параметра сокета см. в разделе Параметры сокета WSK .

Если приложение WSK указывает WskIoctl в параметре RequestType , дополнительные сведения об использовании входных и выходных буферов для каждой операции управления вводом-выводом см. в разделе Операции IOCTL сокета WSK .

Если функция WskControlSocket возвращает STATUS_PENDING, все буферы, на которые указывает параметр InputBuffer или OutputBuffer , должны оставаться действительными до завершения IRP. Если приложение WSK выделило буферы с помощью одной из функций ExAllocateXxx , оно не сможет освободить память с помощью соответствующей функции ExFreeXxx до завершения IRP. Если приложение WSK выделило буферы в стеке, оно не может вернуться из функции, вызывающей функцию WskControlSocket , до завершения IRP.

Вызывающие функции WskControlSocket должны выполняться в irQL <= DISPATCH_LEVEL за исключением случаев, когда для параметра RequestType задано значение WskIoctl , а для параметра ControlCode задано значение SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGE или SIO_ADDRESS_LIST_SORT. В этом случае вызывающие операторы должны выполняться в irQL = PASSIVE_LEVEL.

Требования

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