fonction bind (winsock2.h)
La fonction de liaison associe une adresse locale à un socket.
Syntaxe
int WSAAPI bind(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen
);
Paramètres
[in] s
Descripteur identifiant un socket non lié.
[in] name
Pointeur vers une structure de sockaddr de l’adresse locale à affecter au socket lié .
[in] namelen
Longueur, en octets, de la valeur pointée par le paramètre name .
Valeur retournée
Si aucune erreur ne se produit, la liaison retourne zéro. Sinon, il retourne SOCKET_ERROR, et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.
| Code d'erreur | Signification |
|---|---|
|
Note Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
|
|
| Le sous-système réseau a échoué. | |
|
Une tentative d’accès à un socket a été effectuée de manière interdite par ses autorisations d’accès.
Cette erreur est retournée si nn tente de lier un socket de datagramme à l’adresse de diffusion, car l’option setsockopt SO_BROADCAST n’est pas activée. |
|
|
Une seule utilisation de chaque adresse de socket (protocole/adresse réseau/port) est habituellement autorisée.
Cette erreur est retournée si un processus sur l’ordinateur est déjà lié à la même adresse complète et que le socket n’a pas été marqué pour autoriser la réutilisation des adresses avec SO_REUSEADDR. Par exemple, l’adresse IP et le port spécifiés dans le paramètre name sont déjà liés à un autre socket utilisé par une autre application. Pour plus d’informations, consultez l’option de socket SO_REUSEADDR dans les informations de référence options de socket SOL_SOCKET , Utilisation de SO_REUSEADDR et de SO_EXCLUSIVEADDRUSE, et SO_EXCLUSIVEADDRUSE. |
|
|
L’adresse demandée n’est pas valide dans son contexte.
Cette erreur est retournée si l’adresse spécifiée pointée par le paramètre name n’est pas une adresse IP locale valide sur cet ordinateur. |
|
|
Le système a détecté une adresse de pointeur non valide lors de la tentative d’utilisation d’un argument pointeur dans un appel.
Cette erreur est retournée si le paramètre name a la valeur NULL, si le paramètre name ou namelen ne fait pas partie de l’espace d’adressage de l’utilisateur, si le paramètre namelen est trop petit, si le paramètre name contient un format d’adresse incorrect pour la famille d’adresses associée, ou si les deux premiers octets du bloc de mémoire spécifié par nom ne correspondent pas à la famille d’adresses associée au descripteur de socket s. |
|
| Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
|
Argument non valide fourni.
Cette erreur est retournée du fait que le socket s est déjà lié à une adresse. |
|
|
Impossible d’effectuer une opération sur un socket, car le système n’avait pas suffisamment d’espace de mémoire tampon ou car une file d’attente était pleine.
Cette erreur est retournée en cas de mémoires tampons insuffisantes disponibles ou de connexions trop nombreuses. |
|
|
Une opération a été tentée sur un objet qui n’est pas un socket.
Cette erreur est retournée si le descripteur dans le paramètre s n’est pas un socket. |
Remarques
La fonction bind est requise sur un socket non connecté avant les appels suivants à la fonction d’écoute . Il est normalement utilisé pour se lier à des sockets orientés connexion (flux) ou sans connexion (datagramme). La fonction bind peut également être utilisée pour lier à un socket brut (le socket a été créé en appelant la fonction socket avec le paramètre de type défini sur SOCK_RAW). La fonction bind peut également être utilisée sur un socket non connecté avant les appels suivants aux fonctions connect, ConnectEx, WSAConnect, WSAConnectByList ou WSAConnectByName avant les opérations d’envoi.
Lorsqu’un socket est créé avec un appel à la fonction socket , il existe dans un espace de noms (famille d’adresses), mais aucun nom ne lui est attribué. Utilisez la fonction bind pour établir l’association locale du socket en affectant un nom local à un socket sans nom.
Un nom se compose de trois parties lors de l’utilisation de la famille d’adresses Internet :
- Famille d’adresses.
- Adresse de l’hôte.
- Numéro de port qui identifie l’application.
Dans Windows Sockets 2, le paramètre name n’est pas strictement interprété comme un pointeur vers une structure sockaddr . Il est casté de cette façon pour la compatibilité des sockets Windows 1.1. Les fournisseurs de services sont libres de le considérer comme un pointeur vers un bloc de mémoire de taille namelen. Les 2 premiers octets de ce bloc (correspondant au membre sa_family de la structure sockaddr , au membre sin_family de la structure sockaddr_in ou au membre sin6_family de la structure sockaddr_in6 ) doivent contenir la famille d’adresses utilisée pour créer le socket. Sinon, une erreur WSAEFAULT se produit.
Si une application ne se soucie pas de l’adresse locale affectée, spécifiez la valeur constante INADDR_ANY pour une adresse locale IPv4 ou la valeur constante in6addr_any pour une adresse locale IPv6 dans le membre sa_data du paramètre name . Cela permet au fournisseur de services sous-jacent d’utiliser n’importe quelle adresse réseau appropriée, ce qui simplifie potentiellement la programmation de l’application en présence d’hôtes multi-hébergements (c’est-à-dire des hôtes qui ont plusieurs adresses et interface réseau).
Pour TCP/IP, si le port est spécifié sur zéro, le fournisseur de services affecte un port unique à l’application à partir de la plage de ports client dynamique. Sur Windows Vista et versions ultérieures, la plage de ports clients dynamiques est une valeur comprise entre 49152 et 65535. Il s’agit d’un changement par rapport à Windows Server 2003 et versions antérieures, où la plage de ports client dynamiques était une valeur comprise entre 1025 et 5 000. La valeur maximale de la plage de ports dynamiques client peut être modifiée en définissant une valeur sous la clé de Registre suivante :
HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
La valeur de Registre MaxUserPort définit la valeur à utiliser pour la valeur maximale de la plage de ports client dynamique. Vous devez redémarrer l’ordinateur pour que ce paramètre prenne effet.
Sur Windows Vista et versions ultérieures, la plage de ports clients dynamiques peut être consultée et modifiée à l’aide des commandes netsh . La plage de ports clients dynamiques peut être définie différemment pour UDP et TCP, ainsi que pour IPv4 et IPv6. Pour plus d’informations, consultez Kb 929851.
L’application peut utiliser getsockname après l’appel de bind pour connaître l’adresse et le port qui a été affecté au socket. Si l’adresse Internet est égale à INADDR_ANY ou in6addr_any, getsockname ne peut pas nécessairement fournir l’adresse tant que le socket n’est pas connecté, car plusieurs adresses peuvent être valides si l’hôte est multi-hébergement. La liaison à un numéro de port spécifique autre que le port 0 est déconseillée pour les applications clientes, car il existe un risque de conflit avec un autre socket qui utilise déjà ce numéro de port sur l’ordinateur local.
Pour les opérations de multidiffusion, la méthode recommandée consiste à appeler la fonction de liaison pour associer un socket à une adresse IP locale, puis à rejoindre le groupe de multidiffusion. Bien que cet ordre d’opérations ne soit pas obligatoire, il est fortement recommandé. Ainsi, une application de multidiffusion sélectionnerait d’abord une adresse IPv4 ou IPv6 sur l’ordinateur local, l’adresse IPv4 générique (INADDR_ANY) ou l’adresse IPv6 générique (in6addr_any). L’application de multidiffusion appelle ensuite la fonction bind avec cette adresse dans le sa_data membre du paramètre name pour associer l’adresse IP locale au socket. Si une adresse générique a été spécifiée, Windows sélectionne l’adresse IP locale à utiliser. Une fois la fonction de liaison terminée, une application rejoint le groupe de multidiffusion qui vous intéresse. Pour plus d’informations sur la jonction d’un groupe de multidiffusion, consultez la section programmation de multidiffusion. Ce socket peut ensuite être utilisé pour recevoir des paquets de multidiffusion à partir du groupe de multidiffusion à l’aide des fonctions recv, recvfrom, WSARecvEx, WSARecvFrom ou LPFN_WSARECVMSG (WSARecvMsg).
La fonction de liaison n’est normalement pas requise pour les opérations d’envoi à un groupe de multidiffusion. Les fonctions sendto, WSASendMsg et WSASendTo lient implicitement le socket à l’adresse générique si le socket n’est pas déjà lié. La fonction de liaison est requise avant l’utilisation des fonctions send ou WSASend qui n’effectuent pas de liaison implicite et sont autorisées uniquement sur les sockets connectés, ce qui signifie que le socket doit déjà avoir été lié pour qu’il soit connecté. La fonction bind peut être utilisée avant les opérations d’envoi à l’aide des fonctions sendto, WSASendMsg ou WSASendTo si une application voulait sélectionner une adresse IP locale spécifique sur un ordinateur local avec plusieurs interfaces réseau et adresses IP locales. Sinon, une liaison implicite à l’adresse générique à l’aide des fonctions sendto, WSASendMsg ou WSASendTo peut entraîner l’utilisation d’une adresse IP locale différente pour les opérations d’envoi.
Remarques pour les sockets IrDA
- Le fichier d’en-tête Af_irda.h doit être inclus explicitement.
- Les noms locaux ne sont pas exposés dans IrDA. Les sockets clients IrDA ne doivent donc jamais appeler la fonction bind avant la fonction de connexion . Si le socket IrDA était précédemment lié à un nom de service à l’aide de bind, la fonction de connexion échoue avec SOCKET_ERROR.
- Si le nom du service est de la forme « LSAP-SELxxx », où xxx est un entier décimal dans la plage 1-127, l’adresse indique un LSAP-SEL xxx spécifique plutôt qu’un nom de service. Les noms de service tels que ceux-ci permettent aux applications serveur d’accepter les connexions entrantes dirigées vers un LSAP-SEL spécifique, sans effectuer au préalable une requête de nom de service ISA pour obtenir le LSAP-SEL associé. Un exemple de ce type de nom de service est un appareil non-Windows qui ne prend pas en charge IAS.
Windows Phone 8 : cette fonction est prise en charge pour les applications Windows Phone Store sur 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.
Exemples
L’exemple suivant illustre l’utilisation de la fonction bind . Pour obtenir un autre exemple qui utilise la fonction bind, consultez Prise en main With Winsock.
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
int main()
{
// Declare some variables
WSADATA wsaData;
int iResult = 0; // used to return function results
// the listening socket to be created
SOCKET ListenSocket = INVALID_SOCKET;
// The socket address to be passed to bind
sockaddr_in service;
//----------------------
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != NO_ERROR) {
wprintf(L"Error at WSAStartup()\n");
return 1;
}
//----------------------
// Create a SOCKET for listening for
// incoming connection requests
ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
if (ListenSocket == INVALID_SOCKET) {
wprintf(L"socket function failed with error: %u\n", WSAGetLastError());
WSACleanup();
return 1;
}
//----------------------
// The sockaddr_in structure specifies the address family,
// IP address, and port for the socket that is being bound.
service.sin_family = AF_INET;
service.sin_addr.s_addr = inet_addr("127.0.0.1");
service.sin_port = htons(27015);
//----------------------
// Bind the socket.
iResult = bind(ListenSocket, (SOCKADDR *) &service, sizeof (service));
if (iResult == SOCKET_ERROR) {
wprintf(L"bind failed with error %u\n", WSAGetLastError());
closesocket(ListenSocket);
WSACleanup();
return 1;
}
else
wprintf(L"bind returned success\n");
WSACleanup();
return 0;
}
Configuration requise
| 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 (inclure Winsock2.h) |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |