Fonction de rappel LPWSPCONNECT (ws2spi.h)

Article
08/28/2023

La fonction LPWSPConnect établit une connexion à un homologue, échange des données de connexion et spécifie la qualité de service nécessaire en fonction de la spécification de flux fournie.

Syntaxe

LPWSPCONNECT Lpwspconnect;

int Lpwspconnect(
  [in]  SOCKET s,
  [in]  const sockaddr *name,
  [in]  int namelen,
  [in]  LPWSABUF lpCallerData,
  [out] LPWSABUF lpCalleeData,
  [in]  LPQOS lpSQOS,
  [in]  LPQOS lpGQOS,
  [out] LPINT lpErrno
)
{...}

Paramètres

[in] s

Descripteur identifiant un socket non connecté.

[in] name

Nom de l’homologue auquel le socket dans le sockaddr doit être connecté.

[in] namelen

Longueur du nom, en octets.

[in] lpCallerData

Pointeur vers les données utilisateur qui doivent être transférées à l’homologue lors de l’établissement de la connexion.

[out] lpCalleeData

Pointeur vers une mémoire tampon dans laquelle toutes les données utilisateur reçues de l’homologue pendant l’établissement de la connexion peuvent être copiées.

[in] lpSQOS

Pointeur vers les spécifications de flux pour les sockets, une pour chaque direction.

[in] lpGQOS

Réservé.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, LPWSPConnect retourne zéro. Sinon, elle retourne SOCKET_ERROR 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 la tentative de connexion. Si le code d’erreur de retour indique que la tentative de connexion a échoué ( c’est-à-dire WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), le client Winsock SPI peut appeler À nouveau LPWSPConnect pour le même socket.

Code d'erreur	Signification
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEADDRINUSE	L’adresse locale du socket est déjà utilisée et le socket n’a pas été marqué pour permettre la réutilisation de l’adresse 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.
WSAEINTR	L’appel (bloquant) a été annulé via LPWSPCancelBlockingCall.
WSAEINPROGRESS	Le blocage de l’appel Winsock est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEALREADY	L’appel LPWSPConnect non bloquant est en cours sur le socket spécifié. Afin de préserver la compatibilité descendante, cette erreur est signalée en tant que WSAEINVAL aux applications Windows Sockets 1.1 qui sont liées à Winsock.dll ou Wsock32.dll.
WSAEADDRNOTAVAIL	L’adresse distante n’est pas une adresse valide (par exemple, ADDR_ANY).
WSAEAFNOSUPPORT	Impossible d'utiliser les adresses figurant dans la famille spécifiée avec ce socket.
WSAECONNREFUSED	Une tentative de connexion a été rejetée.
WSAEFAULT	Le paramètre name ou namelen ne fait pas partie de l’espace d’adressage utilisateur, le paramètre namelen est trop petit, la longueur de la mémoire tampon pour lpCalleeData, lpSQOS et lpGQOS est trop petite ou la longueur de la mémoire tampon pour lpCallerData est trop grande.
WSAEINVAL	Le paramètre s est un socket d’écoute.
WSAEISCONN	Le socket est déjà connecté (sockets orientés connexion uniquement).
WSAENETUNREACH	Le réseau ne peut pas être atteint à partir de cet hôte en ce moment.
WSAENOBUFS	Aucune zone tampon disponible. Impossible de connecter le socket.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSAEOPNOTSUPP	Les spécifications de flux spécifiées dans lpSQOS ne peuvent pas être satisfaites.
WSAEPROTONOSUPPORT	L’augmentation de lpCallerData n’est pas prise en charge par le fournisseur de services.
WSAETIMEDOUT	Une tentative de connexion a expiré sans établir de connexion.
WSAEWOULDBLOCK	Le socket est marqué comme non bloquant et la connexion ne peut pas être établie immédiatement. Il est possible de sélectionner le socket à l’aide de la fonction LPWSPSelect pendant la connexion en utilisant la fonction WSPSelect pour le sélectionner pour l’écriture.
WSAEACCES	Une tentative de connexion du socket datagramme à l’adresse de diffusion a échoué, car WSPSetSockOpt SO_BROADCAST n’est pas activé.

Remarques

Cette fonction est utilisée pour créer une connexion à la destination spécifiée et pour effectuer un certain nombre d’autres opérations auxiliaires qui se produisent également au moment de la connexion. Si le socket , s, est indépendant, des valeurs uniques sont affectées à l’association locale par le système et le socket est marqué comme lié.

Pour les sockets orientés connexion (par exemple, type SOCK_STREAM), une connexion active est lancée à l’hôte spécifié à l’aide du nom (une adresse dans l’espace de noms du socket). Pour obtenir une description détaillée, consultez LPWSPBind. Lorsque cet appel se termine correctement, le socket est prêt à envoyer et à recevoir des données. Si le membre d’adresse de la structure de noms est tous des zéros, LPWSPConnect renvoie l’erreur WSAEADDRNOTAVAIL. Toute tentative de reconnexion d’une connexion active échoue avec le code d’erreur WSAEISCONN.

Pour les sockets orientés connexion et non bloquants, il n’est souvent pas possible de terminer la connexion immédiatement. Dans ce cas, cette fonction retourne avec l’erreur WSAEWOULDBLOCK , mais l’opération se poursuit. Lorsque le résultat de la réussite ou de l’échec est connu, il peut être signalé de plusieurs façons selon la façon dont le client s’inscrit pour la notification. Si le client utilise LPWSPSelect, la réussite est signalée dans le jeu writefds et l’échec est signalé dans le jeu exceptfds . Si le client utilise LPWSPAsyncSelect ou LPWSPEventSelect, la notification est annoncée avec FD_CONNECT et le code d’erreur associé à l’FD_CONNECT indique la réussite ou une raison spécifique de l’échec.

Pour un socket sans connexion (par exemple, type SOCK_DGRAM), l’opération effectuée par LPWSPConnect consiste à établir une adresse de destination par défaut afin que le socket puisse être utilisé avec les opérations d’envoi et de réception suivantes orientées connexion (LPWSPSend, LPWSPRecv). Tous les datagrammes reçus d’une adresse autre que l’adresse de destination spécifiée seront ignorés. Si le membre d’adresse de la structure de noms est tous zéros, le socket est déconnecté. L’adresse distante par défaut étant indéterminée, les appels LPWSPSend et LPWSPRecv retournent le code d’erreur WSAENOTCONN. Toutefois, LPWSPSendTo et LPWSPRecvFrom peuvent toujours être utilisés. La destination par défaut peut être modifiée en appelant simplement LPWSPConnect , même si le socket est déjà connecté. Tous les datagrammes mis en file d’attente pour réception sont ignorés si le nom est différent de l’ancien LPWSPConnect.

Pour les sockets sans connexion, le nom peut indiquer n’importe quelle adresse valide, y compris une adresse de diffusion. Toutefois, pour se connecter à une adresse de diffusion, un socket doit avoir WSPSetSockOpt SO_BROADCAST activé. Sinon, LPWSPConnect échoue avec le code d’erreur WSAEACCES.

Sur les sockets sans connexion, l’échange de données utilisateur à utilisateur n’est pas possible et les paramètres correspondants sont ignorés en mode silencieux.

Le client Winsock SPI est chargé d’allouer tout espace mémoire pointé directement ou indirectement par l’un des paramètres qu’il spécifie.

LpCallerData est un paramètre de valeur qui contient toutes les données utilisateur à envoyer avec la demande de connexion. Si lpCallerData a la valeur Null, aucune donnée utilisateur ne sera passée à l’homologue. LpCalleeData est un paramètre de résultat qui référence toutes les données utilisateur passées de l’homologue dans le cadre de l’établissement de la connexion. LpCalleeData-len> contient initialement la longueur de la mémoire tampon allouée par le client SPI Winsock et pointée parlpCalleeData-buf.> LpCalleeData-len> est défini sur zéro si aucune donnée utilisateur n’a été renvoyée. Les informations lpCalleeData sont valides une fois l’opération de connexion terminée. Pour les sockets bloquants, la fonction LPWSPConnect est retournée. Pour les sockets non bloquants, cette opération se produit après l’FD_CONNECT notification. 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 la connexion, un client Winsock SPI peut utiliser le paramètre lpSQOS pour remplacer toute spécification QoS précédente 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 n’a fourni de qualité de service.

Notes

Lorsque les sockets connectés tombent en panne (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é, le client Winsock SPI doit ignorer et recréer les sockets nécessaires afin de revenir à un point stable.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	ws2spi.h