WSAConnectByNameW-Funktion (winsock2.h)

Die WSAConnectByName-Funktion stellt eine Verbindung mit einem angegebenen Host und Port her. Diese Funktion wird bereitgestellt, um eine schnelle Verbindung mit einem Netzwerkendpunkt unter Angabe eines Hostnamens und Ports zu ermöglichen.

Diese Funktion unterstützt sowohl IPv4- als auch IPv6-Adressen.

Syntax

BOOL WSAConnectByNameW(
  [in]      SOCKET          s,
  [in]      LPWSTR          nodename,
  [in]      LPWSTR          servicename,
  [in, out] LPDWORD         LocalAddressLength,
  [out]     LPSOCKADDR      LocalAddress,
  [in, out] LPDWORD         RemoteAddressLength,
  [out]     LPSOCKADDR      RemoteAddress,
  [in]      const timeval   *timeout,
            LPWSAOVERLAPPED Reserved
);

Parameter

[in] s

Ein Deskriptor, der einen nicht verbundenen Socket identifiziert.

Hinweis Unter Windows 7, Windows Server 2008 R2 und früher erfordert die WSAConnectByName-Funktion einen nicht gebundenen und nicht verbundenen Socket. Dies unterscheidet sich von anderen Winsock-Aufrufen zum Herstellen einer Verbindung (z. B. WSAConnect).
 

[in] nodename

Eine NULL-beendete Zeichenfolge, die den Namen des Hosts oder die IP-Adresse des Hosts enthält, auf dem für IPv4 oder IPv6 eine Verbindung hergestellt werden soll.

[in] servicename

Eine NULL-beendete Zeichenfolge, die den Dienstnamen oder Zielport des Hosts enthält, auf dem für IPv4 oder IPv6 eine Verbindung hergestellt werden soll.

Ein Dienstname ist ein Zeichenfolgenalias für eine Portnummer. Beispielsweise ist "http" ein Alias für Port 80, der von der Internet Engineering Task Force (IETF) als Standardport definiert wird, der von Webservern für das HTTP-Protokoll verwendet wird. Mögliche Werte für den Servicename-Parameter , wenn keine Portnummer angegeben ist, sind in der folgenden Datei aufgeführt:

%WINDIR%\system32\drivers\etc\services

[in, out] LocalAddressLength

Bei der Eingabe ein Zeiger auf die Größe des vom Aufrufer bereitgestellten LocalAddress-Puffers in Bytes. Bei der Ausgabe ein Zeiger auf die Größe des SOCKADDR für die lokale Adresse, die im LocalAddress-Puffer gespeichert ist, der nach erfolgreichem Abschluss des Aufrufs vom System ausgefüllt wird.

[out] LocalAddress

Ein Zeiger auf die SOCKADDR-Struktur , die die lokale Adresse der Verbindung empfängt. Die Größe des Parameters entspricht genau der Größe, die in LocalAddressLength zurückgegeben wird. Dies sind die gleichen Informationen, die von der getockname-Funktion zurückgegeben würden. Dieser Parameter kann NULL sein. In diesem Fall wird der Parameter LocalAddressLength ignoriert.

[in, out] RemoteAddressLength

Bei der Eingabe ein Zeiger auf die Größe des vom Aufrufer bereitgestellten RemoteAddress-Puffers in Bytes. Bei der Ausgabe wird ein Zeiger auf die Größe des SOCKADDR für die im RemoteAddress-Puffer gespeicherte Remoteadresse in Bytes angezeigt, die nach erfolgreichem Abschluss des Aufrufs vom System ausgefüllt wird.

[out] RemoteAddress

Ein Zeiger auf die SOCKADDR-Struktur , die die Remoteadresse der Verbindung empfängt. Dies sind die gleichen Informationen, die von der getpeername-Funktion zurückgegeben würden. Dieser Parameter kann NULL sein. In diesem Fall wird remoteAddressLength ignoriert.

[in] timeout

Die Zeit in Millisekunden, um auf eine Antwort von der Remoteanwendung zu warten, bevor der Aufruf abgebrochen wird.

Reserved

Reserviert für die zukünftige Implementierung. Dieser Parameter muss auf NULL festgelegt werden.

Rückgabewert

Wenn eine Verbindung hergestellt wird, gibt WSAConnectByNameTRUE zurück, und die Parameter LocalAddress und RemoteAddress werden ausgefüllt, wenn diese Puffer vom Aufrufer bereitgestellt wurden.

Wenn der Aufruf fehlschlägt, wird FALSE zurückgegeben. WSAGetLastError kann dann aufgerufen werden, um erweiterte Fehlerinformationen zu erhalten.

Rückgabecode Beschreibung
WSAEHOSTUNREACH
Der host, der als nodename-Parameter übergeben wurde, war nicht erreichbar.
WSAEINVAL
Es wurde ein ungültiger Parameter an die Funktion übergeben. Der Nodename - oder servicename-Parameter darf nicht NULL sein. Der Reserved-Parameter muss NULL sein.
WSAENOBUFS
Es konnte kein ausreichender Arbeitsspeicher zugewiesen werden.
WSAENOTSOCK
Ein ungültiger Socket wurde an die Funktion übergeben. Der s-Parameter darf nicht INVALID_SOCKET oder NULL sein.
WSAETIMEDOUT
Eine Antwort der Remoteanwendung wurde nicht empfangen, bevor der Timeoutparameter überschritten wurde.

Hinweise

WSAConnectByName wird bereitgestellt, um schnelle und transparente Verbindungen mit Remotehosts an bestimmten Ports zu ermöglichen. Es ist sowohl mit IPv6- als auch mit IPv4-Versionen kompatibel.

Verwenden Sie die folgende Methode, um sowohl die IPv6- als auch die IPv4-Kommunikation zu aktivieren:

  • Die setockopt-Funktion muss für einen Socket aufgerufen werden, der für die AF_INET6 Adressfamilie erstellt wurde, um die Socketoption IPV6_V6ONLY vor dem Aufrufen von WSAConnectByName zu deaktivieren. Dies wird durch Aufrufen der setockopt-Funktion für den Socket mit dem level-Parameter auf IPPROTO_IPV6 (siehe IPPROTO_IPV6 Socketoptionen), dem auf IPV6_V6ONLY festgelegten optname-Parameter und dem wert des optvalue-Parameters auf Null erreicht.

WSAConnectByName hat Einschränkungen: Es funktioniert nur für verbindungsorientierte Sockets, z. B. solche vom Typ SOCK_STREAM. Die Funktion unterstützt kein überlappende E/A- oder nicht blockierende Verhalten. WSAConnectByName blockiert auch dann, wenn sich der Socket im nicht blockierenden Modus befindet.

WSAConnectByName unterstützt beim Herstellen einer Verbindung keine vom Benutzer bereitgestellten Daten. Dieser Aufruf unterstützt auch keine FLOWSPEC-Strukturen. In Fällen, in denen diese Features erforderlich sind, muss stattdessen WSAConnect verwendet werden.

Wenn eine Anwendung in Versionen vor Windows 10 eine Bindung an eine bestimmte lokale Adresse oder einen port benötigt, kann WSAConnectByName nicht verwendet werden, da der Socketparameter für WSAConnectByName ein ungebundener Socket sein muss.

Diese Einschränkung wurde Windows 10 entfernt.

Die Parameter RemoteAddress und LocalAddress verweisen auf eine SOCKADDR-Struktur , bei der es sich um einen generischen Datentyp handelt. Wenn WSAConnectByName aufgerufen wird, wird erwartet, dass ein Socketadresstyp, der für das verwendete Netzwerkprotokoll oder die verwendete Adressfamilie spezifisch ist, tatsächlich in diesen Parametern übergeben wird. Für IPv4-Adressen würde also ein Zeiger auf eine sockaddr_in-Struktur in einen Zeiger auf SOCKADDR als Die Parameter RemoteAddress und LocalAddress umgewandelt. Bei IPv6-Adressen wird ein Zeiger auf eine sockaddr_in6-Struktur in einen Zeiger auf SOCKADDR als RemoteAddress - und LocalAddress-Parameter umgewandelt.

Wenn die WSAConnectByName-FunktionTRUE zurückgibt, befindet sich der Socket s im Standardzustand für einen verbundenen Socket. Die Sockets aktivieren zuvor festgelegte Eigenschaften oder Optionen erst, wenn SO_UPDATE_CONNECT_CONTEXT für den Socket festgelegt wurde. Verwenden Sie die setockopt-Funktion , um die Option SO_UPDATE_CONNECT_CONTEXT festzulegen.

Beispiel:

//Need to #include <mswsock.h> for SO_UPDATE_CONNECT_CONTEXT

int iResult = 0;

iResult = setsockopt( s, SOL_SOCKET, SO_UPDATE_CONNECT_CONTEXT, NULL, 0 );

Hinweis Beim Ausgeben eines blockierenden Winsock-Aufrufs wie WSAConnectByName mit dem timeout-Parameter , der auf NULL festgelegt ist, 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.
 
Windows Phone 8: Die WSAConnectByNameW-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: Die WSAConnectByNameW-Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Beispiele

Stellen Sie mithilfe von WSAConnectByName eine Verbindung her.

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <mswsock.h>   // Need for SO_UPDATE_CONNECT_CONTEXT
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

SOCKET
OpenAndConnect(LPWSTR NodeName, LPWSTR PortName) 
{
    SOCKET ConnSocket = INVALID_SOCKET;
    int ipv6only = 0;
    int iResult;
    BOOL bSuccess;
    SOCKADDR_STORAGE LocalAddr = {0};
    SOCKADDR_STORAGE RemoteAddr = {0};
    DWORD dwLocalAddr = sizeof(LocalAddr);
    DWORD dwRemoteAddr = sizeof(RemoteAddr);
  
    ConnSocket = socket(AF_INET6, SOCK_STREAM, 0);
    if (ConnSocket == INVALID_SOCKET){
        wprintf(L"socket failed with error: %d\n", WSAGetLastError());
        return INVALID_SOCKET;
    }

    iResult = setsockopt(ConnSocket, IPPROTO_IPV6,
        IPV6_V6ONLY, (char*)&ipv6only, sizeof(ipv6only) );
    if (iResult == SOCKET_ERROR){
        wprintf(L"setsockopt for IPV6_V6ONLY failed with error: %d\n",
            WSAGetLastError());
        closesocket(ConnSocket);
        return INVALID_SOCKET;       
    }

    bSuccess = WSAConnectByName(ConnSocket, NodeName, 
            PortName, &dwLocalAddr,
            (SOCKADDR*)&LocalAddr,
            &dwRemoteAddr,
            (SOCKADDR*)&RemoteAddr,
            NULL,
            NULL);
    if (!bSuccess){
        wprintf(L"WsaConnectByName failed with error: %d\n", WSAGetLastError());
        closesocket(ConnSocket);
        return INVALID_SOCKET;       

    
    }

    iResult = setsockopt(ConnSocket, SOL_SOCKET,
        SO_UPDATE_CONNECT_CONTEXT, NULL, 0);
    if (iResult == SOCKET_ERROR){
        wprintf(L"setsockopt for SO_UPDATE_CONNECT_CONTEXT failed with error: %d\n",
            WSAGetLastError());
        closesocket(ConnSocket);
        return INVALID_SOCKET;       
    }

    return ConnSocket;
}

int __cdecl wmain(int argc, wchar_t **argv)
{
   //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    SOCKET s = INVALID_SOCKET;

    // Validate the parameters
    if (argc != 3) {
        wprintf(L"usage: %ws <Nodename> <Portname>\n", argv[0]);
        wprintf(L"wsaconnectbyname establishes a connection to a specified host and port.\n");
        wprintf(L"%ws www.contoso.com 8080\n", argv[0]);
        return 1;
    }

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed: %d\n", iResult);
        return 1;
    }

    wprintf(L"WsaConnectByName with following parameters:\n");
    wprintf(L"\tNodename = %ws\n", argv[1]);
    wprintf(L"\tPortname (or port) = %ws\n\n", argv[2]);

    //--------------------------------
    // Call our function that uses the WsaConnectByName. 
    
    s = OpenAndConnect(argv[1], argv[2]);
    if ( s == INVALID_SOCKET ) {
        wprintf(L"WsaConnectByName failed with error: %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    else
    {
        wprintf(L"WsaConnectByName succeeded\n");
        
        closesocket(s);
        WSACleanup();
        return 0;
    }
}

Hinweis

Der winsock2.h-Header definiert WSAConnectByName als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 8.1, Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile winsock2.h
Bibliothek Ws2_32.lib
DLL Ws2_32.dll

Weitere Informationen

IPPROTO_IPV6 Socketoptionen

SOCKADDR

WSAConnect

WSAConnectByList

WSAGetLastError

getaddrinfo

getpeername

getsockname

setsockopt