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 mit einem Hostnamen und Port 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--terminated-Zeichenfolge, die den Namen des Hosts oder die IP-Adresse des Hosts enthält, auf dem eine Verbindung für IPv4 oder IPv6 hergestellt werden soll.
[in] servicename
Eine NULL--terminated-Zeichenfolge, die den Dienstnamen oder den Zielport des Hosts enthält, auf dem eine Verbindung für IPv4 oder IPv6 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 wird, sind in der folgenden Datei aufgeführt:
%WINDIR%\system32\drivers\etc\services
[in, out] LocalAddressLength
Bei Eingaben zeigt ein Zeiger auf die Größe des LocalAddress- Puffers, der vom Aufrufer bereitgestellt wird. Bei der Ausgabe zeigt ein Zeiger auf die Größe des SOCKADDR- für die lokale Adresse, die im LocalAddress gespeichert ist, Puffer, der nach erfolgreichem Abschluss des Aufrufs vom System ausgefüllt wurde.
[out] LocalAddress
Ein Zeiger auf die SOCKADDR- Struktur, die die lokale Adresse der Verbindung empfängt. Die Größe des Parameters ist genau die Größe, die in LocalAddressLengthzurückgegeben wird. Dies sind die gleichen Informationen, die von der getockname Funktion zurückgegeben werden. Dieser Parameter kann NULL-werden, in diesem Fall wird der LocalAddressLength-Parameter ignoriert.
[in, out] RemoteAddressLength
Bei Eingaben zeigt ein Zeiger auf die Größe des RemoteAddress- Puffers, der vom Aufrufer bereitgestellt wird. Bei der Ausgabe zeigt ein Zeiger auf die Größe des SOCKADDR- für die Remoteadresse, die in RemoteAddress- Vom System ausgefüllten Puffer nach erfolgreichem Abschluss des Aufrufs gespeichert ist.
[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 werden. Dieser Parameter kann NULL-werden, in diesem Fall wird die RemoteAddressLength- ignoriert.
[in] timeout
Die Zeit in Millisekunden, bis eine Antwort der Remoteanwendung gewartet wird, bevor der Aufruf abgebrochen wird.
Reserved
Reserviert für zukünftige Implementierung. Dieser Parameter muss auf NULL-festgelegt werden.
Rückgabewert
Wenn eine Verbindung hergestellt wird, werden WSAConnectByName-TRUE- und LocalAddress- und Parameter "RemoteAddress" 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. |
|
An die Funktion wurde ein ungültiger Parameter übergeben. Der knotenname oder der servicename Parameter darf nicht NULL-sein. Der Parameter Reserved muss NULL-sein. |
|
Genügend Arbeitsspeicher konnte nicht zugewiesen werden. |
|
An die Funktion wurde ein ungültiger Socket übergeben. Der parameter darf nicht INVALID_SOCKET oder NULL-sein. |
|
Eine Antwort der Remoteanwendung wurde nicht empfangen, bevor der Timeout Parameter überschritten wurde. |
Bemerkungen
WSAConnectByName- wird bereitgestellt, um schnelle und transparente Verbindungen mit Remotehosts für bestimmte Ports zu ermöglichen. Sie ist sowohl mit IPv6- als auch mit IPv4-Versionen kompatibel.
Verwenden Sie die folgende Methode, um die IPv6- und 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 IPV6_V6ONLY Socketoption zu deaktivieren, bevor WSAConnectByNameaufgerufen wird. Dazu rufen Sie die setockopt--Funktion für den Socket auf, wobei der parameter Ebene auf IPPROTO_IPV6 festgelegt ist (siehe IPPROTO_IPV6 Socketoptionen), der optname Parameter, der auf IPV6_V6ONLYfestgelegt ist, und der optvalue Parameterwert auf Null festgelegt ist.
WSAConnectByName- hat Einschränkungen: Es funktioniert nur für verbindungsorientierte Sockets, z. B. für typenbezogene SOCK_STREAM. Die Funktion unterstützt kein überlappende E/A- oder nicht blockierende Verhalten. WSAConnectByName- blockiert, auch wenn sich der Socket im nicht blockierenden Modus befindet.
WSAConnectByName- unterstützt während der Einrichtung einer Verbindung keine vom Benutzer bereitgestellten Daten. Dieser Aufruf unterstützt auch keine FLOWSPEC-Strukturen. In Fällen, in denen diese Features erforderlich sind, müssen WSAConnect- stattdessen verwendet werden.
Wenn eine Anwendung in Versionen vor Windows 10 eine Bindung an eine bestimmte lokale Adresse oder einen bestimmten Port ausführen muss, kann WSAConnectByName nicht verwendet werden, da der Socketparameter zum WSAConnectByName- ein ungebundenes Socket sein muss.
Diese Einschränkung wurde windows 10 entfernt.
Die RemoteAddress- und die parameter LocalAddress verweisen auf eine SOCKADDR--Struktur, bei der es sich um einen generischen Datentyp handelt. Wenn WSAConnectByName- aufgerufen wird, wird erwartet, dass ein für das verwendete Netzwerkprotokoll oder die verwendete Adressfamilie spezifische Socketadressentyp tatsächlich in diesen Parametern übergeben wird. Für IPv4-Adressen würde ein Zeiger auf eine sockaddr_in-Struktur in einen Zeiger in SOCKADDR- als RemoteAddress- und LocalAddress- Parametern umzustellen. Bei IPv6-Adressen würde ein Zeiger auf eine sockaddr_in6-Struktur in einen Zeiger in SOCKADDR- als RemoteAddress- und LocalAddress Parameter umzustellen.
Wenn die
Zum 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 unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.
Beispiele
Herstellen einer Verbindung mit WSAConnectByName-.
#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;
}
}
Anmerkung
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 |
|---|---|
| mindestens unterstützte Client- | Windows 8.1, Windows Vista [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | winsock2.h |
| Library | Ws2_32.lib |
| DLL- | Ws2_32.dll |