LPWSPJOINLEAF-Rückruffunktion (ws2spi.h)
Die WSPJoinLeaf-Funktion verknüpft einen Blattknoten zu einer Mehrpunktsitzung, tauscht Verbindungsdaten aus und gibt die erforderliche Dienstqualität basierend auf den bereitgestellten Flussspezifikationen an.
Syntax
LPWSPJOINLEAF Lpwspjoinleaf;
SOCKET Lpwspjoinleaf(
[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,
[out] LPINT lpErrno
)
{...}
Parameter
[in] s
Deskriptor, der einen Mehrpunktsocket identifiziert.
[in] name
Name des Peers, dem der Socket in der sockaddr-Struktur 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 Flussspezifikationen für Sockets, eins für jede Richtung.
[in] lpGQOS
Reserviert.
[in] dwFlags
Flags, um anzugeben, dass der Socket als Absender, Empfänger oder beides fungiert.
[out] lpErrno
Zeiger auf den Fehlercode.
Rückgabewert
Wenn kein Fehler auftritt, gibt WSPJoinLeaf 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 ist in lpErrno verfügbar.
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 den Rückgabewert eines gültigen Socketdeskriptors angezeigt. Anschließend wird eine FD_CONNECT Angabe angegeben, wenn der Verknüpfungsvorgang erfolgreich oder anderweitig abgeschlossen wird. Der dem FD_CONNECT zugeordnete Fehlercode gibt den Erfolg oder Fehler des WSPJoinLeaf an.
Außerdem schlagen alle nachfolgenden Aufrufe von WSPJoinLeaf auf demselben Socket mit dem Fehlercode WSAEALREADY fehl, bis der Mehrpunktsitzungsbeitrittsversuch abgeschlossen ist. Nachdem WSPJoinLeaf erfolgreich abgeschlossen wurde, schlägt ein nachfolgender 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 WSPJoinLeafs ein weiterer Join initiiert werden.
Wenn der Rückgabefehlercode darauf hinweist, dass der Versuch der Mehrpunktsitzungsbeitritt fehlgeschlagen ist (d. h. WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), kann der Windows Sockets SPI-Client WSPJoinLeaf erneut für denselben Socket aufrufen.
| Fehlercode | Bedeutung |
|---|---|
| Beim Netzwerksubsystem ist ein Fehler aufgetreten. | |
| 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 **bind** an eine teilweise wild-Karte-Adresse (mit ADDR_ANY) war und wenn eine bestimmte Adresse zum Zeitpunkt dieser Funktion "commitiert" werden muss. | |
| Der (blockierende) Aufruf wurde über WSPCancelBlockingCall abgebrochen. | |
| Der Windows Sockets-Aufruf wird blockiert, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion. | |
| Der nicht blockierende WSPJoinLeaf-Aufruf wird für den angegebenen Socket ausgeführt. | |
| Die Remoteadresse ist keine gültige Adresse (z. B. ADDR_ANY). | |
| Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden. | |
| 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ß. | |
| Socket ist bereits Mitglied der Mehrpunktsitzung. | |
| 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 in lpSQOS angegebenen Flussspezifikationen können nicht erfüllt werden. | |
| Das lpCallerData-Augment wird vom Dienstanbieter nicht unterstützt. | |
| Der Versuch, eine Verbindung zu starten, ist ohne Einrichten einer Mehrpunktsitzung nicht mehr zeitlos. |
Hinweise
Diese Funktion wird verwendet, um einen Blattknoten mit einer Mehrpunktsitzung zu verknüpfen, und um eine Reihe anderer Hilfsvorgä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.
WSPJoinLeaf weist die gleichen Parameter und Semantik wie LPWSPConnect auf, mit der Ausnahme, dass es einen Socketdeskriptor (wie in LPWSPAccept) zurückgibt, und es verfügt über einen zusätzlichen dwFlags-Parameter . Für Eingabeparameter können in dieser Funktion nur Mehrpunktsocket-Sockets verwendet werden, die mit LPWSPSocket erstellt wurden und entsprechende Mehrpunktflags festgelegt sind. Wenn sich der Socket im Nichtblockierungsmodus befindet, kann der zurückgegebene Socketdeskriptor erst verwendet werden, nachdem ein entsprechender FD_CONNECT Hinweis auf den ursprünglichen Socket s empfangen wurde, mit der Ausnahme, dass für diesen neuen Socketdeskriptor ein Closesocket aufgerufen werden kann, um einen ausstehenden Verknüpfungsvorgang abzubrechen. Ein Stammknoten in einer Mehrpunktsitzung kann WSPJoinLeaf ein oder mehrere Male aufrufen, um eine Anzahl von Blattknoten hinzuzufügen. Höchstens eine Mehrpunktverbindungsanforderung kann jedoch gleichzeitig ausstehen. Weitere Informationen finden Sie unter Protokollunabhängiger Multicast und Multipoint im SPI .
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 den Hinweis "erfolgreicher Start" zurückgegeben hat. Wenn der Endgültige Erfolg oder Fehler bekannt wird, kann es über LPWSPAsyncSelect oder LPWSPEventSelect 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. Beachten Sie, dass LPWSPSelect nicht zum Erkennen von Vervollständigungsbenachrichtigungen für WSPJoinLeaf verwendet werden kann.
Der von WSPJoinLeaf 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. (Wie im Abschnitt Descriptorzuordnung beschrieben wird, müssen IFS-Anbieter WPUModifyIFSHandle und Nicht-IFS-Anbieter WPUCreateSocketHandle aufrufen, wenn neue Socketdeskriptoren zugewiesen werden. Der neu erstellte Socket verfügt über die gleichen Eigenschaften wie s , einschließlich asynchroner Ereignisse, die mit LPWSPAsyncSelect oder mit LPWSPEventSelect 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. Eine FD_CLOSE Angabe wird für diesen Socket empfangen, wenn der entsprechende Blattknoten LPWSPCloseSocket aufruft , um die Mehrpunktsitzung zu beenden. Symmetrisch bewirkt das Aufrufen von WSPCloseSocket auf dem von WSPJoinLeaf zurückgegebenen c_leaf Sockets, dass der Socket im entsprechenden Blattknoten FD_CLOSE Benachrichtigung erhält.
Wenn WSPJoinLeaf mit einem c_leaf Socket aufgerufen wird, enthält der Name-Parameter die Adresse des Stammknotens (für ein rootendes Steuerelementschema) oder eine vorhandene Mehrpunktsitzung (Nicht-Stammsteuerungsschema), und der zurückgegebene Socketdeskriptor ist mit dem Eingabesockendeskriptor 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 LPWSPListen aufgerufen wird. Die Standardbenachrichtigung FD_ACCEPT wird übermittelt, wenn der Blattknoten anfordert, sich mit der Mehrpunktsitzung zu verbinden. Die Stammanwendung verwendet die üblichen LPWSPAccept-Funktionen , um den neuen Blattknoten zuzulassen. Der von WSPAccept zurückgegebene Wert ist auch ein c_leaf Socketdeskriptor, genau wie die von WSPJoinLeaf zurückgegebenen. Um Mehrpunktschemas aufzunehmen, die sowohl stamminitiierte als auch blattinitiierte Joins zulassen, ist es akzeptabel, dass ein c_root Socket, der sich bereits im Lauschmodus befindet, als Eingabe für WSPJoinLeaf verwendet wird.
Der Windows Sockets SPI-Client ist für die Zuweisung von Speicherplatz verantwortlich, auf den durch einen der angegebenen Parameter direkt oder indirekt 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 Mehrpunktsitzungseinrichtung vom Peer zurückgegeben werden. lpCalleeData-len> enthält zunächst die Länge des Puffers, der vom Windows Sockets SPI-Client zugewiesen und vonlpCalleeData-buf> auf verweist. lpCalleeData-len> wird auf null festgelegt, wenn keine Benutzerdaten zurückgegeben wurden. Die lpCalleeData-Informationen sind gültig, wenn der Mehrpunktbeitrittsvorgang abgeschlossen ist. Wenn Sockets blockiert werden, gibt die WSPJoinLeaf-Funktion zurück. Bei Nichtblockierungssockets erfolgt dies, nachdem die FD_CONNECT Benachrichtigung für die ursprünglichen Sockets aufgetreten ist. Wenn lpCalleeDataNULL ist, werden keine Benutzerdaten zurückgegeben. Das genaue Format der Benutzerdaten ist spezifisch für die Adressfamilie, zu der der Socket gehört, und/oder die betreffenden Anwendungen.
Bei der Einrichtung mehrerer Punktsitzungen kann ein SPI-Client von Windows Sockets die lpSQOS-Parameter verwenden, um jede vorherige QoS-Spezifikation zu überschreiben, die für den Socket über LPWSPIoctl mit dem SIO_SET_QOS Opcode erstellt wurde.
lpSQOS gibt die Datenflussspezifikationen 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 QoS-Anforderung nicht einhalten kann, wird ein Fehler zurückgegeben, wie unten angegeben. Die sendenden oder empfangenden Datenflussspezifikationswerte werden für alle unidirektionalen Sockets ignoriert. Wenn keine anbieterspezifischen Parameter angegeben werden, sollten die buf- und len-Member von lpSQOS-ProviderSpecific> auf NULL bzw. null festgelegt werden. Ein NULL-Wert für lpSQOS gibt an, dass von der Anwendung keine Dienstqualität bereitgestellt wurde.
Der dwFlags-Parameter wird verwendet, um anzugeben, ob der Socket nur als Absender (JL_SENDER_ONLY), nur als Empfänger (JL_RECEIVER_ONLY) oder beides (JL_BOTH) fungiert.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ws2spi.h |