PFN_WSK_RECEIVE_FROM回调函数 (wsk.h)

项目
08/08/2023

WskReceiveFrom 函数从远程传输地址接收数据报和任何关联的控制信息。

语法

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

参数

[in] Socket

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

[in] Buffer

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

Flags

此参数保留供系统使用。 WSK 应用程序必须将此参数设置为零。

[out, optional] RemoteAddress

指向调用方分配的缓冲区的指针，该缓冲区接收接收接收的数据报源自的远程传输地址。缓冲区必须位于非分页内存中。缓冲区还必须足够大，以包含与 WSK 应用程序在创建数据报套接字时指定的地址系列相对应的特定 SOCKADDR 结构类型。此指针是可选的，可以为 NULL。

[in, out] ControlLength

指向 ULONG 的指针，指定 ControlInfo 参数指向的缓冲区的大小。接收操作完成后，变量接收与接收的数据报关联的控件信息的大小。如果返回的值为零，则不存在用于数据报的控制信息。此指针是可选的，可以为 NULL。如果此参数为 NULL，则忽略 ControlInfo 参数。

[out, optional] ControlInfo

指向调用方分配的缓冲区的指针，该缓冲区接收与接收的数据报关联的控制信息。与数据报关联的控件信息数据由一个或多个控件数据对象组成，每个对象都以 CMSGHDR 结构开头。如果收到的数据报没有控制信息，则缓冲区的内容未定义。此指针是可选的，可以为 NULL。如果 ControlInfoLength 参数为 NULL，则 ControlInfo 参数应为 NULL。

[out, optional] ControlFlags

指向 ULONG 类型变量的指针，该变量接收以下标志组合的按位 OR：

MSG_BCAST

数据报是作为链接层广播接收的，或者接收了作为广播地址的目标传输地址。

MSG_MCAST

接收数据报的目标传输地址是多播地址。

MSG_TRUNC

数据报被截断，因为数据报的大小大于 Buffer 参数指定的缓冲区大小。

MSG_CTRUNC

控件信息数据被截断，因为控制信息的字节数大于 ControlInfo 参数指定的缓冲区大小。

此参数是可选的，可以为 NULL。

[in, out] Irp

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

返回值

WskReceiveFrom 返回以下 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 函数以尽快关闭套接字。
其他状态代码	出现了错误。 IRP 将以失败状态完成。

注解

如果 WSK 应用程序已为数据报套接字设置了固定的远程传输地址，则 WSK 子系统将丢弃从任何其他远程传输地址接收的数据报。有关为数据报套接字设置远程传输地址的详细信息，请参阅 SIO_WSK_SET_REMOTE_ADDRESS。

如果 WSK 应用程序的 WskReceiveFromEvent 事件回调函数在数据报套接字上启用，并且应用程序对同一数据报套接字上的 WskReceiveFrom 函数也有挂起调用，则当数据报到达时，对 WskReceiveFrom 函数的挂起调用将优先于 WskReceiveFromEvent 事件回调函数。仅当没有 IRP 排队等待 WskReceiveFrom 函数的调用时，WSK 子系统才调用应用程序的 WskReceiveFromEvent 事件回调函数。但是，WSK 应用程序不应假定 WSK 子系统不会为对 WskReceiveFrom 函数具有挂起调用的数据报套接字调用 应用程序的 WskReceiveFromEvent 事件回调函数。存在争用条件，WSK 子系统仍可以为套接字调用 WSK 应用程序的 WskReceiveFromEvent 事件回调函数。 WSK 应用程序确保 WSK 子系统不会在数据报套接字上调用应用程序的 WskReceiveFromEvent 事件回调函数的唯一方法是在套接字上禁用应用程序的 WskReceiveFromEvent 事件回调函数。

如果 WskReceiveFrom 函数返回STATUS_PENDING，则 Buffer 参数指向的 WSK_BUF 结构中所述的 MDL 链必须在内存中保持锁定状态，直到 IRP 完成。此外， ControlInfoLength 参数指向的变量、 ControlInfo 参数指向的缓冲区以及 ControlFlags 参数指向的变量也必须保持有效，直到 IRP 完成。如果 WSK 应用程序使用 ExAllocateXxx 函数之一分配了这些缓冲区或变量，则在 IRP 完成之前，它无法使用相应的 ExFreeXxx 函数释放内存。如果 WSK 应用程序在堆栈上分配了这些缓冲区或变量，则在 IRP 完成之前，它无法从调用 WskReceiveFrom 函数的函数返回。

要求

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