bind-Funktion (winsock.h)

Artikel
03/04/2024

Die Bindungsfunktion ordnet eine lokale Adresse einem Socket zu.

Syntax

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

Parameter

[in] s

Ein Deskriptor, der einen ungebundenen Socket identifiziert.

addr

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 vom Addr verwiesen wird.

Rückgabewert

Wenn kein Fehler auftritt, gibt die Bindung 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	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
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 IP-Adresse und der port, die im Parameter name angegeben sind, 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 vom Parameter name verwiesen wird, 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 mit dem Namen angegebenen Speicherblocks 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 weiterhin eine Rückruffunktion.
WSAEINVAL	Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, da der Socket s bereits an eine Adresse gebunden ist.
WSAENOBUFS	In der Regel ist WSAENOBUFS ein Hinweis darauf, dass es nicht genügend kurzlebige Ports gibt, die für die Bindung zugeordnet werden können.
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 Bindungsfunktion ist für einen nicht verbundenen Socket vor nachfolgenden Aufrufen der Listenfunktion erforderlich. Es wird normalerweise verwendet, um an verbindungsorientierte (Stream) oder verbindungslose (Datagramm)-Sockets zu binden. Die Bindungsfunktion kann auch verwendet werden, um an einen unformatierten Socket zu binden (der Socket wurde erstellt, indem die Socketfunktion aufgerufen wurde, wobei der Typparameter auf SOCK_RAW festgelegt ist). Die Bindungsfunktion 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 Bindungsfunktion , um die lokale Zuordnung des Sockets herzustellen, indem Sie einem unbenannten Socket einen lokalen Namen zuweisen.

Ein Name besteht aus drei Teilen, wenn die Internetadressfamilie verwendet wird:

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 wird auf diese Weise für die Kompatibilität mit Windows Sockets 1.1 umgewandelt. Dienstanbieter können es 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 wird, geben Sie den konstanten Wert INADDR_ANY für eine lokale IPv4-Adresse oder den Konstantenwert in6addr_any für eine lokale IPv6-Adresse im sa_data Member des namensparameters an. Dies ermöglicht es dem zugrunde liegenden Dienstanbieter, jede geeignete Netzwerkadresse zu verwenden, was die Anwendungsprogrammierung bei anwesenheit von multihomed Hosts (also Hosts mit mehr als einer Netzwerkschnittstelle und -adresse) vereinfacht.

Wenn der Port für TCP/IP als Null angegeben wird, weist der Dienstanbieter der Anwendung einen eindeutigen Port aus dem dynamischen Clientportbereich zu. Unter Windows Vista und höher beträgt der dynamische Clientportbereich einen Wert zwischen 49152 und 65535. Dies ist eine Änderung gegenüber Windows Server 2003 und früher, wobei der dynamische Clientportbereich einen Wert zwischen 1025 und 5000 aufweist. Der maximale Wert für den dynamischen Clientportbereich 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 getockname verwenden, nachdem bind aufgerufen wurde, um die Adresse und den Port zu ermitteln, der dem Socket zugewiesen wurde. 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 multihomed ist. Von einer Bindung an eine andere Portnummer als Port 0 wird für Clientanwendungen abgeraten, da die Gefahr besteht, dass ein Konflikt mit einem anderen Socket besteht, der diese Portnummer bereits auf dem lokalen Computer verwendet.

Hinweis Wenn Sie bind mit der SO_EXCLUSIVEADDRUSE- oder SO_REUSEADDR Socketoption 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 Bindungsfunktion aufzurufen, um einen Socket einer lokalen IP-Adresse zuzuordnen und dann der Multicastgruppe beizutreten. 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-Adresse (in6addr_any) aus. Die Multicastanwendung ruft dann die Bindungsfunktion mit dieser Adresse im sa_data Member des name-Parameters auf, um die lokale IP-Adresse dem Socket zuzuordnen. Wenn eine Feldhalteradresse 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 einer Multicastgruppe finden Sie im Abschnitt 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 Bindungsfunktion ist normalerweise nicht für Sendevorgänge an eine Multicastgruppe erforderlich. Die Funktionen sendto, WSASendMsg und WSASendTo binden den Socket implizit an die Feldhalteradresse, wenn der Socket noch nicht gebunden ist. Die Bindungsfunktion ist vor der Verwendung der Sende- oder WSASend-Funktionen erforderlich, die keine implizite Bindung ausführen und nur für verbundene Sockets zulässig sind, was bedeutet, dass der Socket bereits gebunden sein muss, damit er verbunden werden kann. Die Bindungsfunktion 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 Feldhalteradresse mithilfe der Funktionen sendto, WSASendMsg oder WSASendTo dazu führen, dass eine andere lokale IP-Adresse für Sendevorgänge verwendet wird.

Hinweis Wenn Sie einen blockierenden Winsock-Aufruf wie bind ausgeben, 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 Ausgeben eines weiteren blockierenden Winsock-Aufrufs in einem APC, der einen fortlaufenden blockierenden Winsock-Aufruf im selben Thread unterbrochen hat, führt zu nicht definiertem Verhalten und darf niemals von Winsock-Clients versucht werden.

Hinweise zu IrDA-Sockets

Die Af_irda.h-Headerdatei muss explizit enthalten sein.
Lokale Namen werden in IrDA nicht verfügbar gemacht. IrDA-Clientsockets dürfen daher nie die Bindungsfunktion vor der Verbindungsfunktion aufrufen. Wenn der IrDA-Socket zuvor mithilfe von Bind an einen Dienstnamen gebunden war, schlägt die Verbindungsfunktion mit SOCKET_ERROR fehl.
Wenn der Dienstname das Format "LSAP-SELxxx" hat, wobei xxx eine Dezimalzahl im Bereich 1-127 ist, gibt die Adresse anstelle eines Dienstnamens einen bestimmten LSAP-SEL xxx 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

Anforderung	Wert
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	winsock.h (einschließlich Winsock2.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll