PFN_WSK_RECEIVE回调函数（wsk.h）

项目
02/07/2025

WskReceive 函数通过面向连接或流套接字从远程传输地址接收数据。

语法

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

参数

[in] Socket

指向 WSK_SOCKET 结构的指针，该结构指定要从中接收数据的套接字的套接字对象。

[in] Buffer

指向初始化 WSK_BUF 结构的指针，该结构描述从套接字接收数据的数据缓冲区。

[in] Flags

包含以下标志组合的按位 OR 的 ULONG 值：

WSK_FLAG_WAITALL

等待数据缓冲区完全填充。如果指定了此标志，则在发生以下事件之一之前，Irp 参数中指定的 IRP 将不会完成：

Buffer 参数指向的WSK_BUF结构描述的数据缓冲区已完全填充。
远程发送方正常断开连接。
连接由 WSK 应用程序或远程发送方中止断开连接。
指定的 IRP 已取消。

Microsoft TCP/IP 传输协议支持此标志。其他传输协议可能不支持此标志。

WSK_FLAG_DRAIN

等待套接字断开连接，丢弃套接字上收到的任何数据。如果指定了此标志，则在发生以下事件之一之前，指定的 IRP 将不会完成：

远程发送方正常断开连接。
连接由 WSK 应用程序或远程发送方中止断开连接。
指定的 IRP 已取消。

WSK 子系统会丢弃任何收到的数据。不会将数据复制到数据缓冲区中。指定此标志时，仍需要 Buffer 参数，但WSK_BUF结构描述的缓冲区长度必须为零。

Microsoft TCP/IP 传输协议支持此标志。其他传输协议可能不支持此标志。

WSK_FLAG_WAITALL和WSK_FLAG_DRAIN标志互斥。 WSK 应用程序不应同时指定这两个标志。

[in, out] Irp

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

返回值

WskReceive 返回以下 NTSTATUS 代码之一：

返回代码	描述
STATUS_SUCCESS	已成功从套接字接收数据。 IRP 将以成功状态完成。 IRP IoStatus.Information 字段包含收到的字节数。
STATUS_PENDING	WSK 子系统无法立即从套接字接收数据。 WSK 子系统在从套接字接收数据后将完成 IRP。接收作的状态将在 IRP 的 IoStatus.Status 字段中返回。如果作成功，则 IRP IoStatus.Information 字段将包含收到的字节数。
STATUS_FILE_FORCED_CLOSED	套接字不再正常工作。 IRP 将以失败状态完成。 WSK 应用程序必须调用 WskCloseSocket 函数才能尽快关闭套接字。
STATUS_NOT_SUPPORTED	基础网络传输不支持指定的标志。
其他状态代码	发生错误。 IRP 将以失败状态完成。

言论

WSK 应用程序只能对以前连接到远程传输地址的连接套接字或流套接字调用 WskReceive 函数。面向连接的套接字通过以下方法之一连接到远程传输地址：

WSK 应用程序通过调用 WskConnect 函数来连接套接字。
WSK 应用程序通过调用 WskSocketConnect 函数来创建、绑定和连接套接字。
当 WSK 应用程序接受侦听套接字上的传入连接请求时，WSK 子系统会连接套接字。

如果 WSK 应用程序的 WskReceiveEvent 事件回调函数在面向连接的套接字上启用，并且应用程序还对同一连接导向套接字上的 WskReceive 函数具有挂起调用，然后，当数据到达时，对 WskReceive 函数的挂起调用将优先于 WskReceiveEvent 事件回调函数。仅当没有从挂起调用到 WskReceive 函数的 IRP 时，WSK 子系统才会调用应用程序的 WskReceiveEvent 事件回调函数。但是，WSK 应用程序不应假定 WSK 子系统不会调用应用程序的 WskReceiveEvent 事件回调函数，该套接字具有对 WskReceive 函数的挂起调用。存在争用条件，其中 WSK 子系统仍可以调用 WSK 应用程序的 WskReceiveEvent 套接字的事件回调函数。 WSK 应用程序确保 WSK 子系统不会为面向连接的套接字调用应用程序的 WskReceiveEvent 事件回调函数的唯一方法是禁用应用程序的 WskReceiveEvent 套接字上的事件回调函数。

WSK 应用程序可以调用 WskReceive 函数，该函数在 Buffer 参数指向的 WSK_BUF 结构的 Length 成员中指定的长度为零。在以下情况下，在此成员中指定零长度非常有用：

重新启用 WskReceiveEvent 套接字的事件回调函数后，WskReceiveEvent 事件回调函数之前返回STATUS_DATA_NOT_ACCEPTED
指定WSK_FLAG_DRAIN标志以放弃套接字上接收的任何其他数据

如果 WskReceive 函数返回STATUS_PENDING，则在 IRP 完成之前，Buffer 参数指向的WSK_BUF结构中所述的 MDL 链必须保持锁定在内存中。

要求

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