LPFN_RIORECEIVEEX Rückruffunktion (mswsock.h)

  • Artikel

Die RIOReceiveEx-Funktion empfängt Netzwerkdaten auf einem verbundenen registrierten E/A-TCP-Socket oder einem gebundenen registrierten E/A-UDP-Socket mit zusätzlichen Optionen für die Verwendung mit den registrierten Winsock-E/A-Erweiterungen.

Syntax

LPFN_RIORECEIVEEX LpfnRioreceiveex;

int LpfnRioreceiveex(
                                                                                                                     RIO_RQ SocketQueue,
                                                                                                                     PRIO_BUF pData,
                                                                                                                     ULONG DataBufferCount,
                                                                                                                     PRIO_BUF pLocalAddress,
                                                                                                                     PRIO_BUF pRemoteAddress,
                                                                                                                     PRIO_BUF pControlContext,
                                                                                                                     PRIO_BUF pFlags,
                                                                                                                     DWORD Flags,
                                                                                                                     PVOID RequestContext
)
{...}

Parameter

SocketQueue

Ein Deskriptor, der einen verbundenen registrierten E/A-UDP-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 keine Datennutzlast im UDP-Datagramm 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.

pLocalAddress

Ein Puffersegment, das bei Abschluss die lokale Adresse enthält, an der die Netzwerkdaten empfangen wurden.

Dieser Parameter kann NULL sein, wenn die Anwendung die lokale Adresse nicht empfangen möchte. Wenn dieser Parameter nicht NULL ist, muss das Puffersegment mindestens die Größe einer SOCKADDR_INET-Struktur aufweisen.

pRemoteAddress

Ein Puffersegment, das bei Abschluss die Remoteadresse enthält, von der die Netzwerkdaten empfangen wurden.

Dieser Parameter kann NULL sein, wenn die Anwendung die Remoteadresse nicht empfangen möchte. Wenn dieser Parameter nicht NULL ist, muss das Puffersegment mindestens die Größe einer SOCKADDR_INET-Struktur aufweisen.

pControlContext

Ein Pufferslice, das nach Abschluss zusätzliche Steuerelementinformationen zum Empfangsvorgang enthält.

Dieser Parameter kann NULL sein, wenn die Anwendung die zusätzlichen Steuerelementinformationen nicht empfangen möchte.

pFlags

Flags

Eine Reihe von Flags, die das Verhalten der RIOReceiveEx-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 zu einem Commit ausgeführt.

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, pLocalAddress, pRemoteAddress, pControlContext, pFlags und RequestContext NULL sein, und das DataBufferCount-Argument muss 0 sein.

Dieses Flag wird normalerweise gelegentlich verwendet, nachdem eine Reihe von Anforderungen mit dem RIO_MSG_DEFER-Flag festgelegt wurde. Dadurch entfällt die Notwendigkeit, beim Verwenden des RIO_MSG_DEFER-Flags die letzte Anforderung ohne das RIO_MSG_DEFER-Flag zu stellen, was dazu führt, dass die letzte Anforderung viel langsamer abgeschlossen wird als andere Anforderungen.

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

RIO_MSG_DONT_NOTIFY

Die Anforderung sollte die RIONotify-Funktion nicht auslösen, wenn der Anforderungsabschluss 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 im SocketQueue-Parameter übergebene RIO_RQ ohne das RIO_MSG_DEFER-Flag festgelegt wird. Um die Ausführung für alle Empfange in einer Anforderungswarteschlange auszulösen, rufen Sie die RIOReceive - oder RIOReceiveEx-Funktion auf, ohne dass das RIO_MSG_DEFER-Flag festgelegt ist.

Hinweis

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

RIO_MSG_WAITALL

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

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

Dieses Flag wird für Datagrammsockets oder nachrichtenorientierte verbindungslose Sockets nicht unterstützt.

RequestContext

Der Anforderungskontext, der diesem Empfangsvorgang zugeordnet werden soll.

Rückgabewert

Wenn kein Fehler auftritt, gibt die RIOReceiveEx-FunktionTRUE zurück. In diesem Fall wird der Empfangsvorgang erfolgreich initiiert, und die Vervollständigung wurde bereits in die Warteschlange gestellt, oder der Vorgang wurde erfolgreich initiiert, und die Vervollständigung 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 Vervollständigungsanzeige in die Warteschlange gestellt 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 ein Pufferbezeichner für eine der RIO_BUF Strukturen freigegeben wird, die in Parametern übergeben werden, bevor der Vorgang in die Warteschlange gestellt 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 dwFlags-Parameter einen Wert enthält, der für einen Empfangsvorgang nicht gültig ist oder die Integrität der Vervollständigungswarteschlange gefährdet wurde. Dieser Fehler kann auch für andere Probleme mit Parametern zurückgegeben werden.
WSAENOBUFS Es konnte nicht genügend Arbeitsspeicher zugewiesen werden. Dieser Fehler wird zurückgegeben, wenn die E/A-Vervollständigungswarteschlange, die dem SocketQueue-Parameter zugeordnet ist, voll ist oder wenn 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 SIO_FLUSH-Befehl in WSAIoctl ausgeführt wird.

Hinweise

Eine Anwendung kann die RIOReceiveEx-Funktion verwenden, um Netzwerkdaten in jeden 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.

Sobald die RIOReceiveEx-Funktion aufgerufen wird, muss der Puffer, der im pData-Parameter übergeben wird, 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. Dazu gehört 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 Parameter pLocalAddress kann verwendet werden, um die lokale Adresse abzurufen, an der die Daten empfangen wurden. Der pRemoteAddress-Parameter kann verwendet werden, um die Remoteadresse abzurufen, von der die Daten empfangen wurden. Die lokalen Und Remoteadressen werden als SOCKADDR_INET-Strukturen zurückgegeben. Daher sollte das Length-Element der RIO_BUF , auf die die pLocalAddress- oder pRemoteAddress-Parameter verweisen, gleich oder größer als die Größe einer SOCKADDR_INET-Struktur sein.

In der folgenden Tabelle sind die verschiedenen Verwendungen von Steuerelementdaten zusammengefasst, die für die Verwendung mit den Steuerelementinformationen im pControlContext-Element verfügbar sind.

Protocol cmsg_level cmsg_type BESCHREIBUNG
IPv4 IPPROTO_IP IP_ORIGINAL_ARRIVAL_IF Empfängt die ursprüngliche IPv4-Ankunftsschnittstelle, über die das Paket für Datagrammsockets empfangen wurde. Diese Steuerungsdaten werden von Firewalls verwendet, wenn ein Teredo-, 6to4- oder ISATAP-Tunnel für den IPv4-NAT-Durchlauf verwendet wird.
Das cmsg_data[]-Member ist ein ULONG-Element, das die in der Headerdatei ifdef.h definierte IF_INDEX enthält.
Weitere Informationen finden Sie unter IPPROTO_IP Socketoptionen für die IP_ORIGINAL_ARRIVAL_IF-Socketoption.
IPv4 IPPROTO_IP IP_PKTINFO Gibt Paketinformationen an/empfängt sie.
Weitere Informationen finden Sie unter IPPROTO_IP Socketoptionen für die IP_PKTINFO Socketoption.
IPv6 IPPROTO_IPV6 IPV6_DSTOPTS Gibt Zieloptionen an/empfängt sie.
IPv6 IPPROTO_IPV6 IPV6_HOPLIMIT Gibt das Hoplimit an/empfängt.
Weitere Informationen finden Sie unter IPPROTO_IPV6 Socketoptionen für die IPV6_HOPLIMIT-Socketoption.
IPv6 IPPROTO_IPV6 IPV6_HOPOPTS Gibt Hop-by-Hop-Optionen an/empfängt sie.
IPv6 IPPROTO_IPV6 IPV6_NEXTHOP Gibt die Adresse des nächsten Hops an.
IPv6 IPPROTO_IPV6 IPV6_PKTINFO Gibt Paketinformationen an/empfängt sie.
Weitere Informationen finden Sie unter IPPROTO_IPV6 Socketoptionen für die IPV6_PKTINFO Socketoption.
IPv6 IPPROTO_IPV6 IPV6_RTHDR Gibt den Routingheader an/empfängt.

Steuerelementdaten bestehen aus einem oder mehreren Steuerelementdatenobjekten, die jeweils mit einer WSACMSGHDR-Struktur beginnen, die wie folgt definiert ist:

} WSACMSGHDR;

Die Elemente der WSACMSGHDR-Struktur sind wie folgt:

Begriff BESCHREIBUNG
cmsg_len Die Anzahl der Bytes von Daten, die vom Anfang des WSACMSGHDR bis zum Ende der Daten beginnen (mit Ausnahme von Auffüllungsbytes, die möglicherweise auf Daten folgen).
cmsg_level Das Protokoll, aus dem die Steuerelementinformationen stammen.
cmsg_type Der protokollspezifische Typ der Steuerelementinformationen.

Der Flags-Parameter kann verwendet werden, um das Verhalten des RIOReceiveEx-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 RIOReceiveEx-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 Headerdatei Ws2def.h 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 auf Windows Phone 8 und höher 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