Fonction WSAConnect (winsock2.h)

Article
08/27/2023

La fonction WSAConnect établit une connexion à une autre application socket, échange des données de connexion et spécifie la qualité de service requise en fonction de la structure FLOWSPEC spécifiée.

Syntaxe

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

Paramètres

[in] s

Descripteur identifiant un socket non connecté.

[in] name

Pointeur vers une structure de sockaddr qui spécifie l’adresse à laquelle se connecter. Pour IPv4, le sockaddr contient AF_INET pour la famille d’adresses, l’adresse IPv4 de destination et le port de destination. Pour IPv6, la structure sockaddr contient des AF_INET6 pour la famille d’adresses, l’adresse IPv6 de destination, le port de destination et peut contenir des informations supplémentaires sur le flux et l’id d’étendue.

[in] namelen

Longueur, en octets, de la structure sockaddr pointée vers le paramètre name .

[in] lpCallerData

Pointeur vers les données utilisateur qui doivent être transférées vers l’autre socket lors de l’établissement de la connexion. Consultez la section Notes.

[out] lpCalleeData

Pointeur vers les données utilisateur qui doivent être transférées à partir de l’autre socket lors de l’établissement de la connexion. Consultez la section Notes.

[in] lpSQOS

Pointeur vers les structures FLOWSPEC pour les sockets, un 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). Ce paramètre doit avoir la valeur NULL.

Valeur retournée

Si aucune erreur ne se produit, WSAConnect retourne zéro. Sinon, il retourne SOCKET_ERROR, 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 la tentative de connexion.

Avec un socket non bloquant, la tentative de connexion ne peut pas être effectuée immédiatement. Dans ce cas, WSAConnect retourne SOCKET_ERROR, et WSAGetLastError retourne WSAEWOULDBLOCK ; l’application peut donc :

Utilisez select pour déterminer l’achèvement de la demande de connexion en vérifiant si le socket est accessible en écriture.
Si votre application utilise WSAAsyncSelect pour indiquer son intérêt pour les événements de connexion, votre application reçoit une notification FD_CONNECT lorsque l’opération de connexion est terminée (réussie ou non).
Si votre application utilise WSAEventSelect pour indiquer son intérêt pour les événements de connexion, l’objet d’événement associé est signalé lorsque l’opération de connexion est terminée (réussie ou non).

Pour un socket non bloquant, jusqu’à ce que la tentative de connexion se termine tous les appels suivants à WSAConnect sur le même socket échouent avec le code d’erreur WSAEALREADY.

Si le code d’erreur de retour indique que la tentative de connexion a échoué ( c’est-à-dire, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), l’application peut appeler WSAConnect à nouveau pour le même socket.

Code d'erreur	Signification
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
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 des adresses avec SO_REUSEADDR. Cette erreur se produit généralement pendant l’exécution de la liaison, mais elle peut être retardée jusqu’à ce que cette fonction fonctionne sur 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) Windows Socket 1.1 a été annulé via WSACancelBlockingCall.
WSAEINPROGRESS	Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEALREADY	Un appel de connexion ou WSAConnect non bloquant est en cours sur le socket spécifié.
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	La tentative de connexion a été rejetée.
WSAEFAULT	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.
WSAEINVAL	Le paramètre s est un socket d’écoute, ou l’adresse de destination spécifiée n’est pas cohérente avec celle du groupe contraint auquel appartient le socket, ou le paramètre lpGQOS n’est pas NULL.
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.
WSAEHOSTUNREACH	Une opération de socket a été tentée sur un hôte impossible à atteindre.
WSAENOBUFS	Aucune zone tampon disponible. Le socket ne peut pas être connecté.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSAEOPNOTSUPP	Les structures FLOWSPEC spécifiées dans lpSQOS et lpGQOS ne peuvent pas être satisfaites.
WSAEPROTONOSUPPORT	Le paramètre lpCallerData n’est pas pris en charge par le fournisseur de services.
WSAETIMEDOUT	La tentative de connexion a expiré sans établir de connexion.
WSAEWOULDBLOCK	Le socket est marqué comme non bloquant et la connexion ne peut pas être terminée immédiatement.
WSAEACCES	La tentative de connexion du socket datagram à l’adresse de diffusion a échoué, car setsockopt SO_BROADCAST n’est pas activé.

Remarques

La fonction WSAConnect permet de créer une connexion à la destination spécifiée et d’effectuer un certain nombre d’autres opérations auxiliaires qui se produisent au moment de la connexion. 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é.

Pour les applications ciblées sur Windows Vista et versions ultérieures, envisagez d’utiliser la fonction WSAConnectByList ou WSAConnectByName qui simplifie considérablement la conception des applications clientes.

Pour les sockets orientés connexion (par exemple, le type SOCK_STREAM), une connexion active est lancée à l’hôte étranger à l’aide du nom (une adresse dans l’espace de noms du socket ; pour obtenir une description détaillée, consultez liaison). Une fois cet appel terminé, le socket est prêt à envoyer/recevoir des données. Si le paramètre d’adresse de la structure de noms est tous zéros, WSAConnect retourne l’erreur WSAEADDRNOTAVAIL. Toute tentative de reconnexion d’une connexion active échoue avec le code d’erreur WSAEISCONN.

Note Si un socket est ouvert, un appel setsockopt est effectué, puis un appel sendto est effectué, Windows Sockets effectue un appel de fonction de liaison implicite.

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 l’erreur WSAEWOULDBLOCK. Toutefois, l’opération continue. Lorsque le résultat de la réussite ou de l’échec est connu, il peut être signalé de l’une des différentes manières selon la façon dont le client s’inscrit pour la notification. Si le client utilise select, la réussite est signalée dans le jeu writefds et l’échec est signalé dans le jeu exceptfds . Si le client utilise WSAAsyncSelect ou WSAEventSelect, 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.

Pour un socket sans connexion (par exemple, type SOCK_DGRAM), l’opération effectuée par WSAConnect consiste simplement à établir une adresse de destination par défaut afin que le socket puisse être utilisé lors des opérations d’envoi et de réception orientées connexion suivantes (send, WSASend, recv et WSARecv). Tous les datagrammes reçus d’une adresse autre que l’adresse de destination spécifiée seront ignorés. Si l’ensemble de la structure de noms est tous zéros (pas seulement le paramètre d’adresse de la structure de noms), le socket est déconnecté. Ensuite, l’adresse distante par défaut étant indéterminée, les appels send, WSASend, recv et WSARecv retournent le code d’erreur WSAENOTCONN. Toutefois, sendto, WSASendTo, recvfrom et WSARecvFrom peuvent toujours être utilisés. La destination par défaut peut être modifiée en appelant simplement WSAConnect à nouveau, 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 du WSAConnect précédent.

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 setockopt SO_BROADCAST activé. Sinon, WSAConnect é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.

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.

Le paramètre lpCallerData contient un pointeur vers toutes les données utilisateur qui doivent être envoyées avec la demande de connexion (appelées données de connexion). Il s’agit de données supplémentaires, pas dans le flux de données réseau normal, qui sont envoyées avec des demandes réseau pour établir une connexion. Cette option est utilisée par les protocoles hérités tels que DECNet, OSI TP4 et autres.

Note Les données de connexion ne sont pas prises en charge par le protocole TCP/IP dans Windows. La connexion de données est prise en charge uniquement sur ATM (RAWWAN) sur un socket brut.

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 à partir de l’autre socket dans le cadre de l’établissement de la connexion dans une structure WSABUF. 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 pour 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 sont valides une fois l’opération de connexion terminée. Pour le blocage des sockets, l’opération de connexion se termine lorsque la fonction WSAConnect est retournée. Pour les sockets non bloquants, l’achèvement se fera une fois que la notification FD_CONNECT s’est produite. 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 la connexion, une application peut utiliser les paramètres lpSQOS et lpGQOS pour remplacer toutes les spécifications de qualité de service précédentes établies pour le socket via WSAIoctl avec l’opcode 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 seront ignorées, respectivement, pour tous 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 le paramètre lpSQOS n’indique aucune qualité de service fournie par l’application.

Réservé à une utilisation future avec les groupes de sockets lpGQOS spécifie les structures FLOWSPEC pour le groupe de sockets (le cas échéant), une pour chaque direction, suivie 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ées 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 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.

Note Lors de l’émission d’un appel Winsock bloquant tel que WSAConnect, Winsock peut avoir besoin d’attendre un événement réseau avant que l’appel ne se termine. Winsock effectue une attente alertable dans cette situation, qui peut être interrompue par un appel de procédure asynchrone (APC) planifié sur le même thread. L’émission d’un autre appel Winsock bloquant à l’intérieur d’un APC qui a interrompu un appel Winsock bloquant en cours sur le même thread entraîne un comportement non défini et ne doit jamais être tenté par les clients Winsock.

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

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