Fonction de rappel LPWSPJOINLEAF (ws2spi.h)

La fonction WSPJoinLeaf 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 spécifications de flux fournies.

Syntaxe

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
)
{...}

Paramètres

[in] s

Descripteur identifiant un socket multipoint.

[in] name

Nom de l’homologue auquel le socket de la structure sockaddr 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 spécifications de flux pour les sockets, une pour chaque direction.

[in] lpGQOS

Réservé.

[in] dwFlags

Indicateurs pour indiquer que le socket agit en tant qu’expéditeur, récepteur ou les deux.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, WSPJoinLeaf 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 est disponible dans lpErrno.

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 une valeur de retour d’un descripteur de socket valide. Par la suite, une indication FD_CONNECT est donnée lorsque l’opération de jointure se termine, avec succès ou autrement. Le code d’erreur associé au FD_CONNECT indique la réussite ou l’échec de WSPJoinLeaf.

En outre, jusqu’à ce que la tentative de jointure de session multipoint se termine tous les appels suivants à WSPJoinLeaf sur le même socket échouent avec le code d’erreur WSAEALREADY. Une fois le WSPJoinLeaf terminé avec succès, 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’un WSPJoinLeaf antérieur.

Si le code d’erreur de retour indique que la tentative de jointure de session multipoint a échoué ( c’est-à-dire, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), le client SPI windows Sockets peut à nouveau appeler WSPJoinLeaf pour le même socket.

Remarques

Cette fonction 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 affectées à l’association locale par le système et le socket est marqué comme lié.

WSPJoinLeaf a les mêmes paramètres et sémantiques que LPWSPConnect , sauf qu’il retourne un descripteur de socket (comme dans LPWSPAccept) et qu’il a un paramètre dwFlags supplémentaire. Seuls les sockets multipoints créés à l’aide de LPWSPSocket avec des indicateurs multipoints appropriés peuvent être utilisés pour les paramètres d’entrée dans cette fonction. Si le socket est en mode non bloquant, le descripteur de socket retourné ne sera utilisable qu’après la réception d’une indication de FD_CONNECT correspondante sur le socket d’origine, sauf que closesocket peut être appelé sur ce nouveau descripteur de socket pour annuler une opération de jointure en attente. Un nœud racine dans une session multipoint peut appeler WSPJoinLeaf 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, consultez Multidiffusion indépendante du protocole et Multipoint dans spi .

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 « démarrage réussi ». Lorsque le résultat final de la réussite ou de l’échec est connu, il peut être signalé via LPWSPAsyncSelect ou LPWSPEventSelect , en fonction de 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. Notez que LPWSPSelect ne peut pas être utilisé pour détecter la notification d’achèvement pour WSPJoinLeaf.

Le descripteur de socket retourné par WSPJoinLeaf 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é. (Comme décrit dans la section Allocation de descripteurs, lorsque de nouveaux descripteurs de socket sont alloués, les fournisseurs IFS doivent appeler WPUModifyIFSHandle et les fournisseurs non-IFS doivent appeler WPUCreateSocketHandle). Le socket nouvellement créé a les mêmes propriétés que s , y compris les événements asynchrones inscrits auprès de LPWSPAsyncSelect ou auprès de LPWSPEventSelect. 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 LPWSPCloseSocket pour qu’il quitte la session multipoint. Symétriquement, l’appel de WSPCloseSocket sur le socket c_leaf retourné par WSPJoinLeaf entraîne l’obtention du socket dans le nœud feuille correspondant pour obtenir FD_CLOSE notification.

Lorsque WSPJoinLeaf est appelé avec un socket c_leaf, le paramètre name contient l’adresse du nœud 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 LPWSPListen. 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 LPWSPAccept habituelles pour admettre le nouveau nœud feuille. La valeur retournée par WSPAccept est également un descripteur de socket c_leaf comme ceux retournés par WSPJoinLeaf. Pour prendre en charge les schémas multipoints qui autorisent les jointures initiées par la racine et les jointures à l’initiative feuille, il est acceptable qu’un socket c_root qui est déjà en mode d’écoute soit utilisé comme entrée dans WSPJoinLeaf.

Le client SPI windows Sockets est responsable de l’allocation de tout espace mémoire pointé directement ou indirectement par l’un des paramètres qu’il 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. lpCalleeData-len> contient initialement la longueur de la mémoire tampon allouée par le client SPI Windows Sockets et pointée vers lpCalleeData-buf.> lpCalleeData-len> 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, la fonction WSPJoinLeaf est retournée. Pour les sockets non bloquants, cette opération se produit après que la notification FD_CONNECT s’est produite sur les sockets d’origine. Si lpCalleeData a la valeur NULL, aucune donnée utilisateur ne sera renvoyée. Le format exact des données utilisateur est spécifique à la famille d’adresses à laquelle appartient le socket et/ou aux applications impliquées.

Au moment de l’établissement de la session multipoint, un client SPI Windows Sockets peut utiliser les paramètres lpSQOS pour remplacer toute spécification QoS précédente effectuée pour le socket via LPWSPIoctl avec l’opcode SIO_SET_QOS.

lpSQOS spécifie les spécifications de flux pour les sockets, une pour chaque direction, suivie de tous les paramètres supplémentaires spécifiques au fournisseur. Si le fournisseur de transport associé en général ou le type spécifique de socket en particulier ne peut pas honorer la demande QoS, une erreur est retournée comme indiqué ci-dessous. Les valeurs de spécification de flux d’envoi ou de réception seront ignorées, respectivement, pour tous les sockets unidirectionnels. Si aucun paramètre spécifique au fournisseur n’est fourni, les membres buf et len de lpSQOS-ProviderSpecific> doivent être définis sur NULL et zéro, respectivement. Une valeur NULL pour lpSQOS indique qu’aucune application ne fournit de qualité de service.

Le paramètre dwFlags est utilisé pour indiquer si le socket agit uniquement en tant qu’expéditeur (JL_SENDER_ONLY), uniquement en tant que récepteur (JL_RECEIVER_ONLY) ou les deux (JL_BOTH).

Spécifications

Voir aussi

LPWSPAccept

LPWSPAsyncSelect

LPWSPBind

LPWSPEventSelect

LPWSPSelect

LPWSPSocket