Fonction de rappel LPWSPCONNECT (ws2spi.h)
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 |
|---|---|
| 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 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. | |
| L’appel (bloquant) a été annulé via LPWSPCancelBlockingCall. | |
| Le blocage de l’appel Winsock est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
|
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. |
|
| 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. | |
| Une tentative de connexion a été rejetée. | |
| 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. | |
| Le paramètre s est un socket d’écoute. | |
| 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. | |
| Aucune zone tampon disponible. Impossible de connecter le socket. | |
| Le descripteur n’est pas un socket. | |
| Les spécifications de flux spécifiées dans lpSQOS ne peuvent pas être satisfaites. | |
| L’augmentation de lpCallerData n’est pas prise en charge par le fournisseur de services. | |
| Une tentative de connexion a expiré sans établir de connexion. | |
| 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. | |
| 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 |