RIO_NOTIFICATION_COMPLETION 結構 (mswsock.h)

發行項
03/05/2024

RIO_NOTIFICATION_COMPLETION 結構會指定要搭配RIONotify 函式使用的 I/O 完成方法，以使用 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

I/O 完成埠的句柄，用於佇列 RIONotify 要求完成。

當 Type 成員設定為 RIO_IOCP_COMPLETION 時，這個值是有效的。

Iocp.CompletionKey

在佇列RIONotify 要求時，GetQueuedCompletionStatus 或 GetQueuedCompletionStatusEx 函式所傳回的 lpCompletionKey 參數所使用的值。

當 Type 成員設定為 RIO_IOCP_COMPLETION 時，這個值是有效的。

Iocp.Overlapped

在排入RIONotify 要求完成佇列時所要使用的重疊結構的指標。這個成員必須指向有效的 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 清除事件物件，這可能會導致等候物件回呼的假性執行。

規格需求

需求	值
最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
標頭	mswsock.h