Funzione bind (winsock.h)

Articolo
03/04/2024

La funzione bind associa un indirizzo locale a un socket.

Sintassi

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

Parametri

[in] s

Descrittore che identifica un socket non associato.

addr

Puntatore a una struttura sockaddr dell'indirizzo locale da assegnare al socket associato.

[in] namelen

Lunghezza, in byte, del valore a cui punta addr.

Valore restituito

Se non si verifica alcun errore, bind restituisce zero. In caso contrario, restituisce SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Codice di errore	Significato
WSANOTINITIALISED	Nota Prima di usare questa funzione, è necessario che venga eseguita una chiamata WSAStartup riuscita.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEACCES	È stato effettuato un tentativo di accesso a un socket in modo non consentito dalle autorizzazioni di accesso. Questo errore viene restituito se nn tenta di associare un socket di datagram all'indirizzo broadcast non riuscito perché l'opzione setsockopt SO_BROADCAST non è abilitata.
WSAEADDRINUSE	Only one usage of each socket address (protocol/network address/port) is normally permitted. Questo errore viene restituito se un processo nel computer è già associato allo stesso indirizzo completo e il socket non è stato contrassegnato per consentire il riutilizzo degli indirizzi con SO_REUSEADDR. Ad esempio, l'indirizzo IP e la porta specificati nel parametro name sono già associati a un altro socket usato da un'altra applicazione. Per altre informazioni, vedere l'opzione socket SO_REUSEADDR nel riferimento opzioni socket SOL_SOCKET , Uso di SO_REUSEADDR e SO_EXCLUSIVEADDRUSE e SO_EXCLUSIVEADDRUSE.
WSAEADDRNOTAVAIL	L'indirizzo richiesto non è valido nel contesto. Questo errore viene restituito se l'indirizzo specificato a cui punta il parametro name non è un indirizzo IP locale valido nel computer.
WSAEFAULT	Il sistema ha rilevato un indirizzo puntatore non valido nel tentativo di usare un argomento puntatore in una chiamata. Questo errore viene restituito se il parametro name è NULL, il nome o il parametro namelen non è una parte valida dello spazio indirizzi utente, il parametro namelen è troppo piccolo, il parametro name contiene un formato di indirizzo non corretto per la famiglia di indirizzi associata o i primi due byte del blocco di memoria specificato dal nome non corrispondono alla famiglia di indirizzi associata al descrittore del socket.
WSAEINPROGRESS	È in corso una chiamata di Windows Sockets 1.1 bloccante oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINVAL	Argomento fornito non valido. Questo errore viene restituito del socket s è già associato a un indirizzo.
WSAENOBUFS	In genere, WSAENOBUFS indica che non sono presenti porte temporanee sufficienti da allocare per l'associazione.
WSAENOTSOCK	È stata tentata un'operazione su un elemento che non è un socket. Questo errore viene restituito se il descrittore nel parametro s non è un socket.

Commenti

La funzione di associazione è necessaria su un socket non connesso prima delle chiamate successive alla funzione di ascolto . Viene in genere usato per l'associazione a socket orientati alla connessione (flusso) o senza connessione (datagrammi). La funzione di associazione può essere usata anche per eseguire l'associazione a un socket non elaborato (il socket è stato creato chiamando la funzione socket con il parametro di tipo impostato su SOCK_RAW). La funzione di associazione può essere usata anche in un socket non connesso prima delle chiamate successive alle funzioni connect, ConnectEx, WSAConnect,WSAConnectByList o WSAConnectByName prima delle operazioni di invio.

Quando un socket viene creato con una chiamata alla funzione socket , esiste in uno spazio dei nomi (famiglia di indirizzi), ma non ha alcun nome assegnato. Usare la funzione bind per stabilire l'associazione locale del socket assegnando un nome locale a un socket senza nome.

Un nome è costituito da tre parti quando si usa la famiglia di indirizzi Internet:

Famiglia di indirizzi.
Indirizzo host.
Numero di porta che identifica l'applicazione.

In Windows Sockets 2 il parametro name non viene interpretato rigorosamente come puntatore a una struttura sockaddr . Viene eseguito il cast in questo modo per la compatibilità di Windows Sockets 1.1. I provider di servizi sono liberi di considerarlo come puntatore a un blocco di memoria di size namelen. I primi 2 byte in questo blocco (corrispondenti al membro sa_family della struttura sockaddr , il membro sin_family della struttura sockaddr_in o il membro sin6_family della struttura sockaddr_in6 ) devono contenere la famiglia di indirizzi utilizzata per creare il socket. In caso contrario, si verifica un errore WSAEFAULT.

Se un'applicazione non interessa l'indirizzo locale assegnato, specificare il valore costante INADDR_ANY per un indirizzo locale IPv4 o il valore costante in6addr_any per un indirizzo locale IPv6 nel membro sa_data del parametro name . Ciò consente al provider di servizi sottostante di usare qualsiasi indirizzo di rete appropriato, semplificando potenzialmente la programmazione dell'applicazione in presenza di host multihomed , ovvero host con più interfacce di rete e indirizzo.

Per TCP/IP, se la porta è specificata come zero, il provider di servizi assegna una porta univoca all'applicazione dall'intervallo di porte client dinamiche. In Windows Vista e versioni successive l'intervallo di porte client dinamiche è un valore compreso tra 49152 e 65535. Si tratta di una modifica rispetto a Windows Server 2003 e versioni precedenti in cui l'intervallo di porte client dinamiche era un valore compreso tra 1025 e 5000. Il valore massimo per l'intervallo di porte dinamiche del client può essere modificato impostando un valore nella chiave del Registro di sistema seguente:

HKLM\System\CurrentControlSet\Services\Tcpip\Parameters

Il valore del Registro di sistema MaxUserPort imposta il valore da usare per il valore massimo dell'intervallo di porte client dinamiche. Per rendere effettiva questa impostazione, è necessario riavviare il computer.

In Windows Vista e versioni successive è possibile visualizzare e modificare l'intervallo di porte client dinamiche usando i comandi netsh . L'intervallo di porte client dinamiche può essere impostato in modo diverso per UDP e TCP e anche per IPv4 e IPv6. Per altre informazioni, vedere kb 929851.

L'applicazione può usare getsockname dopo aver chiamato binding per apprendere l'indirizzo e la porta assegnata al socket. Se l'indirizzo Internet è uguale a INADDR_ANY o in6addr_any, getsockname non può necessariamente fornire l'indirizzo finché il socket non è connesso, poiché diversi indirizzi possono essere validi se l'host è multihomed. L'associazione a un numero di porta specifico diverso dalla porta 0 è sconsigliata per le applicazioni client, poiché esiste un pericolo di conflitto con un altro socket che già usa tale numero di porta nel computer locale.

Nota Quando si usa l'associazione con l'opzione socket SO_EXCLUSIVEADDRUSE o SO_REUSEADDR, è necessario impostare l'opzione socket prima dell'esecuzione dell'associazione per avere alcun effetto. Per altre informazioni, vedere SO_EXCLUSIVEADDRUSE e Uso di SO_REUSEADDR e SO_EXCLUSIVEADDRUSE.

Per le operazioni multicast, il metodo preferito consiste nel chiamare la funzione bind per associare un socket a un indirizzo IP locale e quindi aggiungere il gruppo multicast. Anche se questo ordine di operazioni non è obbligatorio, è consigliabile. Pertanto, un'applicazione multicast seleziona prima un indirizzo IPv4 o IPv6 nel computer locale, l'indirizzo IPv4 con caratteri jolly (INADDR_ANY) o l'indirizzo IPv6 con caratteri jolly (in6addr_any). L'applicazione multicast chiamerebbe quindi la funzione di associazione con questo indirizzo nel membro sa_data del parametro name per associare l'indirizzo IP locale al socket. Se è stato specificato un indirizzo con caratteri jolly, Windows selezionerà l'indirizzo IP locale da usare. Al termine della funzione di associazione , un'applicazione aggiungerà quindi il gruppo multicast di interesse. Per altre informazioni su come partecipare a un gruppo multicast, vedere la sezione relativa alla programmazione multicast. Questo socket può quindi essere usato per ricevere pacchetti multicast dal gruppo multicast usando le funzioni recv, recvfrom, WSARecv, WSARecvEx, WSARecvFrom o LPFN_WSARECVMSG (WSARecvMsg).

La funzione bind non è in genere necessaria per le operazioni di invio a un gruppo multicast. Le funzioni sendto,WSASendMsg e WSASendTo associano implicitamente il socket all'indirizzo con caratteri jolly se il socket non è già associato. La funzione bind è necessaria prima dell'uso delle funzioni send o WSASend che non eseguono un binding implicito e sono consentite solo sui socket connessi, il che significa che il socket deve essere già stato associato per essere connesso. La funzione bind può essere usata prima delle operazioni di invio usando le funzioni sendto, WSASendMsg o WSASendTo se un'applicazione desidera selezionare un indirizzo IP locale specifico in un computer locale con più interfacce di rete e indirizzi IP locali. In caso contrario, un'associazione implicita all'indirizzo con caratteri jolly tramite le funzioni sendto,WSASendMsg o WSASendTo potrebbe comportare l'uso di un indirizzo IP locale diverso per le operazioni di invio.

Nota Quando si esegue una chiamata Winsock bloccante, ad esempio bind, Winsock potrebbe dover attendere un evento di rete prima che la chiamata possa essere completata. Winsock esegue un'attesa avvisabile in questa situazione, che può essere interrotta da una chiamata di procedura asincrona pianificata nello stesso thread. L'esecuzione di un'altra chiamata Winsock bloccante all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread causerà un comportamento non definito e non deve mai essere tentata dai client Winsock.

Note per i socket IrDA

Il file di intestazione Af_irda.h deve essere incluso in modo esplicito.
I nomi locali non vengono esposti in IrDA. I socket client IrDA, pertanto, non devono mai chiamare la funzione bind prima della funzione connect . Se il socket IrDA è stato associato in precedenza a un nome di servizio tramite bind, la funzione di connessione avrà esito negativo con SOCKET_ERROR.
Se il nome del servizio è nel formato "LSAP-SELxxx", dove xxx è un numero intero decimale nell'intervallo 1-127, l'indirizzo indica un LSAP-SEL specifico anziché un nome di servizio. I nomi dei servizi, ad esempio questi, consentono alle applicazioni server di accettare connessioni in ingresso indirizzate a un LSAP-SEL specifico, senza prima eseguire una query del nome del servizio ISA per ottenere l'LSAP-SEL associato. Un esempio di questo tipo di nome di servizio è un dispositivo non Windows che non supporta IAS.

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Esempio

Nell'esempio seguente viene illustrato l'uso della funzione di associazione . Per un altro esempio che usa la funzione di associazione, vedere Introduzione 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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock.h (include Winsock2.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll