WSAConnect-Funktion (winsock2.h)

Die WSAConnect-Funktion stellt eine Verbindung mit einer anderen Socketanwendung her, austauscht Verbindungsdaten 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 Ziel-IPv4-Adresse und den Zielport. Für IPv6 enthält die Sockaddr-StrukturAF_INET6 für die Adressfamilie, die Ziel-IPv6-Adresse, den Zielport und können zusätzliche Fluss- und Bereichs-ID-Informationen enthalten.

[in] namelen

Die Länge der sockaddr-Struktur in Bytes, auf die durch den Namensparameter verwiesen wird.

[in] lpCallerData

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

[out] lpCalleeData

Ein Zeiger auf die Benutzerdaten, die während der Verbindungseinrichtung wieder vom anderen Socket übertragen werden sollen. Siehe Anmerkungen.

[in] lpSQOS

Ein Zeiger auf die QOS-Struktur für Sockets.

[in] lpGQOS

Reserviert für die zukünftige Verwendung mit Socketgruppen. Ein Zeiger auf die QOS-Struktur 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 blockierten Socket kann der Verbindungsversuch nicht sofort abgeschlossen werden. In diesem Fall gibt WSAConnect SOCKET_ERROR zurück, und WSAGetLastError gibt WSAEWOULDBLOCK zurück; der Antrag könnte daher:

• Verwenden Sie select , um den Abschluss der Verbindungsanforderung zu ermitteln, indem Sie überprüfen, ob der Socket schreibbar ist.
• Wenn Ihre Anwendung WSAAsyncSelect verwendet, um Das 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 anzugeben, wird das zugeordnete Ereignisobjekt signalisiert, wenn der Verbindungsvorgang abgeschlossen ist (erfolgreich oder nicht).

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.

Bemerkungen

Die WSAConnect-Funktion wird verwendet, um eine Verbindung mit dem angegebenen Ziel zu erstellen und eine Reihe weiterer zusätzlicher Vorgänge auszuführen, die zur Verbindungszeit auftreten. Wenn der Socket s ungebunden ist, werden eindeutige Werte der lokalen Zuordnung durch das System zugewiesen, und der Socket wird als gebunden markiert.

Für Anwendungen, die auf Windows Vista und höher ausgerichtet sind, sollten Sie die WSAConnectByList oder WSAConnectByName-Funktion verwenden, die das Entwerfen von Clientanwendungen erheblich vereinfacht.

Für verbindungsorientierte Sockets (z. B. typ SOCK_STREAM) wird eine aktive Verbindung mit dem fremden Host mithilfe des Namens initiiert (eine Adresse im Namespace des Sockets; eine ausführliche Beschreibung finden Sie unter bind). Wenn dieser Aufruf erfolgreich abgeschlossen ist, 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.

Bei einem verbindungslosen Socket (z. B. Typ SOCK_DGRAM) besteht der von WSAConnect ausgeführte Vorgang lediglich darin, eine Standardzieladresse einzurichten, sodass der Socket für nachfolgende verbindungsorientierte Sende- und Empfangsvorgänge (Sende-, WSASend-, Recv- und WSARecv) verwendet werden kann. Alle von einer anderen Adresse als der angegebenen Zieladresse empfangenen Datagramme werden verworfen. Wenn die gesamte Namensstruktur alle Nullen (nicht nur der Adressparameter der Namensstruktur) ist, wird der Socket getrennt. Anschließend ist die Standard-Remoteadresse unbestimmt, sodass Sende-, WSASend-, Recv- und WSARecv-Aufrufe den Fehlercode WSAENOTCONN zurückgeben. Sendto, WSASendTo, recvfrom und WSARecvFrom können jedoch weiterhin verwendet werden. Das Standardziel kann durch erneutes Aufrufen von WSAConnect geändert werden, auch wenn der Socket bereits verbunden ist. Alle für den Empfang in die Warteschlange eingereihten Datagramme werden verworfen, wenn sich der Name von der vorherigen WSAConnect unterscheidet.

Bei verbindungslosen Sockets kann der Name eine beliebige gültige Adresse angeben, einschließlich einer Übertragungsadresse. Um jedoch eine Verbindung mit einer Übertragungsadresse herzustellen, muss ein Socket setockopt SO_BROADCAST aktiviert haben. 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 automatisch ignoriert.

Die Anwendung ist dafür verantwortlich, alle Speicherplätze zuzuordnen, auf die 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 (als Verbindungsdaten bezeichnet) gesendet werden sollen. Dies sind zusätzliche Daten, nicht im normalen Netzwerkdatenstrom, die mit Netzwerkanforderungen gesendet werden, um eine Verbindung herzustellen. Diese Option wird von älteren Protokollen wie DECNet, OSI TP4 und anderen verwendet.

Wenn lpCallerDataNULL ist, werden keine Benutzerdaten an den Peer übergeben. " lpCalleeData " ist ein Ergebnisparameter, der alle Benutzerdaten enthält, die vom anderen Socket als Teil der Verbindungseinrichtung in einer WSABUF-Struktur zurückgegeben werden. Das len-Element der WSABUF-Struktur , auf das der lpCalleeData-Parameter verweist, enthält zunächst die Länge des Puffers, der der Anwendung für das buf-Element der WSABUF-Struktur zugeordnet ist. Das len-Element der WSABUF-Struktur , auf das der lpCalleeData-Parameter verweist, wird auf Null festgelegt, wenn keine Benutzerdaten zurückgegeben wurden. Die lpCalleeData-Informationen sind gültig, wenn der Verbindungsvorgang abgeschlossen ist. Zum Blockieren von Sockets wird der Verbindungsvorgang abgeschlossen, wenn die WSAConnect-Funktion zurückgegeben wird. Bei nicht blockierten Sockets wird der Abschluss abgeschlossen, nachdem die FD_CONNECT Benachrichtigung aufgetreten ist. Wenn lpCalleeDataNULL ist, werden keine Benutzerdaten zurückgesendet. 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 zusätzlichen anbieterspezifischen Parametern. Wenn der zugeordnete Transportanbieter im Allgemeinen oder der spezifische Sockettyp insbesondere nicht die Qualität der Serviceanfrage berücksichtigen kann, wird ein Fehler zurückgegeben, wie in der folgenden Abbildung angegeben. Die Sende- oder Empfangsflussspezifikationswerte werden für alle unidirektionalen Sockets ignoriert. Wenn keine anbieterspezifischen Parameter angegeben werden, sollten die buf - und len-Elemente der WSABUF-Struktur , auf die der lpCalleeData-Parameter verweist, auf NULL bzw. Null festgelegt werden. Ein NULL-Wert für den lpSQOS-Parameter gibt keine vom 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 buf - und len-Elemente der WSABUF-Struktur , auf die der lpCalleeData-Parameter verweist, auf NULL bzw. Null festgelegt werden. Ein NULL-Wert für lpGQOS gibt keine vom Anwendung bereitgestellte Gruppenqualitä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 sicher, davon auszugehen, dass die Anwendung die erforderlichen Sockets verwerfen und neu erstellen muss, wenn die Dinge aus irgendeinem Grund in einem verbundenen Socket verwischen und neu erstellen, um zu einem stabilen Punkt zurückzukehren.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Requirements

Siehe auch

WSAAsyncSelect

WSABUF

WSAConnect

ConnectEx

WSAConnectByList

WSAEventSelect

Winsock-Funktionen

Winsock-Referenz

annehmen

binden

connect

getsockname

getsockopt

select

Steckdose