WSAConnect-Funktion (winsock2.h)

Artikel
03/06/2024

Die WSAConnect-Funktion stellt eine Verbindung mit einer anderen Socketanwendung her, tauscht Verbindungsdaten aus und gibt die erforderliche Dienstqualität basierend auf der angegebenen FLOWSPEC-Struktur an.

Syntax

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

Parameter

[in] s

Ein Deskriptor, der einen nicht verbundenen Socket identifiziert.

[in] name

Ein Zeiger auf eine sockaddr-Struktur , die die Adresse angibt, mit der eine Verbindung hergestellt werden soll. Für IPv4 enthält der sockaddrAF_INET für die Adressfamilie, die IPv4-Zieladresse und den Zielport. Für IPv6 enthält die sockaddr-StrukturAF_INET6 für die Adressfamilie, die IPv6-Zieladresse, den Zielport und kann zusätzliche Informationen zu Flow und Bereichs-ID enthalten.

[in] namelen

Die Länge der sockaddr-Struktur in Bytes, auf die der name-Parameter verweist.

[in] lpCallerData

Ein Zeiger auf die Benutzerdaten, die während der Verbindungsherstellung an den anderen Socket übertragen werden sollen. Siehe Hinweise.

[out] lpCalleeData

Ein Zeiger auf die Benutzerdaten, die während des Verbindungsaufbaus vom anderen Socket zurück übertragen werden sollen. Siehe Hinweise.

[in] lpSQOS

Ein Zeiger auf die FLOWSPEC-Strukturen für Sockets, eine für jede Richtung.

[in] lpGQOS

Reserviert für die zukünftige Verwendung mit Socketgruppen. Ein Zeiger auf die FLOWSPEC-Strukturen für die Socketgruppe (falls zutreffend). Dieser Parameter sollte NULL sein.

Rückgabewert

Wenn kein Fehler auftritt, gibt WSAConnect null zurück. Andernfalls wird SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden. Bei einem blockierenden Socket gibt der Rückgabewert den Erfolg oder Fehler des Verbindungsversuchs an.

Bei einem nicht blockierenden Socket kann der Verbindungsversuch nicht sofort abgeschlossen werden. In diesem Fall gibt WSAConnect SOCKET_ERROR und WSAGetLastError WSAEWOULDBLOCK zurück. der Antrag könnte daher:

Verwenden Sie select , um den Abschluss der Verbindungsanforderung zu bestimmen, indem Sie überprüfen, ob der Socket schreibbar ist.
Wenn Ihre Anwendung WSAAsyncSelect verwendet, um Interesse an Verbindungsereignissen anzuzeigen, erhält Ihre Anwendung eine FD_CONNECT Benachrichtigung, wenn der Verbindungsvorgang abgeschlossen ist (erfolgreich oder nicht).
Wenn Ihre Anwendung WSAEventSelect verwendet, um Interesse an Verbindungsereignissen anzuzeigen, wird das zugeordnete Ereignisobjekt signalisiert, wenn der Verbindungsvorgang abgeschlossen ist (erfolgreich oder nicht).

Bei einem Nichtblockierungssocket schlägt der Fehlercode WSAEALREADY fehl, bis der Verbindungsversuch alle nachfolgenden Aufrufe von WSAConnect auf demselben Socket abgeschlossen hat.

Wenn der Rückgabefehlercode angibt, dass der Verbindungsversuch fehlgeschlagen ist (d. h. WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), kann die Anwendung WSAConnect erneut für denselben Socket aufrufen.

Fehlercode	Bedeutung
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAEADDRINUSE	Die lokale Adresse des Sockets wird bereits verwendet, und der Socket wurde nicht markiert, um die Wiederverwendung von Adressen mit SO_REUSEADDR zu ermöglichen. Dieser Fehler tritt in der Regel während der Ausführung von bind auf, kann jedoch bis zu dieser Funktion verzögert werden, wenn die Bindfunktion mit einer teilweise wildcard-Adresse (mit ADDR_ANY) arbeitet und wenn eine bestimmte Adresse zum Zeitpunkt dieser Funktion "committet" werden muss.
WSAEINTR	Der (blockierende) Windows Socket 1.1-Aufruf wurde über WSACancelBlockingCall abgebrochen.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion.
WSAEALREADY	Eine nicht blockierende Verbindung oder ein WSAConnect-Aufruf wird für den angegebenen Socket ausgeführt.
WSAEADDRNOTAVAIL	Die Remoteadresse ist keine gültige Adresse (z. B. ADDR_ANY).
WSAEAFNOSUPPORT	Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden.
WSAECONNREFUSED	Der Versuch, eine Verbindung herzustellen, wurde abgelehnt.
WSAEFAULT	Der Name oder der Namelen-Parameter ist kein gültiger Teil des Benutzeradressraums, der namelen-Parameter ist zu klein, die Pufferlänge für lpCalleeData, lpSQOS und lpGQOS ist zu klein, oder die Pufferlänge für lpCallerData ist zu groß.
WSAEINVAL	Der Parameter s ist ein Überwachungssocket, oder die angegebene Zieladresse ist nicht mit der der eingeschränkten Gruppe konsistent, zu der der Socket gehört, oder der lpGQOS-Parameter ist nicht NULL.
WSAEISCONN	Der Socket ist bereits verbunden (nur verbindungsorientierte Sockets).
WSAENETUNREACH	Das Netzwerk kann von diesem Host zurzeit nicht erreicht werden.
WSAEHOSTUNREACH	Versuch eines Socketvorgangs für einen nicht erreichbaren Host.
WSAENOBUFS	Es ist kein Pufferplatz verfügbar. Der Socket kann nicht verbunden werden.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSAEOPNOTSUPP	Die in lpSQOS und lpGQOS angegebenen FLOWSPEC-Strukturen können nicht erfüllt werden.
WSAEPROTONOSUPPORT	Der lpCallerData-Parameter wird vom Dienstanbieter nicht unterstützt.
WSAETIMEDOUT	Zeitüberschreitung beim Verbindungsversuch, ohne eine Verbindung herzustellen.
WSAEWOULDBLOCK	Der Socket ist als nicht blockierend gekennzeichnet, und die Verbindung kann nicht sofort hergestellt werden.
WSAEACCES	Der Versuch, den Datagrammsocket mit der Broadcastadresse zu verbinden, ist fehlgeschlagen, weil setsockopt SO_BROADCAST nicht aktiviert ist.

Hinweise

Die WSAConnect-Funktion wird verwendet, um eine Verbindung mit dem angegebenen Ziel herzustellen und eine Reihe weiterer Hilfsvorgänge auszuführen, die zum Zeitpunkt der Verbindung auftreten. Wenn der Socket s ungebunden ist, werden der lokalen Zuordnung vom System eindeutige Werte zugewiesen, und der Socket wird als gebunden markiert.

Erwägen Sie für Anwendungen, die auf Windows Vista und höher ausgerichtet sind, die Verwendung der Funktion WSAConnectByList oder WSAConnectByName , die den Entwurf von Clientanwendungen erheblich vereinfacht.

Für verbindungsorientierte Sockets (z. B. Typ SOCK_STREAM) wird eine aktive Verbindung mit dem fremden Host unter Verwendung des Namens (eine Adresse im Namespace des Sockets; eine ausführliche Beschreibung finden Sie unter bind) initiiert. Wenn dieser Aufruf erfolgreich abgeschlossen wurde, kann der Socket Daten senden/empfangen. Wenn der Adressparameter der Namensstruktur alle Nullen ist, gibt WSAConnect den Fehler WSAEADDRNOTAVAIL zurück. Jeder Versuch, eine aktive Verbindung wiederherzustellen, schlägt mit dem Fehlercode WSAEISCONN fehl.

Hinweis Wenn ein Socket geöffnet wird, wird ein setsockopt-Aufruf ausgeführt, und dann wird ein sendto-Aufruf ausgeführt, Windows Sockets führt einen impliziten Bindungsfunktionsaufruf aus.

Bei verbindungsorientierten, nicht blockierenden Sockets ist es oft nicht möglich, die Verbindung sofort abzuschließen. In solchen Fällen gibt diese Funktion den Fehler WSAEWOULDBLOCK zurück. Der Vorgang wird jedoch fortgesetzt. Wenn das Erfolgs- oder Fehlerergebnis bekannt wird, kann es auf eine von mehreren Arten gemeldet werden, je nachdem, wie sich der Client für die Benachrichtigung registriert. Wenn der Client select verwendet, wird der Erfolg in der writefds-Gruppe und fehler in der exceptfds-Gruppe gemeldet. Wenn der Client WSAAsyncSelect oder WSAEventSelect verwendet, wird die Benachrichtigung mit FD_CONNECT angekündigt, und der Fehlercode, der dem FD_CONNECT zugeordnet ist, gibt entweder erfolg oder einen bestimmten Fehlergrund an.

Für einen verbindungslosen Socket (z. B. Typ SOCK_DGRAM) besteht der von WSAConnect ausgeführte Vorgang lediglich darin, eine Standardzieladresse festzulegen, damit der Socket für nachfolgende verbindungsorientierte Sende- und Empfangsvorgänge (Send, WSASend, recv und WSARecv) verwendet werden kann. Alle Datagramme, die von einer anderen Adresse als der angegebenen Zieladresse empfangen werden, werden verworfen. Wenn die gesamte Namensstruktur alle Nullen (nicht nur der Adressparameter der Namensstruktur) ist, wird der Socket getrennt. Dann ist die Standard-Remoteadresse unbestimmt, sodass send, WSASend, recv und WSARecv-Aufrufe den Fehlercode WSAENOTCONN zurückgeben. Sendto, WSASendTo, recvfrom und WSARecvFrom können jedoch weiterhin verwendet werden. Das Standardziel kann geändert werden, indem WSAConnect einfach erneut aufgerufen wird, auch wenn der Socket bereits verbunden ist. Alle Datagramme, die für den Empfang in die Warteschlange eingereiht wurden, werden verworfen, wenn sich der Name vom vorherigen WSAConnect-Objekt unterscheidet.

Bei verbindungslosen Sockets kann der Name eine beliebige gültige Adresse angeben, einschließlich einer Broadcastadresse. Um jedoch eine Verbindung mit einer Broadcastadresse herzustellen, muss für einen Socket setockopt SO_BROADCAST aktiviert sein. Andernfalls schlägt WSAConnect mit dem Fehlercode WSAEACCES fehl.

Bei verbindungslosen Sockets ist der Austausch von Benutzer-zu-Benutzer-Daten nicht möglich, und die entsprechenden Parameter werden unbeaufsichtigt ignoriert.

Die Anwendung ist für die Zuweisung von Speicherplatz verantwortlich, auf den direkt oder indirekt durch einen der von ihr angegebenen Parameter verwiesen wird.

Der lpCallerData-Parameter enthält einen Zeiger auf alle Benutzerdaten, die zusammen mit der Verbindungsanforderung (so genannte Verbindungsdaten) gesendet werden sollen. Dies sind zusätzliche Daten, nicht im normalen Netzwerkdatenstrom, die mit Netzwerkanforderungen zum Herstellen einer Verbindung gesendet werden. Diese Option wird von Legacyprotokollen wie DECNet, OSI TP4 und anderen verwendet.

Hinweis Verbindungsdaten werden vom TCP/IP-Protokoll in Windows nicht unterstützt. Verbindungsdaten werden nur am ATM (RAWWAN) über einen unformatierten Socket unterstützt.

Wenn lpCallerDataNULL ist, werden keine Benutzerdaten an den Peer übergeben. LpCalleeData ist ein Ergebnisparameter, der alle Benutzerdaten enthält, die im Rahmen der Verbindungsherstellung in einer WSABUF-Struktur vom anderen Socket zurückgegeben werden. Das len-Element der WSABUF-Struktur , auf die der lpCalleeData-Parameter verweist, enthält zunächst die Länge des Puffers, der von der Anwendung für das buf-Element der WSABUF-Struktur zugewiesen wird. Das len-Element der WSABUF-Struktur , auf das vom lpCalleeData-Parameter verwiesen wird, wird auf 0 festgelegt, wenn keine Benutzerdaten zurückgegeben wurden. Die lpCalleeData-Informationen sind gültig, wenn der Verbindungsvorgang abgeschlossen ist. Beim Blockieren von Sockets wird der Verbindungsvorgang abgeschlossen, wenn die WSAConnect-Funktion zurückgegeben wird. Bei nicht blockierenden Sockets erfolgt die Vervollständigung, nachdem die FD_CONNECT Benachrichtigung aufgetreten ist. Wenn lpCalleeDataNULL ist, werden keine Benutzerdaten zurückgegeben. Das genaue Format der Benutzerdaten ist spezifisch für die Adressfamilie, zu der der Socket gehört.

Zur Verbindungszeit kann eine Anwendung den lpSQOS - und lpGQOS-Parameter verwenden, um alle vorherigen Qualitätsspezifikationen für den Socket über WSAIoctl mit dem SIO_SET_QOS oder SIO_SET_GROUP_QOS Opcode außer Kraft zu setzen.

Der lpSQOS-Parameter gibt die FLOWSPEC-Strukturen für Sockets an, eine für jede Richtung, gefolgt von allen zusätzlichen anbieterspezifischen Parametern. Wenn entweder der zugeordnete Transportanbieter im Allgemeinen oder der spezifische Sockettyp im Besonderen die Qualitätsanforderung des Diensts nicht berücksichtigen kann, wird ein Fehler zurückgegeben, wie im Folgenden angegeben. Die Werte der sendenden oder empfangenden Flowspezifikation werden für alle unidirektionalen Sockets ignoriert. Wenn keine anbieterspezifischen Parameter angegeben werden, sollten die Elemente buf und len der WSABUF-Struktur , auf die vom lpCalleeData-Parameter verwiesen wird, auf NULL bzw. null festgelegt werden. Ein NULL-Wert für den lpSQOS-Parameter gibt keine von der Anwendung bereitgestellte Dienstqualität an.

Reserviert für die zukünftige Verwendung mit Socketgruppen lpGQOS gibt die FLOWSPEC-Strukturen für die Socketgruppe an (falls zutreffend), eine für jede Richtung, gefolgt von zusätzlichen anbieterspezifischen Parametern. Wenn keine anbieterspezifischen Parameter angegeben werden, sollten die Elemente buf und len der WSABUF-Struktur , auf die vom lpCalleeData-Parameter verwiesen wird, auf NULL bzw. null festgelegt werden. Ein NULL-Wert für lpGQOS gibt keine von der Anwendung bereitgestellte Dienstqualität an. Dieser Parameter wird ignoriert, wenn s nicht der Ersteller der Socketgruppe ist.

Wenn verbundene Sockets aus irgendeinem Grund geschlossen werden, sollten sie verworfen und neu erstellt werden. Es ist am sichersten davon auszugehen, dass die Anwendung die erforderlichen Sockets verwerfen und neu erstellen muss, um zu einem stabilen Punkt zurückzukehren, wenn dinge aus irgendeinem Grund schief gehen.

Hinweis Wenn Sie einen blockierenden Winsock-Aufruf wie WSAConnect ausgeben, muss Winsock möglicherweise auf ein Netzwerkereignis warten, bevor der Anruf 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.

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.

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	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll