LPWSPSENDTO-Rückruffunktion (ws2spi.h)

Die LPWSPSendTo-Funktion sendet Daten mithilfe von überlappenden E/A-Vorgängen an ein bestimmtes Ziel.

Syntax

LPWSPSENDTO Lpwspsendto;

int Lpwspsendto(
  [in]  SOCKET s,
  [in]  LPWSABUF lpBuffers,
  [in]  DWORD dwBufferCount,
  [out] LPDWORD lpNumberOfBytesSent,
  [in]  DWORD dwFlags,
  [in]  const sockaddr *lpTo,
  [in]  int iTolen,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  [in]  LPWSATHREADID lpThreadId,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Ein Deskriptor, der einen Socket identifiziert.

[in] lpBuffers

Ein Zeiger auf ein Array von WSABUF-Strukturen . Jede WSABUF-Struktur enthält einen Zeiger auf einen Puffer und die Länge des Puffers in Bytes. Wenn die LPWSPSendTo-Funktion für eine Winsock-Anwendung aufgerufen wurde, besitzt das System diese Puffer, und die Anwendung greift möglicherweise nicht darauf zu. Datenpuffer, auf die in jeder WSABUF-Struktur verwiesen wird, gehören dem System, und Ihre Anwendung greift möglicherweise während der Lebensdauer des Aufrufs nicht darauf zu.

[in] dwBufferCount

Die Anzahl der WSABUF-Strukturen im lpBuffers-Array .

[out] lpNumberOfBytesSent

Ein Zeiger auf die Anzahl von Bytes, die von diesem Aufruf gesendet werden.

[in] dwFlags

Ein Satz von Flags, der die Art und Weise angibt, in der der Aufruf erfolgt.

[in] lpTo

Ein optionaler Zeiger auf die Adresse des Zielsockets in der sockaddr-Struktur .

[in] iTolen

Die Größe der Adresse in Bytes, auf die der lpTo-Parameter verweist.

[in] lpOverlapped

Ein Zeiger auf eine WSAOverlapped-Struktur (wird bei nicht überlappten Sockets ignoriert).

[in] lpCompletionRoutine

Typ: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Ein Zeiger auf die Vervollständigungsroutine, die aufgerufen wird, wenn der Sendevorgang abgeschlossen wurde (wird bei nicht überlappten Sockets ignoriert).

[in] lpThreadId

Ein Zeiger auf eine WSATHREADID-Struktur , die vom Anbieter in einem nachfolgenden Aufruf von WPUQueueApc verwendet werden soll. Der Anbieter sollte die referenzierte WSATHREADID-Struktur (nicht den Zeiger auf dieselbe) speichern, bis die WPUQueueApc-Funktion zurückgegeben wird.

[out] lpErrno

Ein Zeiger auf den Fehlercode.

Rückgabewert

Wenn kein Fehler auftritt und der Empfangsvorgang sofort abgeschlossen wurde, gibt LPWSPSendTo null zurück. Beachten Sie, dass in diesem Fall die Vervollständigungsroutine, sofern angegeben, bereits in die Warteschlange eingereiht wurde. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode ist in lpErrno verfügbar. Der Fehlercode WSA_IO_PENDING gibt an, dass der überlappende Vorgang erfolgreich initiiert wurde und dass der Abschluss zu einem späteren Zeitpunkt angezeigt wird. Jeder andere Fehlercode gibt an, dass kein überlappender Vorgang initiiert wurde und keine Abschlussanzeige erfolgt.

Fehlercode Bedeutung
WSAENETDOWN
Fehler beim Netzwerksubsystem.
WSAEACCES
Die angeforderte Adresse ist eine Broadcastadresse, aber das entsprechende Flag wurde nicht festgelegt.
WSAEINTR
Der (Blockierende) Anruf wurde über LPWSPCancelBlockingCall abgebrochen.
WSAEINPROGRESS
Der Windows Sockets-Aufruf wird blockiert, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion.
WSAEFAULT
Die Parameter lpBuffers oder lpTo sind nicht Teil des Benutzeradressraums, oder der lpTo-Parameter ist zu klein.
WSAENETRESET
Die Verbindung wurde unterbrochen, weil eine Keep-Alive-Aktivität einen Fehler erkannt hat, während der Vorgang ausgeführt wurde.
WSAENOBUFS
Der Windows Sockets-Anbieter meldet einen Puffer-Deadlock.
WSAENOTCONN
Socket ist nicht verbunden (nur verbindungsorientierte Sockets).
WSAENOTSOCK
Der Deskriptor ist kein Socket.
WSAEOPNOTSUPP
MSG_OOB angegeben wurde, aber der Socket nicht im Streamstil verwendet wird, z. B. typ SOCK_STREAM, werden OOB-Daten in der diesem Socket zugeordneten Kommunikationsdomäne nicht unterstützt, MSG_PARTIAL wird nicht unterstützt, oder der Socket ist unidirektional und unterstützt nur Empfangsvorgänge.
WSAESHUTDOWN
Socket wurde heruntergefahren; Es ist nicht möglich , LPWSPSendTo auf einem Socket zu verwenden, nachdem LPWSPShutdown aufgerufen wurde und wie auf SD_SEND oder SD_BOTH festgelegt wurde.
WSAEWOULDBLOCK
Windows NT: Ü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.
WSAEMSGSIZE
Socket ist nachrichtenorientiert, und die Nachricht ist größer als die maximale, die vom zugrunde liegenden Transport unterstützt wird.
WSAEINVAL
Der Socket wurde nicht an LPWSPBind gebunden, oder der Socket wird nicht mit dem überlappenden Flag erstellt.
WSAECONNABORTED
Die virtuelle Verbindung wurde aufgrund eines Timeouts oder eines anderen Fehlers beendet.
WSAECONNRESET
Die virtuelle Verbindung wurde von der Remoteseite zurückgesetzt.
WSAEADDRNOTAVAIL
Die Remoteadresse ist keine gültige Adresse (z. B. ADDR_ANY).
WSAEAFNOSUPPORT
Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden.
WSAEDESTADDRREQ
Die Zieladresse ist erforderlich.
WSAENETUNREACH
Das Netzwerk kann von diesem Host zurzeit nicht erreicht werden.
WSA_OPERATION_ABORTED
Der überlappende Vorgang wurde aufgrund des Schließens des Sockets oder der Ausführung des befehls SIO_FLUSH in LPWSPIoctl abgebrochen.

Hinweise

Die LPWSPSendTo-Funktion wird normalerweise für einen verbindungslosen Socket verwendet, der von s angegeben wird, um ein In einem oder mehreren Puffern enthaltenes Datagramm an einen bestimmten Peersocket zu senden, der durch den lpTo-Parameter identifiziert wird. Auch wenn der verbindungslose Socket zuvor mit der LPWSPConnect-Funktion mit einer bestimmten Adresse verbunden wurde, überschreibt lpTo nur die Zieladresse für dieses bestimmte Datagramm. In einem verbindungsorientierten Socket werden die Parameter lpTo und iToLen ignoriert. in diesem Fall entspricht die LPWSPSendTo-FunktionLPWSPSend.

Bei überlappenden Sockets (erstellt mit LPWSPSocket mit Flag WSA_FLAG_OVERLAPPED) tritt dies mithilfe von überlappenden E/A-Vorgängen auf, es sei denn, sowohl lpOverlapped als auch lpCompletionRoutine sind NULL . In diesem Fall wird der Socket als nicht überlappender Socket behandelt. Eine Vervollständigungsanzeige (Aufruf der Vervollständigungsroutine oder Einstellung eines Ereignisobjekts) tritt auf, wenn die bereitgestellten Puffer vom Transport verbraucht wurden. Wenn der Vorgang nicht sofort abgeschlossen wird, wird der endgültige Abschluss status über die Abschlussroutine oder LPWSPGetOverlappedResult abgerufen.

Bei nicht überlappten Sockets werden die Parameter lpOverlapped, lpCompletionRoutine und lpThreadId ignoriert, und LPWSPSendTo verwendet die reguläre synchrone Semantik. Daten werden aus den bereitgestellten 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, wird LPWSPSendTo zurückgegeben, wobei nur ein Teil der Puffer des Windows Sockets SPI-Clients verbraucht wurde. Aufgrund derselben Puffersituation und eines blockierenden Sockets blockiert LPWSPSendTo , bis alle Pufferinhalte des Windows Sockets SPI-Clients verbraucht wurden.

Das Array von WSABUF-Strukturen , auf das der lpBuffers-Parameter verweist, ist vorübergehend. Wenn dieser Vorgang auf überlappende Weise abgeschlossen wird, liegt es in der Verantwortung des Dienstanbieters, diese WSABUF-Strukturen zu erfassen, bevor von diesem Aufruf zurückgegeben wird. Dadurch können Anwendungen stapelbasierte WSABUF-Arrays erstellen.

Bei nachrichtenorientierten Sockets muss darauf geachtet werden, dass die maximale Nachrichtengröße des zugrunde liegenden Transports 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 über das zugrunde liegende Protokoll zu übergeben, wird der Fehler WSAEMSGSIZE zurückgegeben, und es werden keine Daten übertragen.

Beachten Sie, dass der erfolgreiche Abschluss eines LPWSPSendTo nicht darauf hinweist, dass die Daten erfolgreich übermittelt wurden.

Der iFlags-Parameter 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 dieses Flag ignorieren.
MSG_OOB Sendet OOB-Daten (nur Socket im Streamformat, z. B. SOCK_STREAM).
MSG_PARTIAL Gibt an, dass 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.

 

 

Wenn ein überlappender Vorgang sofort abgeschlossen wird, gibt LPWSPSendTo 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 LPWSPSendTo 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 LPWSPGetOverlappedResult angegeben.

Anbieter müssen zulassen, dass diese Funktion innerhalb der Vervollständigungsroutine einer früheren LPWSPRecv-, LPWSPRecvFrom-, LPWSPSend - oder LPWSPSendTo-Funktion aufgerufen wird. Für einen bestimmten Socket können E/A-Vervollständigungsroutinen jedoch nicht geschachtelt 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 überlappende Struktur verweisen. Die WSAOverlapped-Struktur wird auf einer eigenen Referenzseite definiert.

Wenn der lpCompletionRoutine-ParameterNULL ist, signalisiert der Dienstanbieter das hEvent-Member von lpOverlapped , wenn der überlappende Vorgang abgeschlossen wird, wenn er ein gültiges Ereignisobjekthandle enthält. Windows Sockets SPI-Clients können LPWSPGetOverlappedResult verwenden, um das Ereignisobjekt zu warten oder abzufragen.

Wenn lpCompletionRoutine nicht NULL ist, wird der hEvent-Member ignoriert und kann vom Windows Sockets SPI-Client verwendet werden, um Kontextinformationen an die Vervollständigungsroutine zu übergeben. Ein Client, der eine Nicht-Null-LpCompletionRoutine ü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-Members nicht definiert, und der Versuch, auf das hEvent-Element zu warten, führt zu unvorhersehbaren Ergebnissen.

Es liegt in der Verantwortung des Dienstanbieters, den Aufruf der clientspezifischen Vervollständigungsroutine zu veranlassen, wenn der überlappende Vorgang abgeschlossen ist. Da die Vervollständigungsroutine im Kontext desselben Threads ausgeführt werden muss, der den überlappenden Vorgang initiiert hat, kann sie nicht direkt vom Dienstanbieter aufgerufen werden. Die Ws2_32.dll bietet einen Asynchronen Prozeduraufrufmechanismus (APC), um den Aufruf von Vervollständigungsroutinen zu erleichtern.

Ein Dienstanbieter sorgt dafür, dass eine Funktion im richtigen Thread ausgeführt wird, indem WPUQueueApc aufgerufen wird. Diese Funktion kann aus jedem Prozess- und Threadkontext aufgerufen werden, auch aus einem anderen Kontext als dem Thread und prozess, der zum Initiieren des überlappenden Vorgangs verwendet wurde.

Die WPUQueueApc-Funktion verwendet als Eingabeparameter einen Zeiger auf eine WSATHREADID-Struktur (die dem Anbieter über den lpThreadId-Eingabeparameter bereitgestellt wird), einen Zeiger auf eine aufzurufende APC-Funktion und einen Kontextwert, der anschließend an die APC-Funktion übergeben wird. Da nur ein einzelner Kontextwert verfügbar ist, kann die APC-Funktion selbst nicht die clientspezifische Vervollständigungsroutine sein. Der Dienstanbieter muss stattdessen einen Zeiger auf seine eigene APC-Funktion bereitstellen, die den angegebenen Kontextwert verwendet, um auf die erforderlichen Ergebnisinformationen für den überlappenden Vorgang zuzugreifen, und dann die clientspezifische Vervollständigungsroutine aufruft.

Der Prototyp für die vom Client bereitgestellte Vervollständigungsroutine lautet wie folgt.

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

Die CompletionRoutine ist ein Platzhalter für einen vom Client bereitgestellten Funktionsnamen. dwError gibt die Vervollständigung status für den überlappenden Vorgang an, wie durch lpOverlapped angegeben. cbTransferred gibt die Anzahl der gesendeten Bytes an. Derzeit sind keine Flagwerte definiert, und der dwFlags-Wert ist 0. Diese Funktion gibt keinen Wert zurück.

Die Vervollständigungsroutinen können in beliebiger Reihenfolge aufgerufen werden, allerdings nicht unbedingt in der reihenfolge, in der die überlappenden Vorgänge abgeschlossen werden. Der Dienstanbieter garantiert jedoch dem Client, dass gebuchte Puffer in der gleichen Reihenfolge gesendet werden, in der sie bereitgestellt werden.

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 .

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Kopfzeile ws2spi.h

Weitere Informationen

WPUQueueApc

LPWSPGetOverlappedResult

LPWSPSocket