ProcessSocketNotifications-Funktion (winsock2.h)

Artikel
08/27/2023

Ordnet einen Satz von Sockets einem Abschlussport zu und ruft alle Benachrichtigungen ab, die für diesen Port bereits ausstehen. Nach der Zuordnung empfängt der Abschlussport die angegebenen Socketstatusbenachrichtigungen. Es werden nur Microsoft Winsock-Anbietersockock-Sockets unterstützt.

Um den Mehraufwand für Systemaufrufe zu reduzieren, können Sie sich für Benachrichtigungen registrieren und diese in einem einzigen Aufruf von ProcessSocketNotifications abrufen. Alternativ können Sie sie explizit abrufen, indem Sie die üblichen E/A-Abschlussportfunktionen aufrufen, z. B. GetQueuedCompletionStatus. Benachrichtigungen, die mithilfe von ProcessSocketNotifications abgerufen werden, sind identisch mit denen, die mit GetQueuedCompletionStatusEx abgerufen werden. Dies kann andere Benachrichtigungspakete als Socketzustandsänderungen enthalten.

Die Benachrichtigungsereignisflags sind der ganzzahlige Wert der dwNumberOfBytesTransferred-Felder der zurückgegebenen OVERLAPPED_ENTRY-Strukturen . Dies ähnelt der Verwendung von JOBOBJECT_ASSOCIATE_COMPLETION_PORT, die auch das Feld dwNumberOfBytesTransferred zum Senden ganzzahliger Nachrichten verwendet. Rufen Sie die SocketNotificationRetrieveEvents-Funktion auf, um sie abzurufen.

Ein Sockethandle kann jeweils nur bei einem IOCP registriert werden. Die erneute Registrierung eines zuvor registrierten Sockethandles überschreibt die vorhandene Registrierung. Bevor Sie ein für die Registrierung verwendetes Handle schließen, sollten Sie die Registrierung explizit entfernen und auf die SOCK_NOTIFY_EVENT_REMOVE-Benachrichtigung warten (siehe Hinweise in diesem Thema).

Weitere Informationen und Codebeispiele finden Sie unter Winsock-Socketstatusbenachrichtigungen.

Syntax

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

Parameter

completionPort

Typ: _In_ HANDLE

Ein Handle für einen E/A-Vervollständigungsport, der mit der CreateIoCompletionPort-Funktion erstellt wurde. Der Port wird im CompletionPort-Parameter der PostQueuedCompletionStatus-Funktion verwendet, wenn Nachrichten im Namen des Sockets gesendet werden.

registrationCount

Typ: _In_ UINT32

Die Anzahl der Registrierungen, die von registrationInfos bereitgestellt werden.

registrationInfos

Typ: _Inout_updates_opt_(registrationCount) SOCK_NOTIFY_REGISTRATION*

Ein Zeiger auf ein Array von SOCK_NOTIFY_REGISTRATION Strukturen, die die Parameter für die Benachrichtigungsregistrierung definieren. Dazu gehören die Socket of Interest, die relevanten Benachrichtigungsereignisse und die Vorgangsflags. Bei erfolgreicher Ausführung müssen Sie die Elemente überprüfen, ob die Registrierung erfolgreich verarbeitet wurde. Dieses Argument muss NULL sein, wenn registrationCount den Wert 0 aufweist.

timeoutMs

Typ: _In_ UINT32

Die Zeit in Millisekunden, in der Sie bereit sind, auf das Erscheinen eines Abschlusspakets am Abschlussport zu warten. Wenn ein Vervollständigungspaket nicht innerhalb der angegebenen Zeit angezeigt wird, gibt die Funktion ein Timeout zurück und gibt ERROR_TIMEOUT zurück.

Wenn timeoutMsINFINITE (0xFFFFFFFF) ist, wird für die Funktion kein Timeout ausgeführt. Wenn timeoutMs 0 ist und kein E/A-Vorgang aus der Warteschlange verschoben werden muss, wird für die Funktion sofort ein Timeout ausgeführt.

Der Wert von timeoutMs muss 0 sein, wenn completionCount auf 0 festgelegt ist.

completionCount

Typ: _In_ ULONG

Die maximale Anzahl der zu entfernenden OVERLAPPED_ENTRY Strukturen. Wenn 0 angegeben ist, werden nur Registrierungsvorgänge verarbeitet.

completionPortEntries

Typ: _Out_writes_to_opt_(completionCount, *receivedEntryCount) OVERLAPPED_ENTRY*

Zeigt bei der Eingabe auf ein vorab zugewiesenes Array von Strukturen OVERLAPPED_ENTRY. Das Array darf sich nicht mit dem RegistrationInfos-Array überschneiden. Der Wert von completionPortEntries muss NULL sein, wenn completionCount 0 ist.

Empfängt bei der Ausgabe ein Array von Strukturen OVERLAPPED_ENTRY, die die Einträge enthalten. Die Anzahl der Arrayelemente wird von ReceivedEntryCount bereitgestellt. Die dwNumberOfBytesTransferred-Felder der Strukturen sind ganzzahlige Masken empfangener Ereignisse. Die lpOverlapped-Felder sind reserviert und dürfen nicht als Zeiger verwendet werden.

receivedEntryCount

Typ: _Out_opt_ UINT32*

Ein Zeiger auf eine Variable, die die Anzahl der entfernten Einträge empfängt. Muss NULL sein, wenn completionCount 0 ist.

Rückgabewert

Bei erfolgreicher Ausführung wird ERROR_SUCCESS zurückgegeben. Wenn die Funktion erfolgreich war und Sie einen completionCount ungleich 0 angegeben haben, aber innerhalb der angegebenen Zeit keine Abschlusspakete angezeigt wurden, gibt WAIT_TIMEOUT zurück. Andernfalls wird ein entsprechender WSAE* -Fehlercode zurückgegeben.

Wenn ERROR_SUCCESS oder WAIT_TIMEOUT zurückgegeben wird, müssen Sie die Registrierungsergebnisse der einzelnen Registrierungsinformationen einsehen. Andernfalls ist der gesamte Vorgang fehlgeschlagen, und es sind keine Änderungen aufgetreten.

Hinweise

Informationen zu den Ereignissen, die beim Empfang einer Benachrichtigung möglich sind, finden Sie unter SocketNotificationRetrieveEvents .

Anforderungen


Unterstützte Mindestversion (Client)	Windows 10 Build 20348
Unterstützte Mindestversion (Server)	Windows 10 Build 20348
Kopfzeile	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll

Share via