LPFN_RIONOTIFY Rückruffunktion (mswsock.h)

  • Artikel

Die RIONotify-Funktion registriert die Methode, die für das Benachrichtigungsverhalten bei einer E/A-Vervollständigungswarteschlange für die Verwendung mit den registrierten Winsock-E/A-Erweiterungen verwendet werden soll.

Syntax

LPFN_RIONOTIFY LpfnRionotify;

INT LpfnRionotify(
  RIO_CQ CQ
)
{...}

Parameter

CQ

Ein Deskriptor, der eine E/A-Vervollständigungswarteschlange identifiziert.

Rückgabewert

Wenn kein Fehler auftritt, gibt die RIONotify-FunktionERROR_SUCCESS zurück. Andernfalls ist die Funktion fehlgeschlagen, und ein bestimmter Fehlercode wird zurückgegeben.

Rückgabecode Beschreibung
WSAEINVAL
 Es wurde ein ungültiger Parameter an die Funktion übergeben.
Dieser Fehler wird zurückgegeben, wenn eine ungültige Vervollständigungswarteschlange im CQ-Parameter übergeben wird (z. B. RIO_INVALID_CQ). Dieser Fehler kann auch zurückgegeben werden, wenn ein interner Fehler auftritt.
WSAEALREADY
 Es wurde versucht, für einen nicht blockierenden Socket, für den bereits ein Vorgang ausgeführt wurde, einen weiteren Vorgang auszuführen.
Dieser Fehler wird zurückgegeben, wenn eine vorherige RIONotify-Anforderung noch nicht abgeschlossen wurde.

Hinweise

Die RIONotify-Funktion registriert die Methode, die für das Benachrichtigungsverhalten zum Senden oder Empfangen von Netzwerkdaten mit den registrierten Winsock-E/A-Erweiterungen verwendet werden soll.

Die RIONotify-Funktion ist der Mechanismus, mit dem eine Anwendung feststellt, dass Anforderungen abgeschlossen sind und auf einen Aufruf der RIODequeueCompletion-Funktion warten. Die RIONotify-Funktion legt die Methode fest, die für das Benachrichtigungsverhalten verwendet werden soll, wenn eine E/A-Abschlusswarteschlange nicht leer ist, und enthält den Abschluss eines Ergebnisses.

Das Benachrichtigungsverhalten für eine Vervollständigungswarteschlange wird festgelegt, wenn die RIO_CQ erstellt wird. Die RIO_NOTIFICATION_COMPLETION-Struktur wird an die RIOCreateCompletionQueue-Funktion übergeben, wenn ein RIO_CQ erstellt wird.

Für eine Vervollständigungswarteschlange, die ein Ereignis verwendet, wird das Type-Element der RIO_NOTIFICATION_COMPLETION-Struktur auf RIO_EVENT_COMPLETION festgelegt. Das Event.EventHandle-Element sollte das Handle für ein Ereignis enthalten, das von der WSACreateEvent - oder CreateEvent-Funktion erstellt wurde. Um die RIONotify-Vervollständigung zu erhalten, sollte die Anwendung mithilfe von WSAWaitForMultipleEvents oder einer ähnlichen Warteroutine auf das angegebene Ereignishandle warten. Wenn die Anwendung plant, das Ereignis zurückzusetzen und wiederzuverwenden, kann die Anwendung den Mehraufwand reduzieren, indem das Event.NotifyReset-Element auf einen Wert ungleich 0 festgelegt wird. Dies bewirkt, dass das Ereignis automatisch von der RIONotify-Funktion zurückgesetzt wird, wenn die Benachrichtigung auftritt. Dadurch entfällt die Notwendigkeit, die WSAResetEvent-Funktion aufzurufen, um das Ereignis zwischen Aufrufen der RIONotify-Funktion zurückzusetzen.

Wenn die RIONotify-Funktion verwendeter Ereignisvervollständigung aufgerufen wird und die angegebene Abschlusswarteschlange bereits nicht leer ist, wird das Ereignis entweder synchron oder asynchron festgelegt. In beiden Fällen müssen zusätzliche Einträge nicht in die Vervollständigungswarteschlange eingegeben werden, bevor das Ereignis festgelegt wird. Bis die Vervollständigungswarteschlange den Abschluss einer Anforderung enthält, für die das Flag RIO_MSG_DONT_NOTIFY nicht festgelegt wurde, wird die Abschlusswarteschlange für die Zwecke der RIONotify-Funktion als leer betrachtet, und das Ereignis ist nicht festgelegt. Alle abgeschlossenen Anforderungen können weiterhin mithilfe der RIODequeueCompletion-Funktion abgerufen werden. Wenn das Ereignis festgelegt ist, ruft die Anwendung in der Regel die RIODequeueCompletion-Funktion auf, um die abgeschlossenen Sende- und Empfangsanforderungen aus der Warteschlange zu entfernen.

Für eine Vervollständigungswarteschlange, die einen E/A-Abschlussport verwendet, wird der Typmember der RIO_NOTIFICATION_COMPLETION-Struktur auf RIO_IOCP_COMPLETION festgelegt. Der Iocp.IocpHandle-Member sollte das Handle für einen E/A-Abschlussport enthalten, der von der CreateIoCompletionPort-Funktion erstellt wurde. Um die RIONotify-Vervollständigung zu erhalten, sollte die Anwendung die Funktion GetQueuedCompletionStatus OderGetQueuedCompletionStatusEx aufrufen. Die Anwendung sollte ein dediziertes OVERLAPPED-Objekt für die Abschlusswarteschlange bereitstellen, und sie kann auch das Iocp.CompletionKey-Element verwenden, um RIONotify-Anforderungen in der Abschlusswarteschlange von anderen E/A-Vervollständigungen zu unterscheiden, einschließlich RIONotify-Vervollständigungen für andere Abschlusswarteschlangen.

Eine Anwendung, die Threadpools verwendet, kann Threadpool-Wait-Objekte verwenden, um RIONotify-Vervollständigungen über ihren Threadpool abzurufen. In diesem Fall sollte der Aufruf der SetThreadpoolWait-Funktion sofort auf den Aufruf von RIONotify folgen. Wenn die SetThreadpoolWait-Funktion vor RIONotify aufgerufen wird und die Anwendung rioNotify verwendet, um das Ereignisobjekt zu löschen, kann dies zu falschen Ausführungen des Warteobjektrückrufs führen.

Hinweis

Der Funktionszeiger auf die RIONotify-Funktion muss zur Laufzeit abgerufen werden, indem die WSAIoctl-Funktion mit dem angegebenen SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER Opcode aufgerufen wird. Der an die WSAIoctl-Funktion übergebene Eingabepuffer muss WSAID_MULTIPLE_RIO enthalten, einen global eindeutigen Bezeichner (GUID), dessen Wert die von Winsock registrierten E/A-Erweiterungsfunktionen identifiziert. Bei Erfolg enthält die von der WSAIoctl-Funktion zurückgegebene Ausgabe einen Zeiger auf die RIO_EXTENSION_FUNCTION_TABLE-Struktur , die Zeiger auf die von Winsock registrierten E/A-Erweiterungsfunktionen enthält. Die SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL ist in der Ws2def.h-Headerdatei definiert. Die WSAID_MULTIPLE_RIO GUID ist in der Headerdatei Mswsock.h definiert.

 

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Threadsicherheit

Wenn mehrere Threads versuchen, mithilfe der RIODequeueCompletion-Funktion auf dieselbe RIO_CQ zuzugreifen, muss der Zugriff durch einen kritischen Abschnitt, eine Schreibsperre für schlanke Leser oder einen ähnlichen Mechanismus für gegenseitigen Ausschluss koordiniert werden. Wenn die Abschlusswarteschlangen nicht freigegeben werden, ist kein gegenseitiger Ausschluss erforderlich.

Anforderungen

Anforderung Wert
Header mswsock.h