PFN_WSK_CONTROL_SOCKET回调函数 (wsk.h)

项目
03/05/2024

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 ，除非以下所有情况都成立：

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

[in, out] Irp

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

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

如果 RequestType 参数设置为 WskIoctl，则 Irp 参数是必需的、是可选的，或者必须为 NULL ，具体取决于正在执行的特定 I/O 控制操作。有关每个受支持的 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 字段中返回控制操作的状态。如果操作成功，将在 IRP 的 IoStatus.Information 字段中返回由 OutputBuffer 参数指向的缓冲区中返回的字节数。
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 应用程序在堆栈上分配了缓冲区，则在 IRP 完成之前，它无法从调用 WskControlSocket 函数的函数返回。

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 (请参阅备注部分)