WSARecvEx-Funktion (winsock.h)
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.
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.
| Fehlercode | Bedeutung |
|---|---|
| Timeout- oder anderer Fehler. Die virtuelle Verbindung wurde beendet. Die Anwendung sollte den Socket schließen, weil er nicht mehr verwendbar ist. | |
| 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. | |
| Der buf-Parameter ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten. | |
| Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion. | |
| Der (blockierende) Anruf wurde vom WSACancelBlockingCall-Aufruf abgebrochen. | |
| 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. | |
| Fehler beim Netzwerksubsystem. | |
| 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. | |
| Der Socket ist nicht verbunden. | |
| Der Deskriptor ist kein Socket. | |
| 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. | |
| 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. | |
| Netzwerkfehler oder Antwortfehler des Peersystems. Die Verbindung wurde abgebrochen. | |
| Der Socket wird als nicht blockiert markiert, und der Empfangsvorgang würde blockiert. | |
| 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.
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.
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 |