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 |
|---|---|
| Fehler beim Netzwerksubsystem. | |
| Die angeforderte Adresse ist eine Broadcastadresse, aber das entsprechende Flag wurde nicht festgelegt. | |
| Der (Blockierende) Anruf wurde über LPWSPCancelBlockingCall abgebrochen. | |
| Der Windows Sockets-Aufruf wird blockiert, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion. | |
| Die Parameter lpBuffers oder lpTo sind nicht Teil des Benutzeradressraums, oder der lpTo-Parameter ist zu klein. | |
| Die Verbindung wurde unterbrochen, weil eine Keep-Alive-Aktivität einen Fehler erkannt hat, während der Vorgang ausgeführt wurde. | |
| Der Windows Sockets-Anbieter meldet einen Puffer-Deadlock. | |
| Socket ist nicht verbunden (nur verbindungsorientierte Sockets). | |
| Der Deskriptor ist kein Socket. | |
| 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. | |
| 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. | |
| 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. | |
| Socket ist nachrichtenorientiert, und die Nachricht ist größer als die maximale, die vom zugrunde liegenden Transport unterstützt wird. | |
| Der Socket wurde nicht an LPWSPBind gebunden, oder der Socket wird nicht mit dem überlappenden Flag erstellt. | |
| Die virtuelle Verbindung wurde aufgrund eines Timeouts oder eines anderen Fehlers beendet. | |
| Die virtuelle Verbindung wurde von der Remoteseite zurückgesetzt. | |
| Die Remoteadresse ist keine gültige Adresse (z. B. ADDR_ANY). | |
| Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden. | |
| Die Zieladresse ist erforderlich. | |
| Das Netzwerk kann von diesem Host zurzeit nicht erreicht werden. | |
| 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 |