Fonction WSAConnect (winsock2.h)
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).
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 |
|---|---|
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. | |
| Le sous-système réseau a échoué. | |
| 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. | |
| L’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. | |
| Un appel de connexion ou WSAConnect non bloquant est en cours sur le socket spécifié. | |
| 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. | |
| La tentative de connexion a été rejetée. | |
| 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. | |
| 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. | |
| Le socket est déjà connecté (sockets orientés connexion uniquement). | |
| Le réseau ne peut pas être atteint à partir de cet hôte en ce moment. | |
| Une opération de socket a été tentée sur un hôte impossible à atteindre. | |
| Aucune zone tampon disponible. Le socket ne peut pas être connecté. | |
| Le descripteur n’est pas un socket. | |
| Les structures FLOWSPEC spécifiées dans lpSQOS et lpGQOS ne peuvent pas être satisfaites. | |
| Le paramètre lpCallerData n’est pas pris en charge par le fournisseur de services. | |
| La tentative de connexion a expiré sans établir de connexion. | |
| Le socket est marqué comme non bloquant et la connexion ne peut pas être terminée immédiatement. | |
| 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.
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.
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.
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 |