ProcessSocketNotifications 函式 (winsock2.h)

  • 發行項

建立一組通訊端與完成埠的關聯，並擷取該埠上已擱置的任何通知。 一旦相關聯，完成埠就會接收指定的通訊端狀態通知。 僅支援 Microsoft Winsock 提供者通訊端。

若要減少系統呼叫額外負荷，您可以註冊通知，並在 對 ProcessSocketNotifications的單一呼叫中擷取通知。 或者，您可以藉由呼叫一般的 I/O 完成埠函式，例如 GetQueuedCompletionStatus來明確擷取它們。 使用 ProcessSocketNotifications 擷取的通知，與使用 GetQueuedCompletionStatusEx擷取的通知相同，這可能包含通訊端狀態變更以外的通知封包。

通知事件旗標是傳回之OVERLAPPED_ENTRY結構的dwNumberOfBytesTransferred欄位的整數值。 這類似于使用 JOBOBJECT_ASSOCIATE_COMPLETION_PORT，這也會使用 dwNumberOfBytesTransferred 欄位來傳送整數訊息。 呼叫 SocketNotificationRetrieveEvents 函式 以取得它們。

通訊端控制碼一次只能註冊到一個 IOCP。 重新註冊先前註冊的通訊端控制碼會覆寫現有的註冊。 Before you close a handle used for registration, you should explicitly remove registration, and wait for the SOCK_NOTIFY_EVENT_REMOVE notification (see Remarks in this topic).

如需詳細資訊和程式碼範例，請參閱 Winsock 通訊端狀態通知。

語法

DWORD WSAAPI ProcessSocketNotifications(
  HANDLE                   completionPort,
  UINT32                   registrationCount,
  SOCK_NOTIFY_REGISTRATION *registrationInfos,
  UINT32                   timeoutMs,
  ULONG                    completionCount,
  OVERLAPPED_ENTRY         *completionPortEntries,
  UINT32                   *receivedEntryCount
);

參數

completionPort

類型：_In_ HANDLE

使用 CreateIoCompletionPort 函式所建立之 I/O 完成埠的控制碼。 當訊息代表通訊端傳送時，PostQueuedCompletionStatus函式的CompletionPort參數會使用埠。

registrationCount

類型：_In_ UINT32

registrationInfos 所提供的註冊數目。

registrationInfos

類型：_Inout_updates_opt_ (registrationCount) SOCK_NOTIFY_REGISTRATION*

定義通知註冊參數 之SOCK_NOTIFY_REGISTRATION 結構的陣列指標。 其中包括感興趣的通訊端、感興趣的通知事件，以及作業旗標。 成功時，您必須檢查項目是否已成功處理註冊。 如果registrationCount為 0，這個引數必須是Null。

timeoutMs

類型：_In_ UINT32

您願意等候完成封包出現在完成埠的時間，以毫秒為單位。 如果完成封包未出現在指定的時間內，則函式會逾時並傳回 ERROR_TIMEOUT。

如果 timeoutMs 是 INFINITE (0xFFFFFFFF) ，則函式永遠不會逾時。如果 timeoutm 為 0，而且沒有 I/O 作業可取消佇列，則函式會立即逾時。

如果completionCount為 0，則 timeoutMs的值必須是 0。

completionCount

類型：_In_ ULONG

要移除的 OVERLAPPED_ENTRY 結構數目上限。 如果指定 0，則只會處理註冊作業。

completionPortEntries

類型：_Out_writes_to_opt_ (completionCount、*receivedEntryCount) OVERLAPPED_ENTRY*

在輸入上，指向預先配置的 OVERLAPPED_ENTRY 結構陣列。 陣列不得與 registrationInfos 陣列重迭。 如果 completionCount 為 0，則 completionPortEntries的值必須是Null。

在輸出上，接收保存專案之OVERLAPPED_ENTRY結構的陣列。 ReceivedEntryCount 提供陣列元素的數目。 結構的 dwNumberOfBytesTransferred 欄位是已接收事件的整數遮罩。 lpOverlapped 欄位是保留的，不能當做指標使用。

receivedEntryCount

類型：_Out_opt_ UINT32*

接收已移除專案數目之變數的指標。 如果completionCount為 0，則必須為Null。

傳回值

如果成功，則會傳回 ERROR_SUCCESS。 如果函式成功，而且您提供了非 0 completionCount，但未在指定時間內出現完成封包，則會傳回 WAIT_TIMEOUT。 否則，傳回適當的 WSAE* 錯誤碼。

如果 傳回ERROR_SUCCESS 或 WAIT_TIMEOUT ，則必須檢查個別的註冊資訊註冊結果。 否則，整個作業失敗，而且不會發生任何變更。

備註

如需收到通知時可能的事件，請參閱 SocketNotificationRetrieveEvents 。

規格需求

   
最低支援的用戶端 Windows 10組建 20348
最低支援的伺服器 Windows 10組建 20348
標頭 winsock2.h
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱