WSAConnectByNameA-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 WSAConnectByNameA(
[in] SOCKET s,
[in] LPCSTR nodename,
[in] LPCSTR 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.
| Rückgabecode | Beschreibung |
|---|---|
|
Der host, der als nodename-Parameter übergeben wurde, war nicht erreichbar. |
|
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. |
|
Es konnte kein ausreichender Arbeitsspeicher zugewiesen werden. |
|
Ein ungültiger Socket wurde an die Funktion übergeben. Der s-Parameter darf nicht INVALID_SOCKET oder NULL sein. |
|
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 );
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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für