PFN_WSK_SOCKET回调函数 (wsk.h)

项目
08/08/2023

WskSocket 函数创建新的套接字，并返回指向关联的套接字对象的指针。

语法

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

参数

[in] Client

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

[in] AddressFamily

正在创建的套接字的地址系列。有关支持的地址系列的详细信息，请参阅 WSK 地址系列。

[in] SocketType

正在创建的套接字的类型。支持以下套接字类型：

SOCK_STREAM

支持可靠的面向连接的字节流通信。

SOCK_DGRAM

支持不可靠的无连接数据报通信。

SOCK_RAW

支持对传输协议的原始访问。

有关每个支持的地址系列支持的套接字类型的详细信息，请参阅
WSK 地址系列。

[in] Protocol

正在创建的套接字的传输协议。有关每个支持的地址系列支持的协议的详细信息，请参阅 WSK 地址系列。

[in] Flags

一个标志，指定所创建的套接字的 WSK 套接字类别。此参数可以是以下标志之一：

WSK_FLAG_BASIC_SOCKET

将创建一个基本套接字，该套接字只能用于获取和设置传输堆栈套接字选项或执行套接字 I/O 控制操作。

WSK_FLAG_LISTEN_SOCKET

将创建一个侦听套接字，可用于侦听来自远程传输地址的传入连接。

WSK_FLAG_DATAGRAM_SOCKET

将创建可用于发送和接收数据报的数据报套接字。

WSK_FLAG_CONNECTION_SOCKET

将创建一个面向连接的套接字，可用于通过连接发送和接收网络数据。

WSK_FLAG_STREAM_SOCKET

将创建一个流套接字，该套接字可用于侦听来自远程传输地址的传入连接，或通过连接发送和接收网络数据。

如果 WSK 应用程序未指定上述任何标志， 则 WskSocket 将创建一个基本套接字。

[in, optional] SocketContext

指向正在创建的套接字的调用方提供的上下文的指针。 WSK 子系统将此指针传递给套接字的事件回调函数。上下文信息对 WSK 子系统不透明，必须存储在非分页内存中。如果 WSK 应用程序不会在新套接字上启用任何事件回调函数，则应将此指针设置为 NULL。对于基本套接字，此指针应始终为 NULL。

[in, optional] Dispatch

指向常量客户端调度结构的指针。此结构是一个调度表，其中包含指向新套接字的事件回调函数的指针。根据标志参数) 指定的套接字 (的 WSK 套接字类别，此参数是指向以下结构之一的指针。

标志	Dispatch 表结构
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

如果 WSK 应用程序不会为新套接字启用所有事件回调函数，则它应该将调度表中的指针设置为 NULL ，以便那些它未启用的事件回调函数。如果 WSK 应用程序不会在新套接字上启用任何事件回调函数，则应将 Dispatch 指针设置为 NULL。对于基本套接字，此指针应始终为 NULL。

[in, optional] OwningProcess

指向进程的指针，WSK 子系统将从中检索绑定套接字时要使用的安全上下文。 WSK 子系统使用安全上下文来确定是否可以共享本地传输地址（如果该地址已在使用中）。若要指定当前进程，WSK 应用程序将此指针设置为 NULL。

[in, optional] OwningThread

指向特定线程的指针，WSK 子系统将从该线程检索绑定套接字时要使用的安全上下文。 WSK 子系统使用安全上下文来确定是否可以共享本地传输地址（如果该地址已在使用中）。如果 WSK 应用程序不需要指定特定线程，则会将此指针设置为 NULL。

[in, optional] SecurityDescriptor

指向SECURITY_DESCRIPTOR结构的指针，该结构指定要应用于所创建的套接字的安全描述符。安全描述符控制套接字绑定到的本地传输地址的共享。如果 WSK 应用程序指定非 NULL 指针，它必须指定指向安全描述符的缓存副本的指针，该副本是通过使用WSK_CACHE_SD控制代码调用 WskControlClient 函数获取的。若要指定不允许共享本地传输地址的默认安全描述符，WSK 应用程序会将 SecurityDescriptor 设置为 NULL。

有关SECURITY_DESCRIPTOR结构的详细信息，请参阅Microsoft Windows SDK文档中SECURITY_DESCRIPTOR的参考页。

[in, out] Irp

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

返回值

WskSocket 返回以下 NTSTATUS 代码之一：

返回代码	说明
STATUS_SUCCESS	已成功创建新套接字。 IRP 将以成功状态完成。
STATUS_PENDING	WSK 子系统无法立即创建套接字。 WSK 子系统将在创建新的套接字后完成 IRP。将在 IRP 的 IoStatus.Status 字段中返回套接字创建状态。
其他状态代码	出现了错误。 IRP 将以失败状态完成。

注解

如果 IRP 已完成并处于成功状态，则 IRP 的 IoStatus.Information 字段包含指向新套接字 ( WSK_SOCKET) 的套接字对象结构的指针。

WSK 应用程序可以通过使用WSK_TRANSPORT_LIST_QUERY控制代码调用 WskControlClient 函数来获取可用传输协议的列表。 WskControlClient 返回包含 AddressFamily、SocketType 和 Protocol 参数的所有有效组合的WSK_TRANSPORT结构的列表。

当 WSK 应用程序成功创建新套接字时，默认禁用新套接字上的所有事件回调函数。有关启用任何新套接字的事件回调函数的详细信息，请参阅启用和禁用事件回调函数。

如果 WSK 应用程序为 SecurityDescriptor 参数指定非 NULL 指针，则在 IRP 完成后，它不得释放缓存的安全描述符。

WSK 子系统代表 WSK 应用程序为新套接字分配套接字对象结构的内存 (WSK_SOCKET) 。 WSK 子系统在套接字关闭时解除分配此内存。

要求

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