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.

[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.

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 );

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;
    }
}

Anforderungen

Weitere Informationen

IPPROTO_IPV6 Socketoptionen

SOCKADDR

WSAConnect

WSAConnectByList

WSAGetLastError

getaddrinfo

getpeername

getsockname

setsockopt