WSARecvEx-Funktion (mswsock.h)

Artikel
08/25/2023

Die WSARecvEx-Funktion empfängt Daten von einem verbundenen Socket oder einem gebundenen verbindungslosen Socket. Die WSARecvEx-Funktion ähnelt der recv-Funktion , mit der Ausnahme, dass der Flags-Parameter nur zum Zurückgeben von Informationen verwendet wird. Wenn eine partielle Nachricht empfangen wird, während das Datagrammprotokoll verwendet wird, wird das MSG_PARTIAL Bit im Flags-Parameter festgelegt, wenn die Funktion zurückgegeben wird.

Hinweis Die WSARecvEx-Funktion ist eine Microsoft-spezifische Erweiterung der Windows Sockets-Spezifikation.

Syntax

int WSARecvEx(
  [in]      SOCKET s,
  [out]     char   *buf,
  [in]      int    len,
  [in, out] int    *flags
);

Parameter

[in] s

Ein Deskriptor, der einen verbundenen Socket identifiziert.

[out] buf

Ein Zeiger auf den Puffer, um die eingehenden Daten zu empfangen.

[in] len

Die Länge des Puffers in Bytes, auf den der buf-Parameter verweist.

[in, out] flags

Ein Indikator, der angibt, ob die Nachricht für Datagrammsockets vollständig oder teilweise empfangen wird.

Rückgabewert

Wenn kein Fehler auftritt, gibt WSARecvEx die Anzahl der empfangenen Bytes zurück. Wenn die Verbindung geschlossen wurde, gibt sie null zurück. Wenn eine Teilnachricht empfangen wurde, wird darüber hinaus das MSG_PARTIAL Bit im Flags-Parameter festgelegt. Wenn eine vollständige Nachricht empfangen wurde, wird MSG_PARTIAL nicht in Flags festgelegt.

Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Wichtig Bei einem streamorientierten Transportprotokoll wird MSG_PARTIAL nie bei der Rückgabe von WSARecvEx festgelegt. Diese Funktion verhält sich identisch mit der recv-Funktion für Streamtransportprotokolle.

Fehlercode	Bedeutung
WSAECONNABORTED	Timeout- oder anderer Fehler. Die virtuelle Verbindung wurde beendet. Die Anwendung sollte den Socket schließen, weil er nicht mehr verwendbar ist.
WSAECONNRESET	Die virtuelle Verbindung wurde von der Remoteseite zurückgesetzt, die einen harten oder abbrechenden Schließvorgang ausgeführt hat. Die Anwendung sollte den Socket schließen, weil er nicht mehr verwendbar ist. Für einen UPD-Datagrammsocket zeigt dieser Fehler an, dass ein vorheriger Sendevorgang zu einer ICMP-Nachricht "Port kann nicht erreicht werden" geführt hat.
WSAEFAULT	Der buf-Parameter ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion.
WSAEINTR	Der (blockierende) Aufruf wurde vom WSACancelBlockingCall-Aufruf abgebrochen.
WSAEINVAL	Der Socket wurde nicht an bind gebunden, oder ein unbekanntes Flag wurde angegeben, oder MSG_OOB für einen Socket mit aktiviertem SO_OOBINLINE oder (nur für Bytestreamsockets) len null oder negativ angegeben wurde.
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAENETRESET	Bei einem verbindungsorientierten Socket gibt dieser Fehler an, dass die Verbindung aufgrund einer Keep-Alive-Aktivität unterbrochen wurde, die einen Fehler erkannt hat, während der Vorgang ausgeführt wurde. Für einen Datagrammsocket zeigt dieser Fehler an, dass die Gültigkeitsdauer abgelaufen ist.
WSAENOTCONN	Der Socket ist nicht verbunden.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSAEOPNOTSUPP	MSG_OOB angegeben wurde, aber der Socket nicht im Streamformat wie der Typ SOCK_STREAM, werden OOB-Daten in der diesem Socket zugeordneten Kommunikationsdomäne nicht unterstützt, oder der Socket ist unidirektional und unterstützt nur Sendevorgänge.
WSAESHUTDOWN	Der Socket wurde heruntergefahren. Es ist nicht möglich , WSARecvEx auf einem Socket zu verwenden, nachdem das Herunterfahren aufgerufen wurde, wobei festgelegt ist , dass SD_RECEIVE oder SD_BOTH festgelegt ist.
WSAETIMEDOUT	Netzwerkfehler oder Antwortfehler des Peersystems. Die Verbindung wurde abgebrochen.
WSAEWOULDBLOCK	Der Socket ist als nicht blockierend gekennzeichnet, und der Empfangsvorgang würde blockiert.
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.

Hinweise

Die WSARecvEx-Funktion , die Teil der Microsoft-Implementierung von Windows Sockets 2 ist, ähnelt der häufigeren recv-Funktion , mit der Ausnahme, dass der Flags-Parameter für einen bestimmten Zweck verwendet wird. Der Flags-Parameter wird verwendet, um anzugeben, ob eine partielle oder vollständige Nachricht empfangen wird, wenn ein nachrichtenorientiertes Protokoll verwendet wird.

Der Wert, auf den der Flags-Parameter verweist, wird bei der Eingabe ignoriert. Daher können keine Flags an die WSARecvEx-Funktion übergeben werden, um ihr Verhalten zu ändern. Der Wert, auf den der Flags-Parameter verweist, wird bei der Ausgabe festgelegt. Dies unterscheidet sich von den Funktionen recv und WSARecv , bei denen der Wert, auf den der flags-Parameter bei der Eingabe verweist, das Verhalten der Funktion ändern kann.

Die Funktionen WSARecvEx und recv verhalten sich für streamorientierte Protokolle identisch.

Der Flags-Parameter bietet zwei häufige Situationen, in denen eine Teilnachricht empfangen wird:

Wenn die Datenpuffergröße der Anwendung kleiner als die Nachrichtengröße ist und die Nachricht zufällig in zwei Teilen eingeht.
Wenn die Nachricht ziemlich groß ist und in mehreren Teilen eintreffen muss.

Das MSG_PARTIAL Bit wird in dem Wert festgelegt, auf den der Flags-Parameter bei der Rückgabe von WSARecvEx verweist, wenn eine Teilnachricht empfangen wurde. Wenn eine vollständige Nachricht empfangen wurde, wird MSG_PARTIAL nicht im Wert festgelegt, auf den der flags-Parameter verweist.

Die recv-Funktion unterscheidet sich von der
WSARecvEx - und WSARecv-Funktionen , da die recv-Funktion immer eine einzelne Nachricht für jeden Aufruf nachrichtenorientierter Transportprotokolle empfängt. Die recv-Funktion verfügt auch nicht über ein Mittel, um der Anwendung anzugeben, dass die empfangenen Daten nur eine partielle Nachricht sind. Eine Anwendung muss ein eigenes Protokoll erstellen, um zu überprüfen, ob eine Nachricht teilweise oder vollständig ist, indem nach jedem Aufruf von recv auf den Fehlercode WSAEMSGSIZE überprüft wird. Wenn der Anwendungspuffer kleiner als die gesendeten Daten ist, wird ein möglichst großer Teil der Nachricht in den Puffer des Benutzers kopiert, und recv gibt mit dem Fehlercode WSAEMSGSIZE zurück. Ein anschließender Aufruf von recv erhält den nächsten Teil der Nachricht.

Anwendungen, die für nachrichtenorientierte Transportprotokolle geschrieben wurden, sollten für diese Möglichkeit codiert werden, wenn die Nachrichtendimensionierung durch das Datenübertragungsprotokoll der Anwendung nicht garantiert wird. Eine Anwendung kann recv verwenden und das Protokoll selbst verwalten. Alternativ kann eine Anwendung WSARecvEx verwenden und überprüfen, ob das MSG_PARTIAL Bit im Flags-Parameter festgelegt ist.

Die WSARecvEx-Funktion bietet dem Entwickler eine effektivere Möglichkeit, zu überprüfen, ob eine empfangene Nachricht teilweise oder vollständig ist, wenn eine sehr große Nachricht inkrementell eingeht. Wenn eine Anwendung beispielsweise eine 1-Megabyte-Nachricht sendet, muss das Transportprotokoll die Nachricht aufteilen, um sie über das physische Netzwerk zu senden. Theoretisch ist es möglich, dass das Transportprotokoll auf der Empfangenden Seite alle Daten in der Nachricht puffert, aber dies wäre ressourcenmäßig ziemlich teuer. Stattdessen kann WSARecvEx verwendet werden, um den Mehraufwand zu minimieren und die Notwendigkeit eines anwendungsbasierten Protokolls zu vermeiden.

Hinweis Alle von einem bestimmten Thread initiierten E/A-Vorgänge werden abgebrochen, wenn dieser Thread beendet wird. Bei überlappenden Sockets können ausstehende asynchrone Vorgänge fehlschlagen, wenn der Thread geschlossen wird, bevor die Vorgänge abgeschlossen werden. Weitere Informationen finden Sie in der ExitThread-Funktion .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	mswsock.h (include Mswsock.h)
Bibliothek	Mswsock.lib
DLL	Mswsock.dll