WSASendMsg-Funktion (winsock2.h)

Artikel
08/27/2023

Die WSASendMsg-Funktion sendet Daten und optionale Steuerungsinformationen von verbundenen und nicht verbundenen Sockets.

Hinweis Diese Funktion ist eine Microsoft-spezifische Erweiterung der 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 Flags, 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 Bytes, die von diesem Aufruf gesendet wird, wenn der E/A-Vorgang sofort abgeschlossen wird.

Verwenden Sie NULL für diesen Parameter, wenn der lpOverlapped-Parameter nicht NULL ist, um potenziell fehlerhafte Ergebnisse zu vermeiden. Dieser Parameter kann nur NULL sein, 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 Vervollständigungsroutine, die aufgerufen wird, wenn der Sendevorgang abgeschlossen ist. Wird für nicht überlappende Sockets ignoriert.

Rückgabewert

Gibt null zurück, wenn ein erfolgreicher und sofortiger Abschluss erfolgt. Wenn null zurückgegeben wird, wird die angegebene Vervollständigungsroutine aufgerufen, wenn sich der aufrufende Thread im warnbaren Zustand befindet.

Der Rückgabewert SOCKET_ERROR und der nachfolgende Aufruf von WSAGetLastError , der WSA_IO_PENDING zurückgibt, gibt an, dass der überlappende Vorgang erfolgreich initiiert wurde. Der Abschluss wird dann durch andere Mittel angezeigt, z. B. durch Ereignisse oder Vervollständigungsports.

Bei einem Fehler wird SOCKET_ERROR zurückgegeben, und ein anschließender Aufruf von WSAGetLastError gibt einen anderen Wert als WSA_IO_PENDING zurück. In der folgenden Tabelle sind Fehlercodes aufgeführt.

Fehlercode	Bedeutung
WSAEACCES	Die angeforderte Adresse ist eine Broadcastadresse, aber das entsprechende Flag wurde nicht festgelegt.
WSAECONNRESET	Bei einem UDP-Datagrammsocket würde dieser Fehler darauf hindeuten, dass ein vorheriger Sendevorgang zu einer ICMP-Meldung "Port unreachable" geführt hat.
WSAEFAULT	Der Parameter lpMsg, lpNumberOfBytesSent, lpOverlapped oder lpCompletionRoutine ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten. Dieser Fehler wird auch zurückgegeben, wenn ein Namensmember der WSAMSG-Struktur , auf die der lpMsg-Parameter verweist, ein NULL-Zeiger war und der namelen-Member der WSAMSG-Struktur nicht auf 0 festgelegt wurde. Dieser Fehler wird auch zurückgegeben, wenn ein Control.buf-Member der WSAMSG-Struktur , auf die der lpMsg-Parameter verweist, ein NULL-Zeiger war und das Control.len-Element der WSAMSG-Struktur nicht auf 0 festgelegt wurde.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion.
WSAEINTR	Ein blockierender Windows Socket 1.1-Aufruf wurde über WSACancelBlockingCall abgebrochen.
WSAEINVAL	Der Socket wurde nicht mit bind gebunden, oder der Socket wurde nicht mit dem überlappenden Flag erstellt.
WSAEMSGSIZE	Der Socket ist nachrichtenorientiert, und die Nachricht ist größer als das maximum, das vom zugrunde liegenden Transport unterstützt wird.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAENETRESET	Für einen Datagrammsocket zeigt dieser Fehler an, dass die Gültigkeitsdauer 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 der dwFlags-Member der WSAMSG-Struktur , auf die der lpMsg-Parameter verweist, für WSASendMsg ungültige Steuerelementflags enthält.
WSAESHUTDOWN	Die Steckdose wurde heruntergefahren; Es ist nicht möglich, die WSASendMsg-Funktion in einem Socket aufzurufen, nachdem das Herunterfahren aufgerufen wurde, wobei auf SD_SEND oder SD_BOTH festgelegt ist.
WSAETIMEDOUT	Timeout des Sockets. Dieser Fehler wird zurückgegeben, wenn für den Socket ein Wartetimeout mit der Option SO_SNDTIMEO Socket angegeben wurde und das Timeout überschritten wurde.
WSAEWOULDBLOCK	Überlappende Sockets: Es gibt zu viele ausstehende überlappende E/A-Anforderungen. Nicht überlappende Sockets: Der Socket ist als nicht blockiert gekennzeichnet, und der Sendevorgang kann nicht sofort abgeschlossen werden.
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt.
WSA_OPERATION_ABORTED	Der überlappende Vorgang wurde aufgrund des Schließens des Sockets oder aufgrund der Ausführung des befehls SIO_FLUSH in WSAIoctl abgebrochen.

Hinweise

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

Der dwFlags-Parameter kann nur eine Kombination der folgenden Steuerelementflags enthalten: MSG_DONTROUTE, MSG_PARTIAL und MSG_OOB. Der dwFlags-Member der WSAMSG-Struktur , auf die der lpMsg-Parameter verweist, wird bei der Eingabe ignoriert und nicht für die Ausgabe verwendet.

Hinweis Der Funktionszeiger für die WSASendMsg-Funktion muss zur Laufzeit abgerufen werden, indem die WSAIoctl-Funktion mit dem angegebenen SIO_GET_EXTENSION_FUNCTION_POINTER Opcode aufgerufen wird. Der an die WSAIoctl-Funktion übergebene Eingabepuffer muss WSAID_WSASENDMSG enthalten, einen GUID (Globally Unique Identifier), dessen 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 ist in der Headerdatei Mswsock.h definiert.

Überlappende Sockets werden mit einem WSASocket-Funktionsaufruf erstellt, für den das flag WSA_FLAG_OVERLAPPED festgelegt ist. Für überlappende Sockets verwendet das Senden von Informationen überlappende E/A, es sei denn, sowohl lpOverlapped als auch lpCompletionRoutine sind NULL. Wenn lpOverlapped und lpCompletionRoutineNULL sind, wird der Socket als nicht überlappender Socket behandelt. Eine Vervollständigungsanzeige tritt mit überlappenden Sockets auf; Sobald der Puffer oder die Puffer vom Transport verbraucht wurden, wird eine Vervollständigungsroutine ausgelöst oder ein Ereignisobjekt festgelegt. Wenn der Vorgang nicht sofort abgeschlossen wird, wird der endgültige Abschluss status über die Vervollständigungsroutine oder durch Aufrufen der WSAGetOverlappedResult-Funktion abgerufen.

Bei nicht überlappten Sockets werden die Parameter lpOverlapped und lpCompletionRoutine ignoriert, und WSASendMsg verwendet dieselbe blockierende Semantik wie die Sendefunktion : Daten werden aus dem Puffer oder puffern in den Puffer des Transports kopiert. Wenn der Socket nicht blockend und streamorientiert ist und nicht genügend Speicherplatz im Puffer des Transports vorhanden ist, gibt WSASendMsg zurück, wobei nur ein Teil der Puffer der Anwendung verbraucht wurde. Im Gegensatz dazu führt diese Puffersituation auf einem blockierenden Socket dazu, dass WSASendMsg blockiert wird, bis der gesamte Pufferinhalt der Anwendung genutzt wurde.

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

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

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

Auf einem IPv6-Socket vom Typ SOCK_DGRAM oder SOCK_RAW kann eine Anwendung die lokale IP-Quelladresse angeben, die zum Senden mit der WSASendMsg-Funktion verwendet werden soll. 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 für das Senden verwendet werden soll.

Bei einem Dual-Stack-Socket beim Senden von Datagrammen mit der WSASendMsg-Funktion und einer Anwendung, die eine bestimmte lokale IP-Quelladresse angeben möchte, hängt die Methode für die 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, auf die der 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 blockierende Sockets.

Hinweis Der erfolgreiche Abschluss einer WSASendMsg bedeutet nicht, dass die Daten erfolgreich übermittelt wurden.

Hinweis Wenn Sie einen blockierenden Winsock-Aufruf wie WSASendMsg ausgeben, bei dem der lpOverlapped-Parameter auf NULL festgelegt ist, muss Winsock möglicherweise auf ein Netzwerkereignis warten, bevor der Aufruf abgeschlossen werden kann. Winsock führt in dieser Situation eine warnbare Wartezeit aus, die durch einen asynchronen Prozeduraufruf (APC) unterbrochen werden kann, der für denselben Thread geplant ist. Das Ausgeben eines weiteren blockierenden Winsock-Aufrufs in einem APC, der einen fortlaufenden blockierenden 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 routingpflichtig sein sollen. Ein Windows Sockets-Dienstanbieter kann dieses Flag 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 partielle Nachrichtenübertragungen nicht unterstützen.

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

In der Ausgabe wird der dwFlags-Member der WSAMSG-Struktur , auf die vom lpMsg-Parameter verwiesen wird, nicht verwendet.

Überlappende Socket-E/A

Wenn ein überlappender Vorgang sofort abgeschlossen wird, gibt WSASendMsg den Wert null zurück, und der parameter lpNumberOfBytesSent wird mit der Anzahl der gesendeten Bytes aktualisiert. Wenn der überlappende Vorgang erfolgreich initiiert wurde und später abgeschlossen wird, gibt WSASendMsg SOCKET_ERROR zurück und gibt fehlercode WSA_IO_PENDING an. In diesem Fall wird lpNumberOfBytesSent nicht aktualisiert. Wenn der überlappende Vorgang abgeschlossen ist, wird die übertragene Datenmenge entweder über den cbTransferred-Parameter in der Vervollständigungsroutine (sofern angegeben) oder über den lpcbTransfer-Parameter in WSAGetOverlappedResult angegeben.

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

Die WSASendMsg-Funktion mit überlappenden E/A-Vorgängen kann innerhalb der Vervollständigungsroutine einer vorherigen , WSARecv,WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg), WSASendMsg, WSASendMsg oder WSASendTo-Funktion aufgerufen werden. So können zeitsensible Datenübertragungen vollständig in einem präventiven Kontext erfolgen.

Der lpOverlapped-Parameter 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-ParameterNULL ist, wird der hEvent-Parameter von lpOverlapped signalisiert, wenn der überlappende Vorgang abgeschlossen wird, 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 Vervollständigungsroutine zu übergeben. Ein Aufrufer, der eine nicht NULLlpCompletionRoutine übergibt und später WSAGetOverlappedResult für dieselbe überlappende E/A-Anforderung aufruft, legt den fWait-Parameter für diesen Aufruf von WSAGetOverlappedResult möglicherweise nicht auf TRUE fest. In diesem Fall ist die Verwendung des hEvent-Parameters nicht definiert, und der Versuch, auf den hEvent-Parameter zu warten, führt zu unvorhersehbaren Ergebnissen.

Die Vervollständigungsroutine folgt den gleichen Regeln wie für Windows-Datei-E/A-Vervollständigungsroutinen. Die Vervollständigungsroutine wird erst aufgerufen, wenn sich der Thread in einem warnbaren Wartezustand befindet, z. B. mit dem Aufruf von WSAWaitForMultipleEvents , wobei der fAlertable-Parameter auf TRUE festgelegt ist.

Die Transportanbieter ermöglichen einer Anwendung das Aufrufen von Sende- und Empfangsvorgängen aus dem Kontext der Socket-E/A-Vervollständigungsroutine und garantieren, dass für einen bestimmten Socket E/A-Vervollständigungsroutinen nicht geschachtelt werden. So können zeitsensible Datenübertragungen vollständig in einem präventiven Kontext erfolgen.

Der Prototyp der Vervollständigungsroutine sieht wie folgt aus.


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 bibliotheksdefinierte Funktionsnamen. Der dwError-Parameter gibt die Vervollständigung status für den überlappenden Vorgang an, wie durch den lpOverlapped-Parameter angegeben. Der cbTransferred-Parameter gibt die Anzahl der gesendeten Bytes an. Derzeit sind keine Flagwerte definiert, und der dwFlags-Parameter ist 0. Die CompletionRoutine-Funktion gibt keinen Wert zurück.

Das Zurückgeben von dieser Funktion ermöglicht den Aufruf einer anderen ausstehenden Vervollständigungsroutine für den Socket. Alle wartenden Vervollständigungsroutinen werden aufgerufen, bevor die Wartezeit des warnungsfähigen Threads mit einem Rückgabecode von WSA_IO_COMPLETION erfüllt ist. Die Vervollständigungsroutinen können in beliebiger Reihenfolge aufgerufen werden, nicht unbedingt in der gleichen Reihenfolge, in der die überlappenden Vorgänge abgeschlossen werden. Es wird jedoch garantiert, dass die bereitgestellten Puffer in der angegebenen Reihenfolge gesendet werden.

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
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h (einschließen von Mswsock.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll