bind-Funktion (winsock2.h)

Artikel
08/27/2023

Die Bindfunktion ordnet eine lokale Adresse einem Socket zu.

Syntax

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

Parameter

[in] s

Ein Deskriptor, der einen ungebundenen Socket identifiziert.

[in] name

Ein Zeiger auf eine sockaddr-Struktur der lokalen Adresse, die dem gebundenen Socket zugewiesen werden soll.

[in] namelen

Die Länge des Werts in Bytes, auf den der name-Parameter verweist.

Rückgabewert

Wenn kein Fehler auftritt, gibt bind null zurück. Andernfalls wird SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSANOTINITIALISIERT	Hinweis Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAEACCES	Der Zugriff auf einen Socket war aufgrund der Zugriffsrechte des Sockets unzulässig. Dieser Fehler wird zurückgegeben, wenn nn versucht, einen Datagrammsocket an die Broadcastadresse zu binden, fehlgeschlagen ist, weil die Option setsockopt SO_BROADCAST nicht aktiviert ist.
WSAEADDRINUSE	Only one usage of each socket address (protocol/network address/port) is normally permitted. Dieser Fehler wird zurückgegeben, wenn ein Prozess auf dem Computer bereits an dieselbe vollqualifizierte Adresse gebunden ist und der Socket nicht markiert wurde, um die Wiederverwendung von Adressen mit SO_REUSEADDR zu ermöglichen. Beispielsweise sind die im name-Parameter angegebene IP-Adresse und der Port bereits an einen anderen Socket gebunden, der von einer anderen Anwendung verwendet wird. Weitere Informationen finden Sie unter SO_REUSEADDR Socketoption in der Referenz zu SOL_SOCKET Socketoptionen , Verwenden von SO_REUSEADDR und SO_EXCLUSIVEADDRUSE und SO_EXCLUSIVEADDRUSE.
WSAEADDRNOTAVAIL	Die angeforderte Adresse ist in ihrem Kontext nicht gültig. Dieser Fehler wird zurückgegeben, wenn die angegebene Adresse, auf die der Name-Parameter verweist, keine gültige lokale IP-Adresse auf diesem Computer ist.
WSAEFAULT	Das System hat beim Versuch, ein Zeigerargument in einem Aufruf zu verwenden, eine ungültige Zeigeradresse erkannt. Dieser Fehler wird zurückgegeben, wenn der Name-Parameter NULL ist, der name oder namelen-Parameter kein gültiger Teil des Benutzeradressraums ist, der namelen-Parameter zu klein ist, der name-Parameter ein falsches Adressformat für die zugeordnete Adressfamilie enthält oder die ersten beiden Bytes des speicherblocks, der durch den Namen angegeben ist, nicht mit der Adressfamilie übereinstimmen, die dem Socketdeskriptor s zugeordnet ist.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion.
WSAEINVAL	Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn die Sockets bereits an eine Adresse gebunden sind.
WSAENOBUFS	Ein Vorgang für einen Socket konnte nicht ausgeführt werden, weil dem System ausreichender Pufferspeicherplatz fehlte oder eine Warteschlange voll war. Dieser Fehler wird zurückgegeben, da nicht genügend Puffer verfügbar sind oder zu viele Verbindungen vorhanden sind.
WSAENOTSOCK	Es wurde ein Vorgang für eine Komponente versucht, die kein Socket ist. Dieser Fehler wird zurückgegeben, wenn der Deskriptor im s-Parameter kein Socket ist.

Hinweise

Die Bindfunktion ist für einen nicht verbundenen Socket vor nachfolgenden Aufrufen der Listenfunktion erforderlich. Normalerweise wird es verwendet, um eine Bindung an verbindungsorientierte Sockets (Stream) oder an verbindungslose Sockets (Datagramme) zu binden. Die Bindfunktion kann auch verwendet werden, um eine Bindung an einen unformatierten Socket zu erstellen (der Socket wurde durch Aufrufen der Socketfunktion erstellt, wobei der Typparameter auf SOCK_RAW festgelegt ist). Die Bindfunktion kann auch auf einem nicht verbundenen Socket vor nachfolgenden Aufrufen der Funktionen connect, ConnectEx, WSAConnect, WSAConnectByList oder WSAConnectByName vor Sendevorgängen verwendet werden.

Wenn ein Socket mit einem Aufruf der Socketfunktion erstellt wird, ist er in einem Namespace (Adressfamilie) vorhanden, ihm ist jedoch kein Name zugewiesen. Verwenden Sie die Bindfunktion , um die lokale Zuordnung des Sockets herzustellen, indem Sie einem unbenannten Socket einen lokalen Namen zuweisen.

Ein Name besteht bei Verwendung der Internetadressenfamilie aus drei Teilen:

Die Adressfamilie.
Eine Hostadresse.
Eine Portnummer, die die Anwendung identifiziert.

In Windows Sockets 2 wird der name-Parameter nicht streng als Zeiger auf eine sockaddr-Struktur interpretiert. Es ist auf diese Weise für die Kompatibilität mit Windows Sockets 1.1 umgewandelt. Dienstanbieter können dies als Zeiger auf einen Speicherblock der Größe namelen betrachten. Die ersten 2 Bytes in diesem Block (entsprechend dem sa_family Member der sockaddr-Struktur , dem sin_family Member der sockaddr_in-Struktur oder dem sin6_family Member der sockaddr_in6-Struktur ) müssen die Adressfamilie enthalten, die zum Erstellen des Sockets verwendet wurde. Andernfalls tritt ein Fehler WSAEFAULT auf.

Wenn es einer Anwendung egal ist, welche lokale Adresse zugewiesen ist, geben Sie den konstanten Wert INADDR_ANY für eine lokale IPv4-Adresse oder den konstanten Wert in6addr_any für eine lokale IPv6-Adresse im sa_data member des name-Parameters an. Dies ermöglicht es dem zugrunde liegenden Dienstanbieter, jede geeignete Netzwerkadresse zu verwenden, was möglicherweise die Anwendungsprogrammierung in Gegenwart von multihomed Hosts (d. a. Hosts mit mehr als einer Netzwerkschnittstelle und -adresse) vereinfacht.

Wenn der Port für TCP/IP als null angegeben ist, weist der Dienstanbieter der Anwendung einen eindeutigen Port aus dem dynamischen Clientportbereich zu. Unter Windows Vista und höher liegt der dynamische Clientportbereich zwischen 49152 und 65535. Dies ist eine Änderung gegenüber Windows Server 2003 und früheren Versionen, bei denen der dynamische Clientportbereich einen Wert zwischen 1025 und 5000 aufweist. Der Maximalwert für den clientdynamischen Portbereich kann durch Festlegen eines Werts unter dem folgenden Registrierungsschlüssel geändert werden:

HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

Der Registrierungswert MaxUserPort legt den Wert fest, der für den maximalen Wert des dynamischen Clientportbereichs verwendet werden soll. Sie müssen den Computer neu starten, damit diese Einstellung wirksam wird.

Unter Windows Vista und höher kann der dynamische Clientportbereich mithilfe von netsh-Befehlen angezeigt und geändert werden. Der dynamische Clientportbereich kann für UDP und TCP sowie für IPv4 und IPv6 unterschiedlich festgelegt werden. Weitere Informationen finden Sie unter KB-929851.

Die Anwendung kann getsockname nach dem Aufruf von bind verwenden, um die Adresse und den Port zu ermitteln, die dem Socket zugewiesen wurden. Wenn die Internetadresse gleich INADDR_ANY oder in6addr_any ist, kann getsockname die Adresse nicht unbedingt angeben, bis der Socket verbunden ist, da mehrere Adressen gültig sein können, wenn der Host mehrfach vernetzt ist. Eine Bindung an eine andere Portnummer als Port 0 wird für Clientanwendungen abgeraten, da ein Konflikt mit einem anderen Socket besteht, der diese Portnummer bereits auf dem lokalen Computer verwendet.

Hinweis Wenn Sie die Bindung mit der Option SO_EXCLUSIVEADDRUSE oder SO_REUSEADDR Socket verwenden, muss die Socketoption vor dem Ausführen der Bindung festgelegt werden, um Auswirkungen zu haben. Weitere Informationen finden Sie unter SO_EXCLUSIVEADDRUSE und Verwenden von SO_REUSEADDR und SO_EXCLUSIVEADDRUSE.

Bei Multicastvorgängen besteht die bevorzugte Methode darin, die Bindfunktion aufzurufen, um einen Socket einer lokalen IP-Adresse zuzuordnen und dann die Multicastgruppe zu verknüpfen. Obwohl diese Reihenfolge der Vorgänge nicht obligatorisch ist, wird sie dringend empfohlen. Eine Multicastanwendung wählt also zuerst eine IPv4- oder IPv6-Adresse auf dem lokalen Computer, die IPv4-INADDR_ANY-Adresse oder die IPv6-In6addr_any aus. Die Multicastanwendung ruft dann die Bindfunktion mit dieser Adresse im sa_data Member des name-Parameters auf, um die lokale IP-Adresse dem Socket zuzuordnen. Wenn eine Wildcardadresse angegeben wurde, wählt Windows die zu verwendende lokale IP-Adresse aus. Nach Abschluss der Bindungsfunktion wird eine Anwendung der Multicastgruppe von Interesse beitreten. Weitere Informationen zum Beitreten zu einer Multicastgruppe finden Sie im Abschnitt zur Multicastprogrammierung. Dieser Socket kann dann verwendet werden, um Multicastpakete von der Multicastgruppe mit den Funktionen recv, recvfrom, WSARecv, WSARecvEx, WSARecvFrom oder LPFN_WSARECVMSG (WSARecvMsg) zu empfangen.

Die Bindfunktion ist normalerweise nicht für Sendevorgänge an eine Multicastgruppe erforderlich. Die Funktionen sendto, WSASendMsg und WSASendTo binden den Socket implizit an die Wildcardadresse, wenn der Socket noch nicht gebunden ist. Die Bindfunktion ist vor der Verwendung der Send- oder WSASend-Funktionen erforderlich, die keine implizite Bindung ausführen und nur für verbundene Sockets zulässig sind. Dies bedeutet, dass der Socket bereits gebunden sein muss, damit er verbunden werden kann. Die Bindfunktion kann vor Sendevorgängen mithilfe der Funktionen sendto, WSASendMsg oder WSASendTo verwendet werden, wenn eine Anwendung eine bestimmte lokale IP-Adresse auf einem lokalen Computer mit mehreren Netzwerkschnittstellen und lokalen IP-Adressen auswählen möchte. Andernfalls kann eine implizite Bindung an die Wildcardadresse mithilfe der Funktionen sendto, WSASendMsg oder WSASendTo dazu führen, dass für Sendevorgänge eine andere lokale IP-Adresse verwendet wird.

Hinweis Wenn Sie einen blockierenden Winsock-Aufruf wie bind ausstellen, muss Winsock möglicherweise auf ein Netzwerkereignis warten, bevor der Aufruf abgeschlossen werden kann. Winsock führt in dieser Situation eine warnbare Wartezeit aus, die durch einen asynchronen Prozeduraufruf (APC) unterbrochen werden kann, der für denselben Thread geplant ist. Das Ausstellen eines weiteren blockierenden Winsock-Aufrufs innerhalb eines APC, der einen fortlaufend blockierenden Winsock-Aufruf im selben Thread unterbrochen hat, führt zu undefiniertem Verhalten und darf niemals von Winsock-Clients versucht werden.

Hinweise zu IrDA-Sockets

Die Headerdatei Af_irda.h muss explizit eingeschlossen werden.
Lokale Namen werden in IrDA nicht verfügbar gemacht. IrDA-Clientsockets dürfen daher niemals die Bindfunktion vor der Verbindungsfunktion aufrufen. Wenn der IrDA-Socket zuvor mithilfe von bind an einen Dienstnamen gebunden wurde, schlägt die Verbindungsfunktion mit SOCKET_ERROR fehl.
Wenn der Dienstname die Form "LSAP-SELxxx" hat, wobei xxx eine dezimale ganze Zahl im Bereich von 1 bis 127 ist, gibt die Adresse einen bestimmten LSAP-SEL xxx anstelle eines Dienstnamens an. Dienstnamen wie diese ermöglichen Es Serveranwendungen, eingehende Verbindungen zu akzeptieren, die an eine bestimmte LSAP-SEL weitergeleitet werden, ohne zuerst eine ISA-Dienstnamenabfrage auszuführen, um die zugeordnete LSAP-SEL abzurufen. Ein Beispiel für diesen Dienstnamenstyp ist ein Nicht-Windows-Gerät, das IAS nicht unterstützt.

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Beispiele

Im folgenden Beispiel wird die Verwendung der Bindfunktion veranschaulicht. Ein weiteres Beispiel, das die Bindungsfunktion verwendet, finden Sie unter Erste Schritte Mit 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;
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h (einschließlich Winsock2.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll