WSARecvEx-Funktion (winsock.h)

Artikel
08/27/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 Teilnachricht 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 zum Empfangen der eingehenden Daten.

[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, wird null zurückgegeben. Wenn eine Teilnachricht empfangen wurde, wird außerdem 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 Für ein streamorientiertes 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 noch eine Rückruffunktion.
WSAEINTR	Der (blockierende) Anruf wurde vom WSACancelBlockingCall-Aufruf abgebrochen.
WSAEINVAL	Der Socket wurde nicht mit bind gebunden, oder es wurde ein unbekanntes Flag angegeben, oder MSG_OOB für einen Socket mit aktiviertem SO_OOBINLINE oder (nur für Bytestreamsockets) angegeben wurde, war len null oder negativ.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAENETRESET	Bei einem verbindungsorientierten Socket gibt dieser Fehler an, dass die Verbindung aufgrund einer Keep-Alive-Aktivität unterbrochen wurde, die während des Vorgangs einen Fehler erkannt hat. 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 Streamstil wie 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	Die Steckdose wurde heruntergefahren; Es ist nicht möglich , WSARecvEx auf einem Socket zu verwenden, nachdem das Herunterfahren aufgerufen wurde, wobei auf SD_RECEIVE oder SD_BOTH festgelegt ist.
WSAETIMEDOUT	Netzwerkfehler oder Antwortfehler des Peersystems. Die Verbindung wurde abgebrochen.
WSAEWOULDBLOCK	Der Socket wird als nicht blockiert markiert, 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 unterstützt 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 eingehen 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 in dem Wert, auf den der Flags-Parameter verweist, nicht festgelegt.

Die recv-Funktion unterscheidet sich von der
WSARecvEx - und WSARecv-Funktionen , da die recv-Funktion für jeden Aufruf für nachrichtenorientierte Transportprotokolle immer eine einzelne Nachricht empfängt. Die recv-Funktion verfügt auch nicht über ein Mittel, um der Anwendung mitzuteilen, dass die empfangenen Daten nur eine Teilnachricht sind. Eine Anwendung muss ein eigenes Protokoll erstellen, um zu überprüfen, ob eine Nachricht teilweise oder vollständig ist, indem sie nach jedem Aufruf von recv auf den Fehlercode WSAEMSGSIZE überprüft. 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 nicht durch das Datenübertragungsprotokoll der Anwendung 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 entwicklern 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 trennen, um sie über das physische Netzwerk zu senden. Es ist theoretisch möglich, dass das Transportprotokoll auf der Empfangsseite alle Daten in der Nachricht puffert, aber dies wäre in Bezug auf die Ressourcen 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 sind. Weitere Informationen finden Sie in der ExitThread-Funktion .

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winsock.h (Mswsock.h einschließen)
Bibliothek	Mswsock.lib
DLL	Mswsock.dll