PFN_WSK_CONTROL_CLIENT回调函数 (wsk.h)

项目
03/05/2024

WskControlClient 函数对 WSK 客户端对象执行控制操作。

语法

PFN_WSK_CONTROL_CLIENT PfnWskControlClient;

NTSTATUS PfnWskControlClient(
  [in]            PWSK_CLIENT Client,
  [in]            ULONG ControlCode,
  [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] Client

指向通过 WskCaptureProviderNPI 函数的 WskProviderNpi 参数返回的 WSK_CLIENT 结构的指针。

[in] ControlCode

正在执行的控制操作。 WSK 应用程序可以指定以下控制代码之一：

WSK_TRANSPORT_LIST_QUERY

检索可用网络传输的列表。

WSK_TRANSPORT_LIST_CHANGE

接收对可用网络传输列表的更改通知。

WSK_CACHE_SD

获取安全描述符的缓存副本。

WSK_RELEASE_SD

释放安全描述符的缓存副本。

WSK_SET_STATIC_EVENT_CALLBACKS

在所有套接字上自动启用指定的事件回调函数。

WSK_TDI_DEVICENAME_MAPPING

将地址系列、套接字类型和协议的组合映射到 TDI 传输的设备名称。

WSK_TDI_BEHAVIOR

控制 WSK 子系统是否将网络 I/O 转移到 TDI 传输。

[in] InputSize

InputBuffer 参数指向的缓冲区中的数据字节数。

[in, optional] InputBuffer

调用方分配的缓冲区，提供执行指定控制操作所需的任何输入数据。如果指定的控制操作不需要输入数据，WSK 应用程序应将此参数设置为 NULL ，并将 InputSize 参数设置为零。

[in] OutputSize

OutputBuffer 参数指向的缓冲区的大小（以字节为单位）。

[out, optional] OutputBuffer

调用方分配的缓冲区，用于接收指定控制操作返回的任何输出数据。如果指定的控制操作未返回任何输出数据，则 WSK 应用程序应将此参数设置为 NULL ，并将 OutputSize 参数设置为零。

[out, optional] OutputSizeReturned

指向 ULONG 类型变量的指针，该变量接收 OutputBuffer 参数指向的缓冲区中返回的数据字节数。 WSK 应用程序应将此指针设置为 NULL ，除非以下所有情况都为 true：

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

[in, out] Irp

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

此参数是必需的、可选或必须为 NULL，具体取决于正在执行的特定客户端控制操作。有关每个受支持的客户端控件操作的此参数要求的详细信息，请参阅 WSK 客户端控制操作。

返回值

WskControlClient 返回以下 NTSTATUS 代码之一：

返回代码	说明
STATUS_SUCCESS	控制操作已成功完成。如果 WSK 应用程序在 Irp 参数中指定了指向 IRP 的指针，则 IRP 将以成功状态完成。
STATUS_PENDING	WSK 子系统无法立即完成控制操作。 WSK 子系统将在完成控制操作后完成 IRP。将在 IRP 的 IoStatus.Status 字段中返回控制操作的状态。
STATUS_BUFFER_OVERFLOW	输出缓冲区不够大，无法包含返回的数据。 OutputSizeReturned 参数指向的变量包含所需的缓冲区大小。
其他状态代码	出现了错误。 IRP 将以失败状态完成。

注解

有关如何将输入和输出缓冲区用于每个客户端控制操作的详细信息，请参阅 WSK 客户端控制操作。

如果 WskControlClient 函数返回STATUS_PENDING，则 由 InputBuffer 参数或 OutputBuffer 参数指向的任何缓冲区都必须保持有效，直到 IRP 完成。如果 WSK 应用程序使用 ExAllocateXxx 函数之一分配了缓冲区，则在 IRP 完成之前，它无法使用相应的 ExFreeXxx 函数释放内存。如果 WSK 应用程序在堆栈上分配了缓冲区，则在 IRP 完成之前，它无法从调用 WskControlClient 函数的函数返回。

注意 Windows Vista 之后的 Microsoft Windows 版本将不支持 TDI。请改用 Windows 筛选平台或 Winsock 内核。

要求

要求	值
最低受支持的客户端	在 Windows Vista 和更高版本的 Windows 操作系统中可用。
目标平台	通用
标头	wsk.h (包括 Wsk.h)
IRQL	<= DISPATCH_LEVEL