LPWSPASYNCSELECT-Rückruffunktion (ws2spi.h)
Die LPWSPAsyncSelect-Funktion fordert windows-nachrichtenbasierte Ereignisbenachrichtigungen von Netzwerkereignissen für einen Socket an.
Syntax
LPWSPASYNCSELECT Lpwspasyncselect;
int Lpwspasyncselect(
[in] SOCKET s,
[in] HWND hWnd,
[in] unsigned int wMsg,
[in] long lEvent,
[out] LPINT lpErrno
)
{...}
Parameter
[in] s
Deskriptor, der den Socket identifiziert, für den eine Ereignisbenachrichtigung erforderlich ist.
[in] hWnd
Behandeln Sie die Identifizierung des Fensters, das eine Nachricht empfangen soll, wenn ein Netzwerkereignis auftritt.
[in] wMsg
Nachricht, die gesendet werden soll, wenn ein Netzwerkereignis auftritt.
[in] lEvent
Bitmaske, die eine Kombination von Netzwerkereignissen angibt, an denen der SPI-Client (Windows Sockets Service Provider Interface) interessiert ist. Wird mithilfe des bitweisen OR-Operators mit einem dieser Werte erstellt.
Wert | Bedeutung |
---|---|
|
Probleme bei der Benachrichtigung über die Lesebereitschaft. |
|
Probleme bei der Benachrichtigung über die Schreibbereitschaft. |
|
Gibt Benachrichtigungen über das Eintreffen von OOB-Daten aus. |
|
Gibt Benachrichtigungen über eingehende Verbindungen aus. |
|
Probleme bei der Benachrichtigung über abgeschlossene Verbindungen. |
|
Probleme bei der Benachrichtigung beim Schließen des Sockets. |
|
Probleme bei der Benachrichtigung über Änderungen der Socketqualität des Diensts (QoS). |
|
Reserviert. |
|
Gibt Benachrichtigungen über Änderungen der Routingschnittstelle für das angegebene Ziel aus. |
|
Gibt Benachrichtigungen über die Änderung der lokalen Adressliste für die Protokollfamilie des Sockets aus. |
[out] lpErrno
Zeiger auf den Fehlercode. Weitere Informationen finden Sie im Abschnitt Rückgabewert .
Rückgabewert
Der Rückgabewert ist 0, wenn die Deklaration des Windows Sockets SPI-Clients im Netzwerkereignissatz erfolgreich war. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode ist in lpErrno verfügbar.
Fehlercode | Bedeutung |
---|---|
Beim Netzwerksubsystem ist ein Fehler aufgetreten. | |
Gibt an, dass einer der angegebenen Parameter ungültig war, z. B. das Fensterhandle, das nicht auf ein vorhandenes Fenster verweist, oder dass sich der angegebene Socket in einem ungültigen Zustand befindet. | |
Ein blockierter Windows Sockets-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion. | |
Der Deskriptor ist kein Socket. |
Informationen zu zusätzlichen Fehlercodes, die (im hohen Wort lParam in der Nachricht) festgelegt werden können, wenn ein Anwendungsfenster eine Nachricht empfängt, finden Sie unter Hinweise.
Hinweise
Diese Funktion wird verwendet, um anzufordern, dass der Dienstanbieter eine Windows-Nachricht an das Fenster hWnd des Clients sendet, wenn der Dienstanbieter eines der durch das lEvent-Argument angegebenen Netzwerkereignisse erkennt. Der Dienstanbieter sollte die WPUPostMessage-Funktion verwenden, um die Nachricht zu posten. Die zu sendende Nachricht wird durch den wMsg-Parameter angegeben. Der Socket, für den eine Benachrichtigung erforderlich ist, wird durch s identifiziert.
Diese Funktion legt Sockets unabhängig vom Wert von lEvent automatisch auf den Nichtblockierungsmodus fest. Informationen zum Zurücksetzen des Sockets auf den Blockiermodus finden Sie unter LPWSPIoctl .
Beim Aufrufen von LPWSPAsyncSelect für einen Socket werden alle vorherigen LPWSPAsyncSelect - oder LPWSPEventSelect-Instanzen für denselben Socket abgebrochen. Um beispielsweise Benachrichtigungen zum Lesen und Schreiben zu erhalten, muss der Windows Sockets SPI-Client LPWSPAsyncSelect sowohl mit FD_READ als auch mit FD_WRITE aufrufen.
rc = WSPAsyncSelect(s, hWnd, wMsg, FD_READ | FD_WRITE, &error);
Es ist nicht möglich, unterschiedliche Nachrichten für verschiedene Ereignisse anzugeben. Der folgende Code funktioniert nicht. Der zweite Aufruf bricht die Auswirkungen des ersten ab, und die einzige Zuordnung ist das FD_WRITE-Ereignis, das wMsg2 zugeordnet ist.
// Incorrect example.
rc = WSPAsyncSelect(s, hWnd, wMsg1, FD_READ, &error);
rc = WSPAsyncSelect(s, hWnd, wMsg2, FD_WRITE, &error);
Um alle Benachrichtigungen abzubrechen (d. h. um anzugeben, dass der Dienstanbieter keine weiteren Nachrichten im Zusammenhang mit Netzwerkereignissen auf dem Socket senden soll), legen Sie lEvent auf Null fest.
rc = WSPAsyncSelect(s, hWnd, 0, 0, &error);
Da ein LPWSPAccept-Socket dieselben Eigenschaften wie der für die Annahme verwendete Lauschocket aufweist, gelten alle LPWSPAsyncSelect-Ereignisse , die für den Lauschocket festgelegt sind, auf den akzeptierten Socket. Wenn ein Abhörsocket z. B. LPWSPAsyncSelect-Ereignisse FD_ACCEPT, FD_READ und FD_WRITE aufweist, weist jeder für diesen Socket akzeptierte Socket auch FD_ACCEPT-, FD_READ- und FD_WRITE-Ereignisse mit demselben wMsg-Wert auf, der für Nachrichten verwendet wird. Wenn ein anderes wMsg oder andere Ereignisse gewünscht werden, sollte der Windows Sockets SPI-Client LPWSPAsyncSelect aufrufen und den akzeptierten Socket und die gewünschten neuen Informationen übergeben.
Wenn eines der nominierten Netzwerkereignisse auf den angegebenen Sockets auftritt, verwendet der Dienstanbieter WPUPostMessage , um wMsg-Nachrichten an das Fenster hWnd des Windows Sockets SPI-Clients zu senden. In der geposteten Nachricht identifiziert das wParam-Argument den Socket, an dem ein Netzwerkereignis aufgetreten ist. Das niedrige Wort lParam gibt das aufgetretene Netzwerkereignis an. Die möglichen Netzwerkereigniscodes, die möglicherweise angegeben werden, sind wie folgt.
Wert | Bedeutung |
---|---|
FD_READ | Socket s ist zum Lesen bereit |
FD_WRITE | Socket s ist schreibbereit |
FD_OOB | Out-of-Band-Daten sind bereit für das Lesen von Sockets |
FD_ACCEPT | Socket s ist bereit, eine neue eingehende Verbindung zu akzeptieren |
FD_CONNECT | Die Verbindung, die für Socket s initiiert wurde, wurde abgeschlossen. |
FD_CLOSE | Die durch Socket s identifizierte Verbindung wurde geschlossen. |
FD_QOS | Die Dienstqualität im Zusammenhang mit Socket s hat sich geändert. |
FD_GROUP_QOS | Reserviert für zukünftige Verwendung mit Socketgruppen: Die Dienstqualität, die der Socketgruppe zugeordnet ist, zu der Socket s gehört, wurde geändert. |
FD_ROUTING_INTERFACE_CHANGE | Die lokale Schnittstelle, die zum Senden an das angegebene Ziel verwendet werden soll, wurde geändert. |
FD_ADDRESS_LIST_CHANGE | Die Liste der Adressen der Protokollfamilie des Sockets, an die der Windows Sockets SPI-Client gebunden werden kann, wurde geändert. |
Das hohe Wort lParam enthält beliebigen Fehlercode (kann mithilfe des WSAGETSELECTERROR-Makros extrahiert werden). Der Fehlercode ist ein beliebiger Fehler, der in ws2spi.h
definiert ist. Mögliche Fehlercodes für jedes Netzwerkereignis sind in der folgenden Tabelle aufgeführt.
Ereignis: FD_CONNECT
Fehlercode | Bedeutung |
---|---|
Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden. | |
Der Versuch, eine Verbindung herzustellen, wurde abgelehnt. | |
Das Netzwerk kann von diesem Host zurzeit nicht erreicht werden. | |
Der namelen-Parameter ist ungültig. | |
Der Socket ist bereits an eine Adresse gebunden. | |
Der Socket ist bereits verbunden. | |
Es sind keine Dateideskriptoren mehr verfügbar. | |
Es ist kein Pufferplatz verfügbar. Der Socket kann nicht verbunden werden. | |
Der Socket ist nicht verbunden. | |
Zeitüberschreitung beim Verbindungsversuch, ohne eine Verbindung herzustellen. |
Ereignis: FD_CLOSE
Fehlercode | Bedeutung |
---|---|
Fehler beim Netzwerksubsystem. | |
Die Verbindung wurde von der Remoteseite zurückgesetzt. | |
Die Verbindung wurde aufgrund eines Timeouts oder eines anderen Fehlers beendet. |
Event...: FD_ACCEPT, FD_ADDRESS_LIST_CHANGE, FD_GROUP_QOS, FD_OOB, FD_QOS, FD_READ, FD_WRITE
Fehlercode | Bedeutung |
---|---|
Fehler beim Netzwerksubsystem. |
Ereignis: FD_ROUTING_INTERFACE_CHANGE
Fehlercode | Bedeutung |
---|---|
Das angegebene Ziel ist nicht mehr erreichbar. | |
Fehler beim Netzwerksubsystem. |
Obwohl LPWSPAsyncSelect mit Interesse an mehreren Ereignissen aufgerufen werden kann, gibt der Dienstanbieter für jedes Ereignis dieselbe Windows-Nachricht aus.
Ein Windows Sockets 2-Anbieter sollte einen Windows Sockets SPI-Client nicht ständig mit Nachrichten für ein bestimmtes Netzwerkereignis überfluten. Nachdem die Benachrichtigung über ein bestimmtes Ereignis erfolgreich an ein Windows Sockets SPI-Clientfenster gesendet wurde, werden keine weiteren Nachrichten für dieses Netzwerkereignis an das Windows Sockets SPI-Clientfenster gesendet, bis der SPI-Client von Windows Sockets den Funktionsaufruf vornimmt, der die Benachrichtigung über dieses Netzwerkereignis implizit wieder aktiviert.
Netzwerkereignis | Erneutes Aktivieren der Funktion |
---|---|
FD_READ | LPWSPRecv oder LPWSPRecvFrom |
FD_WRITE | LPWSPSend oder LPWSPSendTo |
FD_OOB | LPWSPRecv oder LPWSPRecvFrom |
FD_ACCEPT | LPWSPAccept, es sei denn, der zurückgegebene Fehlercode ist WSATRY_AGAIN, der angibt, dass die zurückgegebene Bedingungsfunktion CF_DEFER |
FD_CONNECT | Keine |
FD_CLOSE | Keine |
FD_QOS | LPWSPIoctl mit SIO_GET_QOS |
FD_GROUP_QOS | Reserviert für die zukünftige Verwendung mit Socketgruppen: LPWSPIoctl mit SIO_GET_GROUP_QOS |
FD_ROUTING_INTERFACE_CHANGE | LPWSPIoctl mit Befehl SIO_ROUTING_INTERFACE_CHANGE |
FD_ADDRESS_LIST_CHANGE | LPWSPIoctl mit Befehl SIO_ADDRESS_LIST_CHANGE |
Jeder Aufruf der Wiederaktivierungsroutine, auch einer, der fehlschlägt, führt dazu, dass die Nachrichtenposting für das relevante Ereignis erneut aktiviert wird.
Für FD_READ-, FD_OOB- und FD_ACCEPT-Ereignisse wird die Nachrichtenpostingebene ausgelöst. Dies bedeutet, dass eine LPWSPAsyncSelect-Nachricht an den SPI-Client von Windows Sockets gesendet wird, wenn die Wiederaktivierungsroutine aufgerufen wird und die relevante Bedingung nach dem Aufruf weiterhin erfüllt ist.
Die FD_QOS- und FD_GROUP_QOS-Ereignisse gelten als edgetriggeriert. Eine Nachricht wird genau einmal gesendet, wenn eine QOS-Änderung auftritt. Weitere Meldungen werden erst angezeigt, wenn der Anbieter eine weitere Änderung in QOS erkennt oder der SPI-Client von Windows Sockets die QOS für den Socket neu aushandelt.
Die ereignisse FD_ROUTING_INTERFACE_CHANGE und FD_ADDRESS_LIST_CHANGE werden ebenfalls als edgeauslöst betrachtet. Eine Meldung wird genau dann gesendet, wenn eine Änderung eintritt, nachdem der SPI-Client von Windows Sockets die Benachrichtigung angefordert hat, indem WSAIoctl mit SIO_ROUTING_INTERFACE_CHANGE oder SIO_ADDRESS_LIST_CHANGE entsprechend ausgegeben wird. Weitere Meldungen werden erst angezeigt, wenn der SPI-Client von Windows Sockets die IOCTL erneut ausstellt und eine weitere Änderung erkannt wird, da die IOCTL ausgestellt wurde.
Wenn bereits ein Ereignis aufgetreten ist, wenn der Windows Sockets SPI-Client LPWSPAsyncSelect aufruft oder wenn die Funktion zum erneuten Aktivieren aufgerufen wird, wird eine entsprechende Meldung gesendet. Betrachten Sie beispielsweise die folgende Sequenz.
- Ein Windows Sockets SPI-Client ruft LPWSPListen auf.
- Eine Verbindungsanforderung wird empfangen, aber noch nicht akzeptiert.
- Der Spi-Client von Windows Sockets ruft LPWSPAsyncSelect auf und gibt an, dass er FD_ACCEPT Nachrichten für den Socket empfangen möchte. Aufgrund der Persistenz von Ereignissen sendet der WinSock-Dienstanbieter sofort eine FD_ACCEPT Nachricht.
Das FD_WRITE-Ereignis wird etwas anders behandelt. Eine FD_WRITE-Meldung wird gesendet, wenn ein Socket zuerst mit LPWSPConnect verbunden ist (nach FD_CONNECT, falls auch registriert) oder mit LPWSPAccept akzeptiert wird, und dann, nachdem ein LPWSPSend oder LPWSPSendTo mit WSAEWOULDBLOCK fehlschlägt und Pufferspeicher verfügbar wird. Daher kann ein Windows Sockets SPI-Client davon ausgehen, dass Absendungen ab der ersten FD_WRITE Nachricht möglich sind, bis ein Sendevorgang WSAEWOULDBLOCK zurückgibt. Nach einem solchen Fehler wird der SPI-Client von Windows Sockets benachrichtigt, dass Senden mit einer FD_WRITE Nachricht wieder möglich sind.
Das FD_OOB-Ereignis wird nur verwendet, wenn ein Socket für den getrennten Empfang von Out-of-Band-Daten konfiguriert ist. Wenn der Socket so konfiguriert ist, dass er Out-of-Band-Daten inline empfängt, werden die Out-of-Band-Daten (beschleunigt) wie normale Daten behandelt, und der SPI-Client von Windows Sockets muss ein Interesse an FD_READ Ereignissen registrieren, nicht an FD_OOB Ereignissen.
Der Fehlercode in einer FD_CLOSE Meldung gibt an, ob das Schließen des Sockets ordnungsgemäß oder abgebrochen war. Wenn der Fehlercode 0 ist, war das Schließen ordnungsgemäß; Wenn der Fehlercode WSAECONNRESET lautet, wurde die virtuelle Verbindung des Sockets zurückgesetzt. Dies gilt nur für verbindungsorientierte Sockets wie SOCK_STREAM.
Die FD_CLOSE Meldung wird gesendet, wenn für die virtuelle Verbindung, die dem Socket entspricht, ein Close-Hinweis empfangen wird. In TCP bedeutet dies, dass die FD_CLOSE bereitgestellt wird, wenn die Verbindung in den Status TIME WAIT oder CLOSE WAIT wechselt. Dies ergibt sich daraus, dass das Remote-Ende einen LPWSPShutdown auf der Sendeseite oder ein LPWSPCloseSocket ausführt. Es ist richtig, dass FD_CLOSE erst veröffentlicht werden, nachdem alle Daten aus einem Socket gelesen wurden.
Im Falle eines ordnungsgemäßen Schließens sollte der Dienstanbieter erst nach dem Lesen aller empfangenen Daten eine FD_CLOSE-Nachricht senden, um den Abschluss der virtuellen Verbindung anzugeben. Es sollte keine FD_READ Nachricht senden, um diese Bedingung anzugeben.
Die FD_QOS- oder FD_GROUP_QOS-Nachricht wird gesendet, wenn eine Änderung an einem Beliebigen Feld in der Flowspezifikation vorgenommen wurde, die Sockets zugeordnet ist, bzw. an der Socketgruppe, zu der s gehört. Der Dienstanbieter muss die QOS-Informationen aktualisieren, die dem Client über LPWSPIoctl mit SIO_GET_QOS und/oder SIO_GET_GROUP_QOS zur Verfügung stehen.
Die FD_ROUTING_INTERFACE_CHANGE Meldung wird gesendet, wenn die lokale Schnittstelle, die verwendet werden soll, um das in LPWSPIoctl angegebene Ziel mit SIO_ROUTING_INTERFACE_CHANGE Änderungen zu erreichen, nachdem eine solche IOCTL ausgestellt wurde.
Die FD_ADDRESS_LIST_CHANGE Meldung wird gesendet, wenn die Liste der Adressen, an die der Windows Sockets SPI-Client Änderungen binden kann , nachdemLPWSPIoctl mit SIO_ADDRESS_LIST_CHANGE ausgestellt wurde.
Hier ist eine Zusammenfassung der Ereignisse und Bedingungen für jede asynchrone Benachrichtigung.
FD_READ
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn derzeit Daten zum Empfangen verfügbar sind.
- Wenn Daten eingehen, wenn FD_READ noch nicht veröffentlicht.
- Nachdem LPWSPRecv oder LPWSPRecvFrom aufgerufen wurde (mit oder ohne MSG_PEEK), wenn noch Daten zum Empfangen verfügbar sind.
Wenn LPWSPSetSockOpt SO_OOBINLINE aktiviert ist, enthalten Daten sowohl normale Daten als auch Out-of-Band-Daten (OOB) in den oben genannten Instanzen.
FD_WRITE
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn ein LPWSPSend oder LPWSPSendTo möglich ist.
- Nachdem LPWSPConnect oder LPWSPAccept aufgerufen wurde, wenn die Verbindung hergestellt wurde.
- Nach LPWSPSend oder LPWSPSendTo schlägt WSAEWOULDBLOCK fehl, wenn LPWSPSend oder LPWSPSendTo wahrscheinlich erfolgreich sind.
- Nach LPWSPBind auf einem verbindungslosen Socket. FD_WRITE kann zu diesem Zeitpunkt auftreten (implementierungsabhängig). In jedem Fall ist ein verbindungsloser Socket immer unmittelbar nach LPWSPBind beschreibbar.
FD_OOB (nur gültig, wenn LPWSPSetSockOpt SO_OOBINLINE deaktiviert ist (Standard))
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn derzeit OOB-Daten mit dem MSG_OOB-Flag empfangen werden können.
- Wenn OOB-Daten eintreffen, wenn FD_OOB noch nicht veröffentlicht.
- Nachdem LPWSPRecv oder LPWSPRecvFrom mit oder ohne MSG_OOB Flag aufgerufen wurde, wenn OOB-Daten noch zum Empfangen verfügbar sind.
FD_ACCEPT
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn derzeit eine Verbindungsanforderung zur Annahme verfügbar ist.
- Wenn eine Verbindungsanforderung eingeht, wenn FD_ACCEPT noch nicht veröffentlicht.
- Nach dem Aufruf von LPWSPAccept , wenn eine andere Verbindungsanforderung zur Annahme verfügbar ist.
FD_CONNECT
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn derzeit eine Verbindung hergestellt wird.
- Nach dem Aufruf von LPWSPConnect , wenn die Verbindung hergestellt wird (auch wenn LPWSPConnect sofort erfolgreich ist, wie es bei einem Datagrammsocket üblich ist) und auch dann, wenn die Verbindung sofort fehlschlägt).
- Nachdem WSPJoinLeaf aufgerufen wurde, wenn der Joinvorgang abgeschlossen ist.
- Nach der Verbindung wurde WSAConnect oder WSPJoinLeaf mit einem nicht blockierenden, verbindungsorientierten Socket aufgerufen. Der anfängliche Vorgang wurde mit einem bestimmten Fehler von WSAEWOULDBLOCK zurückgegeben, aber der Netzwerkvorgang wurde ausgeführt. Ob der Vorgang letztendlich erfolgreich ist oder nicht, wenn das Ergebnis bestimmt wurde, geschieht FD_CONNECT. Der Client sollte den Fehlercode überprüfen, um zu ermitteln, ob das Ergebnis ein Erfolg oder ein Fehler war.
FD_CLOSE (gilt nur für verbindungsorientierte Sockets (z. B. SOCK_STREAM))
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn die Socketverbindung geschlossen wurde.
- Nachdem das Remotesystem eine ordnungsgemäße Schließung initiiert hat, wenn derzeit keine Daten zum Empfangen verfügbar sind (wenn Daten empfangen wurden und darauf warten, gelesen zu werden, wenn das Remotesystem eine ordnungsgemäße Schließung initiiert, wird die FD_CLOSE erst übermittelt, wenn alle ausstehenden Daten gelesen wurden).
- Nachdem das lokale System einen ordnungsgemäßen Abschluss mit LPWSPShutdown initiiert hat und das Remotesystem mit einer Datenendebenachrichtigung (z. B. TCP FIN) geantwortet hat, wenn derzeit keine Daten für den Empfang verfügbar sind.
- Wenn das Remotesystem die Verbindung abbricht (z. B. TCP RST gesendet), enthält lParam den WSAECONNRESET-Fehlerwert.
FD_CLOSE wird nach dem Aufruf von LPWSPCloseSocket nicht gepostet.
FD_QOS
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn das dem Socket zugeordnete QOS geändert wurde.
- Nachdem LPWSPIoctl mit SIO_GET_QOS aufgerufen wird, wenn das QOS geändert wird.
FD_GROUP_QOS
Reserviert für die zukünftige Verwendung mit Socketgruppen:
- Wenn LPWSPAsyncSelect aufgerufen wird, wenn die QOS-Gruppe, die dem Socket zugeordnet ist, geändert wurde.
- Nachdem LPWSPIoctl mit SIO_GET_GROUP_QOS aufgerufen wird, wenn die Gruppen-QOS geändert wird.
FD_ROUTING_INTERFACE_CHANGE
- nachdem LPWSPIoctl mit SIO_ROUTING_INTERFACE_CHANGE aufgerufen wurde, wenn sich die lokale Schnittstelle ändert, die zum Erreichen des in der IOCTL angegebenen Ziels verwendet werden soll.
FD_ADDRESS_LIST_CHANGE
- nachdem LPWSPIoctl mit SIO_ADDRESS_LIST_CHANGE aufgerufen wurde, wenn die Liste der lokalen Adressen, an die der Windows Sockets SPI-Client Änderungen binden kann.
Anforderungen
Anforderung | Wert |
---|---|
Unterstützte Mindestversion (Client) | Windows 10 Build 20348 |
Unterstützte Mindestversion (Server) | Windows 10 Build 20348 |
Kopfzeile | ws2spi.h |
Weitere Informationen
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für