LPFN_RIORECEIVE Rückruffunktion (mswsock.h)

Die RIOReceive-Funktion empfängt Netzwerkdaten auf einem verbundenen registrierten E/A-TCP-Socket oder einem gebundenen registrierten E/A-UDP-Socket zur Verwendung mit den registrierten Winsock-E/A-Erweiterungen.

Syntax

LPFN_RIORECEIVE LpfnRioreceive;

BOOL LpfnRioreceive(
  RIO_RQ SocketQueue,
  PRIO_BUF pData,
  ULONG DataBufferCount,
  DWORD Flags,
  PVOID RequestContext
)
{...}

Parameter

SocketQueue

Ein Deskriptor, der einen verbundenen registrierten E/A-TCP-Socket oder einen gebundenen registrierten E/A-UDP-Socket identifiziert.

pData

Eine Beschreibung des Teils des registrierten Puffers, in dem Daten empfangen werden sollen.

Dieser Parameter kann null für einen gebundenen registrierten E/A-UDP-Socket sein, wenn die Anwendung die Datennutzlast im UDP-Datagramm nicht empfangen muss.

DataBufferCount

Ein Datenpufferanzahlparameter, der angibt, ob Daten im Puffer empfangen werden sollen, auf den der pData-Parameter verweist.

Dieser Parameter sollte auf null festgelegt werden, wenn pData NULL ist. Andernfalls sollte dieser Parameter auf 1 festgelegt werden.

Flags

Ein Satz von Flags, die das Verhalten der RIOReceive-Funktion ändern.

Der Flags-Parameter kann eine Kombination der folgenden Optionen enthalten, die in der Mswsockdef.h Headerdatei definiert sind:

RIO_MSG_COMMIT_ONLY

Vorherige Anforderungen, die mit RIO_MSG_DEFER Flag hinzugefügt wurden, werden committet.

Wenn das RIO_MSG_COMMIT_ONLY-Flag festgelegt ist, können keine anderen Flags angegeben werden. Wenn das RIO_MSG_COMMIT_ONLY-Flag festgelegt ist, müssen die Argumente pData und RequestContext NULL und das Argument DataBufferCount null sein.

Dieses Flag wird in der Regel gelegentlich verwendet, nachdem eine Reihe von Anforderungen mit festgelegtem RIO_MSG_DEFER-Flag ausgegeben wurde. Dadurch entfällt die Notwendigkeit, wenn sie das RIO_MSG_DEFER-Flag verwenden, um die letzte Anforderung ohne das RIO_MSG_DEFER-Flag auszuführen, was dazu führt, dass die letzte Anforderung viel langsamer abgeschlossen wird als andere Anforderungen.

Im Gegensatz zu anderen Aufrufen der RIOReceive-Funktion müssen Aufrufe der RIOReceive-Funktion nicht serialisiert werden, wenn das RIO_MSG_COMMIT_ONLY Flag festgelegt ist. Für einen einzelnen RIO_RQ kann die RIOReceive-Funktion mit RIO_MSG_COMMIT_ONLY in einem Thread aufgerufen werden, während die RIOReceive-Funktion in einem anderen Thread aufgerufen wird.

RIO_MSG_DONT_NOTIFY

Die Anforderung sollte die RIONotify-Funktion nicht auslösen, wenn der Abschluss der Anforderung in die Vervollständigungswarteschlange eingefügt wird.

RIO_MSG_DEFER

Die Anforderung muss nicht sofort ausgeführt werden. Dadurch wird die Anforderung in die Anforderungswarteschlange eingefügt, aber möglicherweise wird die Ausführung der Anforderung ausgelöst.

Der Datenempfang kann verzögert werden, bis eine Empfangsanforderung für die RIO_RQ erfolgt, die im SocketQueue-Parameter übergeben wird, ohne dass das RIO_MSG_DEFER-Flag festgelegt ist. Um die Ausführung für alle Empfange in einer Anforderungswarteschlange auszulösen, rufen Sie die RIOReceive - oder RIOReceiveEx-Funktion auf, ohne dass das flag RIO_MSG_DEFER festgelegt ist.

Hinweis

Die Empfangsanforderung wird mit der ausstehenden E/A-Kapazität für die im SocketQueue-Parameter übergebene RIO_RQ berechnet, unabhängig davon, ob RIO_MSG_DEFER festgelegt ist.

RIO_MSG_WAITALL

Die RIOReceive-Funktion wird erst abgeschlossen, wenn eines der folgenden Ereignisse auftritt:

• Das vom Aufrufer im pData-Parameter bereitgestellte Puffersegment ist vollständig voll.
• Die Verbindung wurde geschlossen.
• Die Anforderung wurde abgebrochen, oder es ist ein Fehler aufgetreten.

Dieses Flag wird für UDP-Sockets nicht unterstützt.

RequestContext

Der Anforderungskontext, der diesem Empfangsvorgang zugeordnet werden soll.

Rückgabewert

Wenn kein Fehler auftritt, gibt die RIOReceive-FunktionTRUE zurück. In diesem Fall wird der Empfangsvorgang erfolgreich initiiert, und der Abschluss wurde bereits in die Warteschlange gestellt, oder der Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt in die Warteschlange gestellt.

Der Wert FALSE gibt an, dass die Funktion fehlgeschlagen ist, der Vorgang nicht erfolgreich initiiert wurde und keine Abschlussanzeige in die Warteschlange eingereiht wird. Ein bestimmter Fehlercode kann durch Aufrufen der WSAGetLastError-Funktion abgerufen werden.

Rückgabecode	Beschreibung
WSAEFAULT	Das System hat beim Versuch, ein Zeigerargument in einem Aufruf zu verwenden, eine ungültige Zeigeradresse erkannt. Dieser Fehler wird zurückgegeben, wenn die Registrierung eines Pufferbezeichners aufgehoben oder ein Puffer für eine der RIO_BUF Strukturen freigegeben wird, die in Parametern übergeben werden, bevor der Vorgang in die Warteschlange eingereiht oder aufgerufen wird.
WSAEINVAL	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn der SocketQueue-Parameter ungültig ist, der Flags-Parameter einen Wert enthält, der für einen Empfangsvorgang ungültig ist oder die Integrität der Abschlusswarteschlange gefährdet wurde. Dieser Fehler kann auch für andere Probleme mit Parametern zurückgegeben werden.
WSAENOBUFS	Es konnte kein ausreichender Arbeitsspeicher zugewiesen werden. Dieser Fehler wird zurückgegeben, wenn die E/A-Vervollständigungswarteschlange, die dem SocketQueue-Parameter zugeordnet ist, voll ist oder die E/A-Vervollständigungswarteschlange mit null Empfangseinträgen erstellt wurde.
WSA_OPERATION_ABORTED	Der Vorgang wurde abgebrochen, während der Empfangsvorgang ausstehend war. Dieser Fehler wird zurückgegeben, wenn der Socket lokal oder remote geschlossen wird oder der befehl SIO_FLUSH in WSAIoctl für diesen Socket ausgeführt wird.

Hinweise

Eine Anwendung kann die RIOReceive-Funktion verwenden, um Netzwerkdaten in einen puffer zu empfangen, der vollständig in einem einzelnen registrierten Puffer enthalten ist. Die Elemente Offset und Length der RIO_BUF Struktur, auf die der pData-Parameter verweist, bestimmen, wo die Netzwerkdaten im Puffer empfangen werden.

Nachdem die RIOReceive-Funktion aufgerufen wurde, muss der im pData-Parameter übergebene Puffer einschließlich des RIO_BUFFERID im BufferId-MemberRIO_BUF Struktur für die Dauer des Empfangsvorgangs gültig bleiben.

Um Racebedingungen zu vermeiden, sollte ein Puffer, der einer Empfangsanforderung zugeordnet ist, nicht gelesen oder geschrieben werden, bevor die Anforderung abgeschlossen ist. Dies umfasst die Verwendung des Puffers als Quelle für eine Sendeanforderung oder das Ziel für eine andere Empfangsanforderung. Teile eines registrierten Puffers, die keiner Empfangsanforderung zugeordnet sind, sind in dieser Einschränkung nicht enthalten.

Der Flags-Parameter kann verwendet werden, um das Verhalten des RIOReceive-Funktionsaufrufs über die für den zugeordneten Socket angegebenen Optionen hinaus zu beeinflussen. Das Verhalten dieser Funktion wird durch eine Kombination aller Socketoptionen bestimmt, die für den Socket festgelegt sind, der dem SocketQueue-Parameter zugeordnet ist, und den im Flags-Parameter angegebenen Werten.

Hinweis

Der Funktionszeiger auf die RIOReceive-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.

Anforderungen

Anforderung	Wert
Header	mswsock.h