Fonction WSAJoinLeaf (winsock2.h)
La fonction WSAJoinLeaf joint un nœud feuille à une session multipoint, échange des données de connexion et spécifie la qualité de service nécessaire en fonction des structures FLOWSPEC spécifiées.
Syntaxe
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
);
Paramètres
[in] s
Descripteur identifiant un socket multipoint.
[in] name
Nom de l’homologue auquel le socket doit être joint.
[in] namelen
Longueur du nom, en octets.
[in] lpCallerData
Pointeur vers les données utilisateur qui doivent être transférées vers l’homologue pendant l’établissement d’une session multipoint.
[out] lpCalleeData
Pointeur vers les données utilisateur qui doivent être transférées à partir de l’homologue pendant l’établissement de la session multipoint.
[in] lpSQOS
Pointeur vers les structures FLOWSPEC pour les sockets, une pour chaque direction.
[in] lpGQOS
Réservé à une utilisation future avec des groupes de sockets. Pointeur vers les structures FLOWSPEC pour le groupe de sockets (le cas échéant).
[in] dwFlags
Indicateurs pour indiquer que le socket agit en tant qu’expéditeur (JL_SENDER_ONLY), récepteur (JL_RECEIVER_ONLY) ou les deux (JL_BOTH).
Valeur retournée
Si aucune erreur ne se produit, WSAJoinLeaf retourne une valeur de type SOCKET qui est un descripteur pour le socket multipoint nouvellement créé. Sinon, une valeur de INVALID_SOCKET est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.
Sur un socket bloquant, la valeur de retour indique la réussite ou l’échec de l’opération de jointure.
Avec un socket non bloquant, le lancement réussi d’une opération de jointure est indiqué par un retour d’un descripteur de socket valide. Par la suite, une indication FD_CONNECT sera donnée sur les sockets d’origine une fois l’opération de jointure terminée, avec succès ou autrement. L’application doit utiliser WSAAsyncSelect ou WSAEventSelect avec l’intérêt inscrit pour l’événement FD_CONNECT afin de déterminer quand l’opération de jointure est terminée et de vérifier le code d’erreur associé pour déterminer la réussite ou l’échec de l’opération. La fonction select ne peut pas être utilisée pour déterminer quand l’opération de jointure se termine.
En outre, jusqu’à ce que la tentative de jointure de session multipoint se termine tous les appels suivants à WSAJoinLeaf sur le même socket échouent avec le code d’erreur WSAEALREADY. Une fois l’opération WSAJoinLeaf terminée, une tentative suivante échoue généralement avec le code d’erreur WSAEISCONN. Une exception à la règle WSAEISCONN se produit pour un socket c_root qui autorise les jointures initiées par la racine. Dans ce cas, une autre jointure peut être lancée après la fin d’une opération WSAJoinLeaf précédente.
Si le code d’erreur de retour indique que la tentative de jonction de session multipoint a échoué ( c’est-à-dire, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), l’application peut appeler WSAJoinLeaf à nouveau pour le même socket.
| Code d'erreur | Signification |
|---|---|
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. | |
| L’adresse locale du socket est déjà utilisée et le socket n’a pas été marqué pour permettre la réutilisation des adresses avec SO_REUSEADDR. Cette erreur se produit généralement au moment de la liaison, mais peut être retardée jusqu’à cette fonction si la liaison était vers une adresse générique partielle (impliquant ADDR_ANY) et si une adresse spécifique doit être validée au moment de cette fonction. | |
| L’adresse distante n’est pas une adresse valide (par exemple, ADDR_ANY). | |
| Impossible d'utiliser les adresses figurant dans la famille spécifiée avec ce socket. | |
| Un appel WSAJoinLeaf non bloquant est en cours sur le socket spécifié. | |
| La tentative d’adhésion a été rejetée de force. | |
| Le nom ou le paramètre namelen ne fait pas partie valide de l’espace d’adressage utilisateur, le paramètre namelen est trop petit, la longueur de mémoire tampon pour lpCalleeData, lpSQOS et lpGQOS est trop petite ou la longueur de mémoire tampon pour lpCallerData est trop grande. | |
| Un appel de fonction WSAJoinLeaf a été effectué sur un socket UDP ouvert sans définir son WSA_FLAG_MULTIPOINT_C_LEAF ou WSA_FLAG_MULTIPOINT_D_LEAF indicateur multipoint. | |
| Le socket est déjà membre de la session multipoint. | |
| Un appel bloquant Windows Socket 1.1 a été annulé via WSACancelBlockingCall. | |
| Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Le sous-système réseau a échoué. | |
| Le réseau ne peut pas être atteint à partir de cet hôte en ce moment. | |
| Aucune zone tampon disponible. Impossible de joindre le socket. | |
| Le descripteur n’est pas un socket. | |
| Les structures FLOWSPEC spécifiées dans lpSQOS et lpGQOS ne peuvent pas être satisfaites. | |
| L’augmentation lpCallerData n’est pas prise en charge par le fournisseur de services. | |
| La tentative de jointure a expiré sans établir de session multipoint. |
Remarques
La fonction WSAJoinLeaf est utilisée pour joindre un nœud feuille à une session multipoint et pour effectuer un certain nombre d’autres opérations auxiliaires qui se produisent également au moment de la jonction de session. Si le socket s n’est pas lié, les valeurs uniques sont attribuées à l’association locale par le système et le socket est marqué comme lié.
La fonction WSAJoinLeaf a les mêmes paramètres et sémantiques que WSAConnect , sauf qu’elle retourne un descripteur de socket (comme dans WSAAccept) et qu’elle a un paramètre dwFlags supplémentaire. Seuls les sockets multipoints créés à l’aide de WSASocket avec des indicateurs multipoints appropriés peuvent être utilisés pour les paramètres d’entrée dans cette fonction. Le descripteur de socket retourné ne sera utilisable qu’une fois l’opération de jointure terminée. Par exemple, si le socket est en mode non bloquant après qu’une indication de FD_CONNECT correspondante a été reçue de WSAAsyncSelect ou de WSAEventSelect sur les sockets d’origine, sauf que closesocket peut être appelé sur ce nouveau descripteur de socket pour annuler une opération de jointure en attente. Une application racine dans une session multipoint peut appeler WSAJoinLeaf une ou plusieurs fois afin d’ajouter un certain nombre de nœuds feuilles, mais au maximum une demande de connexion multipoint peut être en attente à la fois. Pour plus d’informations, reportez-vous à Multipoint et Multicast Semantics .
Pour les sockets non bloquants, il est souvent impossible d’effectuer la connexion immédiatement. Dans ce cas, cette fonction retourne un descripteur de socket encore inutilisable et l’opération se poursuit. Il n’existe aucun code d’erreur tel que WSAEWOULDBLOCK dans ce cas, car la fonction a effectivement retourné une indication de démarrage réussie. Lorsque le résultat final est connu, il peut être signalé via WSAAsyncSelect ou WSAEventSelect , selon la façon dont le client s’inscrit pour la notification sur les sockets d’origine. Dans les deux cas, la notification est annoncée avec FD_CONNECT et le code d’erreur associé au FD_CONNECT indique la réussite ou une raison spécifique de l’échec. La fonction select ne peut pas être utilisée pour détecter la notification d’achèvement pour WSAJoinLeaf.
Le descripteur de socket retourné par WSAJoinLeaf est différent selon que le descripteur de socket d’entrée, s, est un c_root ou un c_leaf. Lorsqu’il est utilisé avec un socket c_root, le paramètre name désigne un nœud feuille particulier à ajouter et le descripteur de socket retourné est un socket c_leaf correspondant au nœud feuille nouvellement ajouté. Le socket nouvellement créé a les mêmes propriétés que s, y compris les événements asynchrones inscrits auprès de WSAAsyncSelect ou de WSAEventSelect. Il n’est pas destiné à être utilisé pour l’échange de données multipoints, mais plutôt pour recevoir des indications d’événement réseau (par exemple, FD_CLOSE) pour la connexion qui existe à l’c_leaf spécifique. Certaines implémentations multipoints peuvent également permettre d’utiliser ce socket pour les conversations latérales entre la racine et un nœud feuille individuel. Une indication FD_CLOSE est reçue pour ce socket si le nœud feuille correspondant appelle closesocket pour supprimer la session multipoint. Symétriquement, l’appel de closesocket sur le socket c_leaf retourné par WSAJoinLeaf entraîne l’obtention d’une notification FD_CLOSE dans le socket dans le nœud feuille correspondant.
Lorsque WSAJoinLeaf est appelé avec un socket c_leaf, le paramètre name contient l’adresse de l’application racine (pour un schéma de contrôle rooté) ou une session multipoint existante (schéma de contrôle non rooté), et le descripteur de socket retourné est identique au descripteur de socket d’entrée. En d’autres termes, un nouveau descripteur de socket n’est pas alloué. Dans un schéma de contrôle rooté, l’application racine place son socket c_root en mode d’écoute en appelant listen. La notification FD_ACCEPT standard est remise lorsque le nœud feuille demande à se joindre lui-même à la session multipoint. L’application racine utilise les fonctions accept ou WSAAccept habituelles pour admettre le nouveau nœud feuille. La valeur retournée par accept ou WSAAccept est également un descripteur de socket c_leaf comme ceux retournés par WSAJoinLeaf. Pour prendre en charge les schémas multipoints qui autorisent les jointures initiées par la racine et les jointures lancées par feuille, il est acceptable qu’un socket c_root qui est déjà en mode d’écoute soit utilisé comme entrée dans WSAJoinLeaf.
L’application est responsable de l’allocation de tout espace mémoire pointé directement ou indirectement par l’un des paramètres qu’elle spécifie.
LpCallerData est un paramètre value qui contient toutes les données utilisateur qui doivent être envoyées avec la demande de jointure de session multipoint. Si lpCallerData a la valeur NULL, aucune donnée utilisateur n’est transmise à l’homologue. L’objet lpCalleeData est un paramètre de résultat qui contiendra toutes les données utilisateur transmises par l’homologue dans le cadre de l’établissement de la session multipoint. Le membre len de la structure WSABUF pointée vers le paramètre lpCalleeData contient initialement la longueur de la mémoire tampon allouée par l’application et pointée par le membre buf de la structure WSABUF . Le membre len de la structure WSABUF pointée vers le paramètre lpCalleeData est défini sur zéro si aucune donnée utilisateur n’a été renvoyée. Les informations lpCalleeData seront valides une fois l’opération de jointure multipoint terminée.
Pour les sockets bloquants, c’est lorsque la fonction WSAJoinLeaf est retournée. Pour les sockets non bloquants, cela se fera une fois l’opération de jointure terminée. Par exemple, cela peut se produire après FD_CONNECT notification sur le socket d’origine s). Si lpCalleeData a la valeur NULL, aucune donnée utilisateur n’est renvoyée. Le format exact des données utilisateur est spécifique à la famille d’adresses à laquelle appartient le socket.
Au moment de l’établissement de la session multipoint, une application peut utiliser les paramètres lpSQOS et/ou lpGQOS pour remplacer toute spécification de qualité de service précédente pour le socket via WSAIoctl avec les opcodes SIO_SET_QOS ou SIO_SET_GROUP_QOS.
Le paramètre lpSQOS spécifie les structures FLOWSPEC pour les sockets, une pour chaque direction, suivies de tous les paramètres supplémentaires spécifiques au fournisseur. Si le fournisseur de transport associé en général ou le type de socket spécifique en particulier ne peut pas honorer la demande de qualité de service, une erreur est retournée comme indiqué dans ce qui suit. Les valeurs de spécification de flux d’envoi ou de réception respectives seront ignorées pour les sockets unidirectionnels. Si aucun paramètre spécifique au fournisseur n’est spécifié, les membres buf et len de la structure WSABUF pointées par le paramètre lpCalleeData doivent être définis sur NULL et zéro, respectivement. Une valeur NULL pour lpSQOS n’indique aucune qualité de service fournie par l’application.
Réservé aux futurs groupes de sockets. Le paramètre lpGQOS spécifie les structures FLOWSPEC pour le groupe de sockets (le cas échéant), une pour chaque direction, suivies de tous les paramètres supplémentaires spécifiques au fournisseur. Si aucun paramètre spécifique au fournisseur n’est spécifié, les membres buf et len de la structure WSABUF pointée par le paramètre lpCalleeData doivent être définis sur NULL et zéro, respectivement. Une valeur NULL pour lpGQOS n’indique aucune qualité de service de groupe fournie par l’application. Ce paramètre sera ignoré si s n’est pas le créateur du groupe de sockets.
Lorsque les sockets connectés s’arrêtent (c’est-à-dire qu’ils sont fermés pour une raison quelconque), ils doivent être ignorés et recréés. Il est plus sûr de supposer que lorsque les choses vont mal pour une raison quelconque sur un socket connecté, l’application doit ignorer et recréer les sockets nécessaires pour revenir à un point stable.
Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | winsock2.h |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |