RIO_NOTIFICATION_COMPLETION 结构 (mswsock.h)

项目
08/25/2023

RIO_NOTIFICATION_COMPLETION 结构指定用于 I/O 完成的方法与 RIONotify 函数一起使用，以便通过 Winsock 注册的 I/O 扩展发送或接收网络数据。

语法

typedef struct _RIO_NOTIFICATION_COMPLETION {
  RIO_NOTIFICATION_COMPLETION_TYPE Type;
  union {
    struct {
      HANDLE EventHandle;
      BOOL   NotifyReset;
    } Event;
    struct {
      HANDLE IocpHandle;
      PVOID  CompletionKey;
      PVOID  Overlapped;
    } Iocp;
  };
} RIO_NOTIFICATION_COMPLETION, *PRIO_NOTIFICATION_COMPLETION;

成员

Type

发送或接收数据时要与 RIONotify 函数一起使用的完成类型。

Event

Event.EventHandle

在完成 RIONotify 请求后要设置的事件的句柄。

当 Type 成员设置为 RIO_EVENT_COMPLETION 时，此值有效。

Event.NotifyReset

导致在调用 RIONotify 函数时重置关联事件的布尔值。非零值会导致重置关联的事件。

当 Type 成员设置为 RIO_EVENT_COMPLETION 时，此值有效。

Iocp

Iocp.IocpHandle

用于排队 RIONotify 请求完成的 I/O 完成端口的句柄。

当 Type 成员设置为 RIO_IOCP_COMPLETION 时，此值有效。

Iocp.CompletionKey

在排队 RIONotify 请求时，GetQueuedCompletionStatus 或 GetQueuedCompletionStatusEx 函数返回的 lpCompletionKey 参数的值。

当 Type 成员设置为 RIO_IOCP_COMPLETION 时，此值有效。

Iocp.Overlapped

指向在排队 RIONotify 请求完成时要使用的 OVERLAPPED 结构的指针。此成员必须指向有效的 OVERLAPPED 结构。

当 Type 成员设置为 RIO_IOCP_COMPLETION 时，此值有效。

注解

RIO_NOTIFICATION_COMPLETION 结构用于指定与 Winsock 注册的 I/O 扩展一起使用的 RIONotify 函数的行为。

创建RIO_CQ时，RIO_NOTIFICATION_COMPLETION结构将传递给 RIOCreateCompletionQueue 函数。如果应用程序不为完成队列调用 RIONotify 函数，则可以在没有 RIO_NOTIFICATION_COMPLETION 对象的情况下创建完成队列。

对于使用事件的完成队列，RIO_NOTIFICATION_COMPLETION 结构的 Type 成员设置为 RIO_EVENT_COMPLETION。 RIO_NOTIFICATION_COMPLETION 结构的 Event.EventHandle 成员应包含由 WSACreateEvent 或 CreateEvent 函数创建的事件的句柄。若要接收 RIONotify 完成，应用程序应使用 WSAWaitForMultipleEvents 或类似的等待例程等待指定的事件句柄。如果应用程序计划重置并重复使用事件，则应用程序可以通过将RIO_NOTIFICATION_COMPLETION结构的 Event.NotifyReset 成员设置为非零值来减少开销。这会导致发生通知时 ，RIONotify 函数重置事件。这可减少调用 WSAResetEvent 函数以在调用 RIONotify 函数之间重置事件的需求。

对于使用 I/O 完成端口的完成队列，RIO_NOTIFICATION_COMPLETION 结构的 Type 成员设置为 RIO_IOCP_COMPLETION。 RIO_NOTIFICATION_COMPLETION 结构的 Iocp.IocpHandle 成员应包含 CreateIoCompletionPort 函数创建的 I/O 完成端口的句柄。若要接收 RIONotify 完成，应用程序应调用 GetQueuedCompletionStatus 或 GetQueuedCompletionStatusEx 函数。应用程序应为完成队列提供专用的 OVERLAPPED 对象，并且它还可以使用 Iocp.CompletionKey 成员将完成队列上的 RIONotify 请求与其他 I/O 完成请求（包括其他完成队列的 RIONotify 完成）区分开来。

使用线程池的应用程序可以使用线程池等待对象通过其线程池获取 RIONotify 完成。在这种情况下，对 SetThreadpoolWait 函数的调用应立即跟随对 RIONotify 的调用。如果在 RIONotify 之前调用 SetThreadpoolWait 函数，并且应用程序依赖于 RIONotify 来清除事件对象，则可能会导致等待对象回调的虚假执行。