bind, fonction (winsock.h)

Article
04/21/2023

La fonction bind associe une adresse locale à un socket.

Syntaxe

int bind(
  [in] SOCKET         s,
       const sockaddr *addr,
  [in] int            namelen
);

Paramètres

[in] s

Descripteur identifiant un socket indépendant.

addr

Pointeur vers une structure sockaddr de l’adresse locale à affecter au socket lié .

[in] namelen

Longueur, en octets, de la valeur pointée par addr.

Valeur retournée

Si aucune erreur ne se produit, la liaison retourne zéro. Sinon, elle retourne SOCKET_ERROR et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur	Signification
WSANOTINITIALISED	Note Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEACCES	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 a échoué, car l’option setsockopt SO_BROADCAST n’est pas activée.
WSAEADDRINUSE	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 de l’adresse 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 la référence options de socket SOL_SOCKET , Utilisation de SO_REUSEADDR et de SO_EXCLUSIVEADDRUSE, et SO_EXCLUSIVEADDRUSE.
WSAEADDRNOTAVAIL	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.
WSAEFAULT	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 n’est pas une partie valide de l’espace d’adressage 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 aux descripteurs de socket.
WSAEINPROGRESS	Un appel Windows Sockets 1.1 bloquant est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEINVAL	Argument non valide fourni. Cette erreur est retournée car le socket est déjà lié à une adresse.
WSAENOBUFS	En règle générale, WSAENOBUFS indique qu’il n’y a pas suffisamment de ports éphémères à allouer à la liaison.
WSAENOTSOCK	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 listen . Il est normalement utilisé pour établir une liaison à 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é de Windows Sockets 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 peut simplifier la programmation des applications en présence d’hôtes multi-hébergements (c’est-à-dire des hôtes qui ont plusieurs interfaces et adresses réseau).

Pour TCP/IP, si le port est spécifié comme 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 du client dynamique 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 du 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 du client dynamique peut être consultée et modifiée à l’aide des commandes netsh . La plage de ports du client dynamique 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 avoir appelé 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.

Note Lors de l’utilisation de bind avec l’option SO_EXCLUSIVEADDRUSE ou SO_REUSEADDR socket, l’option de socket doit être définie avant l’exécution de la liaison pour avoir un impact. Pour plus d’informations, consultez SO_EXCLUSIVEADDRUSE et Utilisation de SO_REUSEADDR et SO_EXCLUSIVEADDRUSE.

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 à joindre le groupe de multidiffusion. Bien que cet ordre d’opérations ne soit pas obligatoire, il est fortement recommandé. Par conséquent, une application de multidiffusion sélectionne 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 façon de joindre un groupe de multidiffusion, consultez la section programmation multidiffusion. Ce socket peut ensuite être utilisé pour recevoir des paquets de multidiffusion à partir du groupe de multidiffusion à l’aide des fonctions recv, recvfrom, WSARecvV, WSARecvEx, WSARecvFrom ou LPFN_WSARECVMSG (WSARecvMsg).

La fonction bind n’est normalement pas nécessaire pour envoyer des opérations à 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 d’envoi 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 d’envoyer des opérations à l’aide des fonctions sendto, WSASendMsg ou WSASendTo si une application souhaitait 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.

Note Lors de l’émission d’un appel Winsock bloquant tel que bind, Winsock peut avoir besoin d’attendre un événement réseau avant que l’appel puisse se terminer. Winsock effectue une attente pouvant être alertée 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 interrompt 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.

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. Par conséquent, les sockets clients IrDA ne doivent 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

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	winsock.h (inclure Winsock2.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll