WSAJoinLeaf-Funktion (winsock2.h)
Die WSAJoinLeaf-Funktion verknüpft einen Blattknoten zu einer Mehrpunktsitzung, tauscht Verbindungsdaten aus und gibt die erforderliche Dienstqualität basierend auf den angegebenen FLOWSPEC-Strukturen an.
Syntax
SOCKET WSAAPI WSAJoinLeaf(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen,
[in] LPWSABUF lpCallerData,
[out] LPWSABUF lpCalleeData,
[in] LPQOS lpSQOS,
[in] LPQOS lpGQOS,
[in] DWORD dwFlags
);
Parameter
[in] s
Deskriptor, der einen Mehrpunktsocket identifiziert.
[in] name
Name des Peers, dem der Socket zugeordnet werden soll.
[in] namelen
Länge des Namens in Bytes.
[in] lpCallerData
Zeiger auf die Benutzerdaten, die während der Einrichtung von Mehrpunktsitzungen an den Peer übertragen werden sollen.
[out] lpCalleeData
Zeiger auf die Benutzerdaten, die während der Einrichtung von Mehrpunktsitzungen vom Peer zurück übertragen werden sollen.
[in] lpSQOS
Zeiger auf die FLOWSPEC-Strukturen für Sockets, eine für jede Richtung.
[in] lpGQOS
Reserviert für die zukünftige Verwendung mit Socketgruppen. Ein Zeiger auf die FLOWSPEC-Strukturen für die Socketgruppe (falls zutreffend).
[in] dwFlags
Flags, um anzugeben, dass der Socket als Absender (JL_SENDER_ONLY), Empfänger (JL_RECEIVER_ONLY) oder beides (JL_BOTH) fungiert.
Rückgabewert
Wenn kein Fehler auftritt, gibt WSAJoinLeaf einen Wert vom Typ SOCKET zurück, der ein Deskriptor für den neu erstellten Mehrpunktsocket ist. Andernfalls wird der Wert INVALID_SOCKET zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.
Auf einem blockierenden Socket gibt der Rückgabewert den Erfolg oder Fehler des Joinvorgangs an.
Bei einem nicht blockierenden Socket wird die erfolgreiche Einleitung eines Joinvorgangs durch die Rückgabe eines gültigen Socketdeskriptors angezeigt. Anschließend wird eine FD_CONNECT Angabe für den ursprünglichen Socket s angegeben, wenn der Verknüpfungsvorgang erfolgreich oder anderweitig abgeschlossen wird. Die Anwendung muss entweder WSAAsyncSelect oder WSAEventSelect mit für das FD_CONNECT-Ereignis registrierten Interesse verwenden, um zu bestimmen, wann der Joinvorgang abgeschlossen ist, und überprüft den zugehörigen Fehlercode, um den Erfolg oder Fehler des Vorgangs zu ermitteln. Die Select-Funktion kann nicht verwendet werden, um zu bestimmen, wann der Joinvorgang abgeschlossen ist.
Außerdem schlagen alle nachfolgenden Aufrufe von WSAJoinLeaf auf demselben Socket fehl, bis der Mehrpunktsitzungsbeitrittsversuch abgeschlossen ist, mit dem Fehlercode WSAEALREADY. Nachdem der WSAJoinLeaf-Vorgang erfolgreich abgeschlossen wurde, schlägt ein weiterer Versuch normalerweise mit dem Fehlercode WSAEISCONN fehl. Eine Ausnahme von der WSAEISCONN-Regel tritt für einen c_root Socket auf, der rootinitiierte Joins zulässt. In einem solchen Fall kann nach Abschluss eines vorherigen WSAJoinLeaf-Vorgangs ein weiterer Join initiiert werden.
Wenn der Rückgabefehlercode darauf hinweist, dass der Versuch der Mehrpunktsitzungsbeitritt fehlgeschlagen ist (d. h. WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), kann die Anwendung WSAJoinLeaf erneut für denselben Socket aufrufen.
| Fehlercode | Bedeutung |
|---|---|
| Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen. | |
| Die lokale Adresse des Sockets wird bereits verwendet, und der Socket wurde nicht markiert, um die Wiederverwendung von Adressen mit SO_REUSEADDR zu ermöglichen. Dieser Fehler tritt normalerweise zum Zeitpunkt der Bindung auf, kann jedoch bis zu dieser Funktion verzögert werden, wenn die Bindung an eine teilweise Aufplatzhalteradresse (mit ADDR_ANY) war und eine bestimmte Adresse zum Zeitpunkt dieser Funktion festgelegt werden muss. | |
| Die Remoteadresse ist keine gültige Adresse (z. B. ADDR_ANY). | |
| Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden. | |
| Für den angegebenen Socket wird ein nicht blockierender WSAJoinLeaf-Aufruf ausgeführt. | |
| Der Versuch, sich zu verbinden, wurde mit Nachkräften abgelehnt. | |
| Der Name oder der namelen-Parameter ist kein gültiger Teil des Benutzeradressraums, der namelen-Parameter ist zu klein, die Pufferlänge für lpCalleeData, lpSQOS und lpGQOS ist zu klein, oder die Pufferlänge für lpCallerData ist zu groß. | |
| Ein WSAJoinLeaf-Funktionsaufruf wurde für einen UDP-Socket ausgeführt, der geöffnet wurde, ohne dessen WSA_FLAG_MULTIPOINT_C_LEAF oder WSA_FLAG_MULTIPOINT_D_LEAF Mehrpunktflag festzulegen. | |
| Der Socket ist bereits Mitglied der Mehrpunktsitzung. | |
| Ein blockierender Windows Socket 1.1-Aufruf wurde über WSACancelBlockingCall abgebrochen. | |
| Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion. | |
| Beim Netzwerksubsystem ist ein Fehler aufgetreten. | |
| Das Netzwerk kann von diesem Host zurzeit nicht erreicht werden. | |
| Es ist kein Pufferplatz verfügbar. Der Socket kann nicht verknüpft werden. | |
| Der Deskriptor ist kein Socket. | |
| Die flowspec-Strukturen , die in lpSQOS und lpGQOS angegeben sind, können nicht erfüllt werden. | |
| Das lpCallerData-Augment wird vom Dienstanbieter nicht unterstützt. | |
| Der Versuch, einen Beitritt durchzuführen, ist ohne Einrichten einer Mehrpunktsitzung gezeitigt. |
Hinweise
Die WSAJoinLeaf-Funktion wird verwendet, um einen Blattknoten mit einer Mehrpunktsitzung zu verknüpfen, und um eine Reihe anderer hilfsseitiger Vorgänge auszuführen, die zur Sitzungsbeitrittszeit ausgeführt werden. Wenn der Socket s ungebunden ist, werden der lokalen Zuordnung vom System eindeutige Werte zugewiesen, und der Socket wird als gebunden markiert.
Die WSAJoinLeaf-Funktion verfügt über die gleichen Parameter und Semantik wie WSAConnect , mit der Ausnahme, dass sie einen Socketdeskriptor (wie in WSAAccept) zurückgibt und einen zusätzlichen dwFlags-Parameter enthält. Für Eingabeparameter in dieser Funktion können nur Mehrpunktsocket-Sockets verwendet werden, die mit WSASocket erstellt wurden und entsprechende Mehrpunktflags festgelegt sind. Der zurückgegebene Socketdeskriptor kann erst nach Abschluss des Joinvorgangs verwendet werden. Wenn sich der Socket beispielsweise im Nichtblockierungsmodus befindet, nachdem eine entsprechende FD_CONNECT Anzeige von WSAAsyncSelect oder WSAEventSelect für den ursprünglichen Socket s empfangen wurde, kann die Closesocket für diesen neuen Socketdeskriptor aufgerufen werden, um einen ausstehenden Verknüpfungsvorgang abzubrechen. Eine Stammanwendung in einer Mehrpunktsitzung kann WSAJoinLeaf ein oder mehrere Male aufrufen, um eine Reihe von Blattknoten hinzuzufügen, aber höchstens eine Mehrpunktverbindungsanforderung kann gleichzeitig ausstehen. Weitere Informationen finden Sie unter Multipoint- und Multicastsemantik .
Bei nicht blockierenden Sockets ist es oft nicht möglich, die Verbindung sofort abzuschließen. In einem solchen Fall gibt diese Funktion einen noch nicht verwendbaren Socketdeskriptor zurück, und der Vorgang wird fortgesetzt. In diesem Fall gibt es keinen Fehlercode wie WSAEWOULDBLOCK , da die Funktion effektiv eine erfolgreiche Startanzeige zurückgegeben hat. Wenn das endgültige Ergebnis erfolgreich oder fehlerhaft ist, kann es über WSAAsyncSelect oder WSAEventSelect gemeldet werden, je nachdem, wie sich der Client für die Benachrichtigung für die ursprünglichen Sockets registriert. In beiden Fällen wird die Benachrichtigung mit FD_CONNECT angekündigt, und der fehlercode, der dem FD_CONNECT zugeordnet ist, gibt entweder den Erfolg oder einen bestimmten Fehlergrund an. Die Select-Funktion kann nicht verwendet werden, um vervollständigungsbenachrichtigungen für WSAJoinLeaf zu erkennen.
Der von WSAJoinLeaf zurückgegebene Socketdeskriptor unterscheidet sich je nachdem, ob der Eingabesocketdeskriptor s ein c_root oder ein c_leaf ist. Bei Verwendung mit einem c_root Socket gibt der Name-Parameter einen bestimmten hinzuzufügenden Blattknoten an, und der zurückgegebene Socketdeskriptor ist ein c_leaf Socket, der dem neu hinzugefügten Blattknoten entspricht. Der neu erstellte Socket verfügt über die gleichen Eigenschaften wie s, einschließlich asynchroner Ereignisse, die mit WSAAsyncSelect oder WSAEventSelect registriert sind. Es ist nicht für den Austausch von Mehrpunktdaten vorgesehen, sondern dient zum Empfangen von Netzwerkereignisanzeigen (z. B. FD_CLOSE) für die Verbindung, die mit dem jeweiligen c_leaf besteht. Bei einigen Mehrpunktimplementierungen kann dieser Socket auch für Seitenchats zwischen dem Stamm und einem einzelnen Blattknoten verwendet werden. Für diesen Socket wird ein FD_CLOSE-Hinweis empfangen, wenn der entsprechende Blattknoten closesocket aufruft, um die Mehrpunktsitzung zu beenden. Symmetrisch bewirkt das Aufrufen von Closesocket auf dem c_leaf Socket, der von WSAJoinLeaf zurückgegeben wird, dazu, dass der Socket im entsprechenden Blattknoten eine FD_CLOSE Benachrichtigung erhält.
Wenn WSAJoinLeaf mit einem c_leaf Socket aufgerufen wird, enthält der Name-Parameter die Adresse der Stammanwendung (für ein rootendes Steuerelementschema) oder eine vorhandene Mehrpunktsitzung (Nicht-Stammsteuerungsschema), und der zurückgegebene Socketdeskriptor ist mit dem Eingabesocketdeskriptor identisch. Anders ausgedrückt: Ein neuer Socketdeskriptor wird nicht zugeordnet. In einem Root-Steuerelementschema würde die Stammanwendung ihren c_root Socket in den Lauschmodus versetzen, indem sie listen aufruft. Die Standardbenachrichtigung FD_ACCEPT wird übermittelt, wenn der Blattknoten anfordert, sich mit der Mehrpunktsitzung zu verbinden. Die Stammanwendung verwendet die üblichen Accept - oder WSAAccept-Funktionen , um den neuen Blattknoten zuzulassen. Der von accept oder WSAAccept zurückgegebene Wert ist auch ein c_leaf Socketdeskriptor, genau wie die von WSAJoinLeaf zurückgegebenen Werte. Um Mehrpunktschemas aufzunehmen, die sowohl root-initiierte als auch blattinitiierte Joins zulassen, ist es akzeptabel, dass ein c_root Socket, der sich bereits im Lauschmodus befindet, als Eingabe für WSAJoinLeaf verwendet wird.
Die Anwendung ist für die Zuweisung von Speicherplatz verantwortlich, auf den direkt oder indirekt durch einen der von ihr angegebenen Parameter verwiesen wird.
LpCallerData ist ein Wertparameter, der alle Benutzerdaten enthält, die zusammen mit der Mehrpunktsitzungsbeitrittsanforderung gesendet werden sollen. Wenn lpCallerDataNULL ist, werden keine Benutzerdaten an den Peer übergeben. LpCalleeData ist ein Ergebnisparameter, der alle Benutzerdaten enthält, die im Rahmen der Multipointsitzungseinrichtung vom Peer zurückgegeben werden. Das len-Element der WSABUF-Struktur , auf die der lpCalleeData-Parameter verweist, enthält zunächst die Länge des Puffers, der von der Anwendung zugeordnet ist, und auf den das buf-Element der WSABUF-Struktur verweist. Das len-Element der WSABUF-Struktur , auf die der lpCalleeData-Parameter verweist, wird auf 0 festgelegt, wenn keine Benutzerdaten zurückgegeben wurden. Die lpCalleeData-Informationen sind gültig, wenn der Multipoint-Joinvorgang abgeschlossen ist.
Wenn Sockets blockiert werden, gibt die WSAJoinLeaf-Funktion zurück. Bei Nichtblockierungssockets erfolgt dies nach Abschluss des Joinvorgangs. Dies kann z. B. nach FD_CONNECT Benachrichtigung für die ursprünglichen Sockets s) auftreten. Wenn lpCalleeDataNULL ist, werden keine Benutzerdaten zurückgegeben. Das genaue Format der Benutzerdaten bezieht sich auf die Adressfamilie, zu der der Socket gehört.
Bei der Einrichtung mehrerer Punktsitzungen kann eine Anwendung die Parameter lpSQOS und/oder lpGQOS verwenden, um jede vorherige Qualitätsspezifikation für den Socket über WSAIoctl mit den opcodes SIO_SET_QOS oder SIO_SET_GROUP_QOS außer Kraft zu setzen.
Der parameter lpSQOS gibt die FLOWSPEC-Strukturen für Sockets an, eine für jede Richtung, gefolgt von zusätzlichen anbieterspezifischen Parametern. Wenn entweder der zugeordnete Transportanbieter im Allgemeinen oder der spezifische Sockettyp im Besonderen die Servicequalitätsanforderung nicht einhalten kann, wird ein Fehler zurückgegeben, wie im Folgenden angegeben. Die entsprechenden Datenflussspezifikationswerte für das Senden oder Empfangen werden für alle unidirektionalen Sockets ignoriert. Wenn keine anbieterspezifischen Parameter angegeben werden, sollten die Elemente buf und len der WSABUF-Struktur , auf die der parameter lpCalleeData verweist, auf NULL bzw. null festgelegt werden. Ein NULL-Wert für lpSQOS gibt an, dass keine von der Anwendung bereitgestellte Dienstqualität bereitgestellt wird.
Reserviert für zukünftige Socketgruppen. Der lpGQOS-Parameter gibt die FLOWSPEC-Strukturen für die Socketgruppe an (falls zutreffend), eine für jede Richtung, gefolgt von zusätzlichen anbieterspezifischen Parametern. Wenn keine anbieterspezifischen Parameter angegeben werden, sollten die Elemente buf und len der WSABUF-Struktur , auf die vom parameter lpCalleeData verwiesen wird, auf NULL bzw. null festgelegt werden. Ein NULL-Wert für lpGQOS gibt an, dass keine von der Anwendung bereitgestellte Dienstqualitätsgruppe bereitgestellt wird. Dieser Parameter wird ignoriert, wenn s nicht der Ersteller der Socketgruppe ist.
Wenn verbundene Sockets unterbrochen werden (d. h. aus irgendeinem Grund geschlossen werden), sollten sie verworfen und neu erstellt werden. Es ist am sichersten anzunehmen, dass die Anwendung die benötigten Sockets verwerfen und neu erstellen muss, um zu einem stabilen Punkt zurückzukehren, wenn es aus irgendeinem Grund zu einem fehler kommt.
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 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winsock2.h |
| Bibliothek | Ws2_32.lib |
| DLL | Ws2_32.dll |