PFN_WSK_RECEIVE回调函数 (wsk.h)

项目
08/08/2023

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

一个 ULONG 值，该值包含以下标志的组合的按位 OR：

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

指向调用方分配的 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 子系统不会为具有对 WskReceive 函数的挂起调用的面向连接的套接字调用 应用程序的 WskReceiveEvent 事件回调函数。存在争用条件，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，则 Buffer 参数指向的 WSK_BUF 结构中描述的 MDL 链必须在内存中保持锁定状态，直到 IRP 完成。

要求

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