PFN_WSK_CONTROL_SOCKET回调函数（wsk.h）

项目
02/07/2025

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

执行 I/O 控制作。

[in] ControlCode

如果 RequestType 参数设置为 WskSetOption 或 WskGetOption，则 ControlCode 参数指定其值正在设置或检索的特定套接字选项。有关 WSK 子系统支持的套接字选项的详细信息，请参阅 WSK 套接字选项。基础网络协议可能支持其他套接字选项。

如果 RequestType 参数设置为 WskIoctl，则 ControlCode 参数指定正在执行的特定 I/O 控件作。有关 WSK 子系统支持的 I/O 控制作的详细信息，请参阅 WSK 套接字 IOCTL作。基础网络协议可能支持其他套接字 I/O 控制作。

[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，除非以下所有内容均为 true：

Irp 参数设置为 NULL。
所执行的作返回 OutputBuffer 参数指向的缓冲区中的输出数据。
所执行的作返回的输出数据的字节数未知。

[in, out] Irp

指向 WSK 子系统用于异步完成控制作的调用方分配的 IRP 的指针。有关将 IRP 与 WSK 函数配合使用的详细信息，请参阅将 IRP 与 Winsock 内核函数配合使用。

如果将 RequestType 参数设置为 WskSetOption 或 WskGetOption，则 Irp 参数是必需的，是可选的，或者必须 NULL，具体取决于要设置或检索的特定套接字选项。有关每个受支持的套接字选项 Irp 参数的要求的详细信息，请参阅 WSK 套接字选项。

如果将 RequestType 参数设置为 WskIoctl，则 Irp 参数是必需的，或者必须根据所执行的特定 I/O 控件作 NULL。有关每个受支持的 I/O 控制作 Irp 参数的要求的详细信息，请参阅 WSK 套接字 IOCTL作。

返回值

WskControlSocket 返回以下 NTSTATUS 代码之一：

返回代码	描述
STATUS_SUCCESS	控制作已成功完成。如果 WSK 应用程序在 Irp 参数中指定了指向 IRP 的指针，则 IRP 将以成功状态完成，并且 OutputBuffer 参数指向的缓冲区中返回的字节数将在 IRP 的 IoStatus.Information 字段中返回。
STATUS_PENDING	WSK 子系统无法立即完成控制作。完成控制作后，WSK 子系统将完成 IRP。控制作的状态将在 IRP 的 IoStatus.Status 字段中返回。如果作成功，OutputBuffer 参数指向的缓冲区中返回的字节数将在 IRP 的 IoStatus.Information 字段中返回。
STATUS_EVENT_PENDING	WSK 子系统无法立即完成控制作。仅当 WSK 应用程序在套接字上禁用事件回调函数时，才会返回此值，前提是当前正在调用该事件回调函数，并且当 Irp 参数 NULL时。有关禁用事件回调函数的详细信息，请参阅 SO_WSK_EVENT_CALLBACK。
STATUS_FILE_FORCED_CLOSED	套接字不再正常工作。 IRP 将以失败状态完成。 WSK 应用程序必须调用 WskCloseSocket 函数才能尽快关闭套接字。
其他状态代码	发生错误。 IRP 将以失败状态完成。

言论

如果 WSK 应用程序在 RequestType 参数中指定 WskSetOption 或 WskGetOption，请参阅 WSK 套接字选项，了解有关输入和输出缓冲区如何用于每个套接字选项的详细信息。

如果 WSK 应用程序在 RequestType 参数中指定 WskIoctl，请参阅 WSK 套接字 IOCTL作，详细了解输入和输出缓冲区如何用于每个 I/O 控制作。

如果 WskControlSocket 函数返回STATUS_PENDING，则 InputBuffer 参数指向的任何缓冲区或 OutputBuffer 参数必须保持有效，直到 IRP 完成。如果 WSK 应用程序使用 ExAllocateXxx 函数之一分配了缓冲区，则在 IRP 完成后，它才能使用相应的 ExFreeXxx 函数释放内存。如果 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 （请参阅“备注”部分）