WSASendMsg-Funktion (winsock2.h)

Artikel
07/16/2024

Die WSASendMsg Funktion sendet Daten und optionale Steuerinformationen aus verbundenen und nicht verbundenen Sockets.

Hinweis Diese Funktion ist eine microsoftspezifische Erweiterung für die Windows Sockets-Spezifikation.

Syntax

int WSAAPI WSASendMsg(
  [in]  SOCKET                             Handle,
  [in]  LPWSAMSG                           lpMsg,
  [in]  DWORD                              dwFlags,
  [out] LPDWORD                            lpNumberOfBytesSent,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameter

[in] Handle

Ein Deskriptor, der den Socket identifiziert.

[in] lpMsg

Eine WSAMSG- Struktur, die die Posix.1g-msghdr- Struktur speichert.

[in] dwFlags

Die Kennzeichen, die zum Ändern des Verhaltens des WSASendMsg Funktionsaufrufs verwendet werden. Weitere Informationen finden Sie unter Verwenden von dwFlags- im Abschnitt "Hinweise".

[out] lpNumberOfBytesSent

Ein Zeiger auf die Zahl in Byte, die von diesem Aufruf gesendet wird, wenn der E/A-Vorgang sofort abgeschlossen ist.

Verwenden Sie NULL- für diesen Parameter, wenn der parameter lpOverlapped nicht NULL- ist, um potenziell fehlerhafte Ergebnisse zu vermeiden. Dieser Parameter kann nur NULL- werden, wenn der lpOverlapped Parameter nicht NULL-ist.

[in] lpOverlapped

Ein Zeiger auf eine WSAOVERLAPPED--Struktur. Wird für nicht überlappende Sockets ignoriert.

[in] lpCompletionRoutine

Typ: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Ein Zeiger auf die Abschlussroutine, die aufgerufen wird, wenn der Sendevorgang abgeschlossen ist. Wird für nicht überlappende Sockets ignoriert.

Rückgabewert

Gibt Null zurück, wenn erfolgreich und sofort abgeschlossen wird. Wenn Null zurückgegeben wird, wird die angegebene Abschlussroutine aufgerufen, wenn sich der aufrufende Thread im warnungsfähigen Zustand befindet.

Ein Rückgabewert von SOCKET_ERRORund anschließender Aufruf von WSAGetLastError, der WSA_IO_PENDING zurückgibt, gibt an, dass der überlappende Vorgang erfolgreich initiiert wurde; der Abschluss wird dann auf andere Wege angegeben, z. B. durch Ereignisse oder Vervollständigungsports.

Wenn ein Fehler auftritt, werden SOCKET_ERROR und ein nachfolgenden Aufruf von WSAGetLastError einen anderen Wert als WSA_IO_PENDINGzurückgegeben. In der folgenden Tabelle sind Fehlercodes aufgeführt.

Fehlercode	Bedeutung
WSAEACCES	Die angeforderte Adresse ist eine Übertragungsadresse, aber das entsprechende Flag wurde nicht festgelegt.
WSAECONNRESET-	Bei einem UDP-Datagrammsocket würde dieser Fehler darauf hinweisen, dass ein vorheriger Sendevorgang zu einer ICMP-Meldung "Port nicht erreichbar" führte.
WSAEFAULT-	Der lpMsg, lpNumberOfBytesSent, lpOverlappedoder lpCompletionRoutine Parameter ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten. Dieser Fehler wird auch zurückgegeben, wenn ein Name Mitglied der WSAMSG- Struktur, auf die durch den lpMsg Parameter verwiesen wurde, ein NULL- Zeiger war und das namelen Member der WSAMSG--Struktur nicht auf Null festgelegt wurde. Dieser Fehler wird auch zurückgegeben, wenn ein Control.buf Member der WSAMSG- Struktur, auf die durch den lpMsg-Parameter verwiesen wurde, ein NULL- Zeiger war und das Control.len Member der WSAMSG--Struktur nicht auf Null festgelegt wurde.
WSAEINPROGRESS-	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion.
WSAEINTR-	Ein blockierter Windows Socket 1.1-Aufruf wurde über WSACancelBlockingCall-abgebrochen.
WSAEINVAL-	Der Socket wurde nicht an Bindunggebunden, oder der Socket wurde nicht mit dem überlappenden Flag erstellt.
WSAEMSGSIZE-	Der Socket ist nachrichtenorientiert, und die Nachricht ist größer als die maximale Unterstützung durch den zugrunde liegenden Transport.
WSAENETDOWN-	Fehler des Netzwerksubsystems.
WSAENETRESET-	Bei einem Datagrammsocket gibt dieser Fehler an, dass die Zeit für das Live-Programm abgelaufen ist.
WSAENETUNREACH	Das Netzwerk ist nicht erreichbar.
WSAENOBUFS	Der Windows Sockets-Anbieter meldet einen Puffer-Deadlock.
WSAENOTCONN	Der Socket ist nicht verbunden.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSAEOPNOTSUPP	Der Socketvorgang wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn das dwFlags Member der WSAMSG- Struktur, auf die durch den parameter lpMsg verwiesen wird, alle Steuerelementflags enthält, die für WSASendMsgungültig sind.
WSAESHUTDOWN-	Der Socket wurde heruntergefahren; Es ist nicht möglich, die WSASendMsg-Funktion in einem Socket aufzurufen, nachdem Herunterfahren mit aufgerufen wurde, wie auf SD_SEND oder SD_BOTH festgelegt wurde.
WSAETIMEDOUT-	Timeout des Sockets. Dieser Fehler wird zurückgegeben, wenn der Socket ein mit der SO_SNDTIMEO Socketoption angegebenes Wartezeittimeout hatte und das Timeout überschritten wurde.
WSAEWOULDBLOCK	Überlappende Sockets: Es gibt zu viele überlappende E/A-Anforderungen. Nicht überlappte Sockets: Der Socket ist als nicht blockiert gekennzeichnet, und der Sendevorgang kann nicht sofort abgeschlossen werden.
WSANOTINITIALISIERT	Ein erfolgreicher WSAStartup Aufrufs muss erfolgen, bevor diese Funktion verwendet wird.
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angegeben.
WSA_OPERATION_ABORTED	Der überlappende Vorgang wurde aufgrund des Schließens des Sockets oder aufgrund der Ausführung des SIO_FLUSH Befehls in WSAIoctlabgebrochen.

Bemerkungen

Die WSASendMsg--Funktion kann anstelle der WSASend- und WSASendTo--Funktionen verwendet werden. Die WSASendMsg--Funktion kann nur mit Datagrammen und unformatierten Sockets verwendet werden. Der Socketdeskriptor im -Parameter muss geöffnet werden, wobei der Sockettyp auf SOCK_DGRAM oder SOCK_RAWfestgelegt ist.

Der dwFlags Parameter kann nur eine Kombination der folgenden Steuerelementflags enthalten: MSG_DONTROUTE, MSG_PARTIALund MSG_OOB. Das dwFlags Mitglied der WSAMSG- Struktur, auf die durch den lpMsg Parameter verwiesen wird, wird für die Eingabe ignoriert und nicht für die Ausgabe verwendet.

Hinweis Der Funktionszeiger für die WSASendMsg--Funktion muss zur Laufzeit abgerufen werden, indem ein Aufruf der WSAIoctl--Funktion mit dem angegebenen SIO_GET_EXTENSION_FUNCTION_POINTER Opcode erfolgt. Der an die WSAIoctl Funktion übergebene Eingabepuffer muss WSAID_WSASENDMSGenthalten, eine GUID (Globally Unique Identifier), deren Wert die WSASendMsg Erweiterungsfunktion identifiziert. Bei Erfolg enthält die von der WSAIoctl Funktion zurückgegebene Ausgabe einen Zeiger auf die WSASendMsg--Funktion. Die WSAID_WSASENDMSG GUID wird in der Mswsock.h Headerdatei definiert.

Überlappende Sockets werden mit einem WSASocket- Funktionsaufruf erstellt, der den WSA_FLAG_OVERLAPPED Flagsatz aufweist. Bei überlappenden Sockets werden beim Senden von Informationen überlappende E/A verwendet, es sei denn, lpOverlapped- und lpCompletionRoutine null sind; Wenn lpOverlapped und lpCompletionRoutinenullsind, wird der Socket als nicht überlappter Socket behandelt. Ein Abschlusshinweis tritt mit überlappenden Sockets auf; Sobald der Puffer oder Puffer vom Transport genutzt wurden, wird eine Abschlussroutine ausgelöst oder ein Ereignisobjekt festgelegt. Wenn der Vorgang nicht sofort abgeschlossen wird, wird der endgültige Abschlussstatus über die Abschlussroutine oder durch Aufrufen der WSAGetOverlappedResult-Funktion abgerufen.

Bei nicht überlappten Sockets werden die lpOverlapped und lpCompletionRoutine Parameter ignoriert, und WSASendMsg übernimmt die gleiche blockierende Semantik wie die senden Funktion: Daten werden aus dem Puffer oder Puffer des Transports in den Puffer kopiert. Wenn der Socket nicht blockiert und datenstromorientiert ist und nicht genügend Speicherplatz im Puffer des Transports vorhanden ist, WSASendMsg zurückgibt, wobei nur ein Teil der Puffer der Anwendung verbraucht wurde. Im Gegensatz dazu führt diese Puffersituation bei einem blockierenden Socket zu WSASendMsg Blockieren, bis alle Pufferinhalte der Anwendung verbraucht wurden.

Wenn diese Funktion auf überlappende Weise abgeschlossen wird, liegt es in der Verantwortung des Winsock-Dienstanbieters, diese WSABUF--Struktur zu erfassen, bevor sie von diesem Aufruf zurückgegeben wird. Auf diese Weise können Anwendungen stapelbasierte WSABUF- Arrays erstellen, auf die vom lpBuffers Member der WSAMSG- Struktur verwiesen wird, auf die der lpMsg-Parameter verweist.

Bei nachrichtenorientierten Sockets muss die maximale Nachrichtengröße des zugrunde liegenden Anbieters nicht überschritten werden, was durch Abrufen des Werts der Socketoption SO_MAX_MSG_SIZEabgerufen werden kann. Wenn die Daten zu lang sind, um atomisch über das zugrunde liegende Protokoll zu übergeben, wird der Fehler WSAEMSGSIZE zurückgegeben, und es werden keine Daten übertragen.

Bei einem IPv4-Socket vom Typ SOCK_DGRAM oder SOCK_RAWkann eine Anwendung die lokale IP-Quelladresse spezifisch für das Senden mit der WSASendMsg--Funktion verwenden. Eines der Steuerelementdatenobjekte, die in der WSAMSG--Struktur an die WSASendMsg-Funktion übergeben werden, kann eine in_pktinfo Struktur enthalten, die verwendet wird, um die lokale IPv4-Quelladresse anzugeben, die zum Senden verwendet werden soll.

Bei einem IPv6-Socket vom Typ SOCK_DGRAM oder SOCK_RAWkann eine Anwendung die lokale IP-Quelladresse spezifisch für das Senden mit der WSASendMsg--Funktion verwenden. Eines der Steuerelementdatenobjekte, die in der WSAMSG- Struktur an die WSASendMsg-Funktion übergeben werden, kann eine in6_pktinfo Struktur enthalten, die verwendet wird, um die lokale IPv6-Quelladresse anzugeben, die zum Senden verwendet werden soll.

Bei einem Dualstapel-Socket beim Senden von Datagrammen mit der WSASendMsg-Funktion und eine Anwendung möchte eine bestimmte lokale IP-Quelladresse angeben, die verwendet werden soll, hängt die Methode zur Verarbeitung von der Ziel-IP-Adresse ab. Beim Senden an eine IPv4-Zieladresse oder eine IPv4-zugeordnete IPv6-Zieladresse sollte eines der Steuerelementdatenobjekte, die in der WSAMSG- Struktur übergeben werden, die vom lpMsg Parameter verweist, eine in_pktinfo Struktur enthalten, die die lokale IPv4-Quelladresse enthält, die zum Senden verwendet werden soll. Beim Senden an eine IPv6-Zieladresse, die keine IPv4-zugeordnete IPv6-Adresse ist, sollte eines der Steuerelementdatenobjekte, die in der WSAMSG--Struktur übergeben werden, auf die der lpMsg-Parameter verweist, eine in6_pktinfo Struktur enthalten, die die lokale IPv6-Quelladresse enthält, die zum Senden verwendet werden soll.

Hinweis Die SO_SNDTIMEO Socketoption gilt nur für das Blockieren von Sockets.

Hinweis Der erfolgreiche Abschluss eines WSASendMsg- weist nicht darauf hin, dass die Daten erfolgreich übermittelt wurden.

Hinweis Beim Ausgeben eines blockierenden Winsock-Aufrufs wie WSASendMsg mit dem parameter lpOverlapped auf NULL festgelegt, muss Winsock möglicherweise auf ein Netzwerkereignis warten, bevor der Aufruf abgeschlossen werden kann. Winsock führt in dieser Situation eine warnbare Wartezeit durch, die durch einen asynchronen Prozeduraufruf (APC) unterbrochen werden kann, der im selben Thread geplant ist. Das Ausstellen eines weiteren blockierenden Winsock-Aufrufs innerhalb eines APC, der einen fortlaufend blockierten Winsock-Aufruf im selben Thread unterbrochen hat, führt zu nicht definiertem Verhalten und darf niemals von Winsock-Clients versucht werden.

dwFlags

Der dwFlags Eingabeparameter kann verwendet werden, um das Verhalten des Funktionsaufrufs über die für den zugeordneten Socket angegebenen Optionen hinaus zu beeinflussen. Das heißt, die Semantik dieser Funktion wird durch die Socketoptionen und den dwFlags Parameter bestimmt. Letzteres wird mithilfe des bitweisen OR-Operators mit einem der folgenden Werte erstellt.

Wert	Bedeutung
MSG_DONTROUTE	Gibt an, dass die Daten nicht dem Routing unterliegen sollen. Ein Windows Sockets-Dienstanbieter kann diese Kennzeichnung ignorieren.
MSG_PARTIAL	Gibt an, dass lpMsg->lpBuffers- nur eine partielle Nachricht enthält. Beachten Sie, dass der Fehlercode WSAEOPNOTSUPP- von Transporten zurückgegeben wird, die teilweise Nachrichtenübertragungen nicht unterstützen.

Die möglichen Werte für dwFlags Parameter sind in der Winsock2.h Headerdatei definiert.

Bei der Ausgabe wird das dwFlags Member der WSAMSG- Struktur verwendet, auf die der lpMsg-Parameter verweist.

überlappenden Socket-E/A

Wenn ein überlappender Vorgang sofort abgeschlossen wird, gibt WSASendMsg einen Wert von Null zurück, und der lpNumberOfBytesSent Parameter wird mit der Anzahl der gesendeten Bytes aktualisiert. Wenn der überlappende Vorgang erfolgreich initiiert und später abgeschlossen wird, gibt WSASendMsg SOCKET_ERROR zurück und gibt fehlercode WSA_IO_PENDINGan. In diesem Fall wird lpNumberOfBytesSent nicht aktualisiert. Nach Abschluss des überlappenden Vorgangs wird die übertragene Datenmenge entweder über den cbTransferred Parameter in der Abschlussroutine (sofern angegeben) oder über den lpcbTransfer Parameter in WSAGetOverlappedResultangegeben.

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 unter ExitThread-.

Die WSASendMsg Funktion mit überlappender E/A kann innerhalb der Abschlussroutine eines vorherigen , WSARecv, WSARecvFrom, LPFN_WSARECVMSG aufgerufen werden. (WSARecvMsg), WSASend, WSASendMsgoder WSASendTo Funktion. Dies ermöglicht es zeitsensiblen Datenübertragungen, vollständig innerhalb eines präventiven Kontexts zu erfolgen.

Der parameter lpOverlapped muss für die Dauer des überlappenden Vorgangs gültig sein. Wenn mehrere E/A-Vorgänge gleichzeitig ausstehen, muss jeder auf eine separate WSAOVERLAPPED Struktur verweisen.

Wenn der lpCompletionRoutine Parameter NULL-ist, wird der hEvent Parameter lpOverlapped signalisiert, wenn der überlappende Vorgang abgeschlossen ist, wenn er ein gültiges Ereignisobjekthandle enthält. Eine Anwendung kann WSAWaitForMultipleEvents oder WSAGetOverlappedResult- verwenden, um das Ereignisobjekt zu warten oder abzufragen.

Wenn lpCompletionRoutine nicht NULL-ist, wird der hEvent Parameter ignoriert und kann von der Anwendung verwendet werden, um Kontextinformationen an die Abschlussroutine zu übergeben. Ein Aufrufer, der eine nichtNULL-lpCompletionRoutine- und später aufruft, WSAGetOverlappedResult- für dieselbe überlappende E/A-Anforderung nicht den fWait Parameter für diesen Aufruf von WSAGetOverlappedResult- auf TRUEfestlegen. In diesem Fall ist die Verwendung des hEvent--Parameters nicht definiert, und der Versuch, auf den hEvent Parameter zu warten, würde zu unvorhersehbaren Ergebnissen führen.

Die Abschlussroutine folgt den gleichen Regeln wie für Die I/O-Vervollständigungsroutinen der Windows-Datei. Die Abschlussroutine wird erst aufgerufen, wenn sich der Thread in einem warnbaren Wartezustand befindet, z. B. mit WSAWaitForMultipleEvents aufgerufen, wobei der fAlertable Parameter auf TRUEfestgelegt ist.

Die Transportanbieter ermöglichen es einer Anwendung, Sende- und Empfangsvorgänge innerhalb des Kontexts der E/A-Abschlussroutine des Sockets aufzurufen und sicherzustellen, dass E/A-Vervollständigungsroutinen für einen bestimmten Socket nicht geschachtelt werden. Dies ermöglicht es zeitsensiblen Datenübertragungen, vollständig innerhalb eines präventiven Kontexts zu erfolgen.

Der Prototyp der Abschlussroutine lautet wie folgt.


void CALLBACK CompletionRoutine(
  IN DWORD dwError,
  IN DWORD cbTransferred,
  IN LPWSAOVERLAPPED lpOverlapped,
  IN DWORD dwFlags
);

Die CompletionRoutine-Funktion ist ein Platzhalter für einen anwendungsdefinierten oder bibliotheksdefinierten Funktionsnamen. Der parameter dwError gibt den Abschlussstatus für den überlappenden Vorgang an, wie durch den parameter lpOverlapped angegeben. Der parameter cbTransferred gibt die Anzahl der gesendeten Bytes an. Derzeit sind keine Flagwerte definiert, und der dwFlags Parameter ist null. Die CompletionRoutine--Funktion gibt keinen Wert zurück.

Das Zurückgeben von dieser Funktion ermöglicht den Aufruf einer anderen ausstehenden Abschlussroutine für den Socket. Alle Warteabschlussroutinen werden aufgerufen, bevor die Warteschleife des warnbaren Threads mit einem Rückgabecode von WSA_IO_COMPLETION zufrieden ist. Die Abschlussroutinen können in beliebiger Reihenfolge aufgerufen werden, nicht unbedingt in der gleichen Reihenfolge, in der die überlappenden Vorgänge abgeschlossen sind. Die geposteten Puffer werden jedoch garantiert in derselben Reihenfolge gesendet, in der sie angegeben sind.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winsock2.h (include Mswsock.h)
Library	Ws2_32.lib
DLL-	Ws2_32.dll