LPFN_CONNECTEX Rückruffunktion (mswsock.h)

Artikel
08/25/2023

Die ConnectEx-Funktion stellt eine Verbindung mit einem angegebenen Socket her und sendet optional Daten, sobald die Verbindung hergestellt wurde. Die ConnectEx-Funktion wird nur für verbindungsorientierte Sockets unterstützt.

Hinweis Diese Funktion ist eine Microsoft-spezifische Erweiterung der Windows Sockets-Spezifikation.

Syntax

LPFN_CONNECTEX LpfnConnectex;

BOOL LpfnConnectex(
  [in]           SOCKET s,
  [in]           const sockaddr *name,
  [in]           int namelen,
  [in, optional] PVOID lpSendBuffer,
  [in]           DWORD dwSendDataLength,
  [out]          LPDWORD lpdwBytesSent,
  [in]           LPOVERLAPPED lpOverlapped
)
{...}

Parameter

[in] s

Ein Deskriptor, der einen nicht verbundenen, zuvor gebundenen Socket identifiziert. Weitere Informationen finden Sie unter Hinweise.

[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 IPv6-Fluss- und Bereichs-ID-Informationen enthalten.

[in] namelen

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

[in, optional] lpSendBuffer

Ein Zeiger auf den Puffer, der nach dem Herstellen einer Verbindung übertragen werden soll. Dieser Parameter ist optional. Wenn die Option TCP_FASTOPEN für s aktiviert ist, bevor ConnectEx aufgerufen wird, werden möglicherweise einige dieser Daten während der Verbindungsherstellung gesendet.

[in] dwSendDataLength

Die Länge der Daten in Bytes, auf die der lpSendBuffer-Parameter verweist. Dieser Parameter wird ignoriert, wenn der lpSendBuffer-ParameterNULL ist.

[out] lpdwBytesSent

Bei erfolgreicher Rückgabe zeigt dieser Parameter auf einen DWORD-Wert , der die Anzahl der Bytes angibt, die nach dem Herstellen der Verbindung gesendet wurden. Die gesendeten Bytes stammen aus dem Puffer, auf den der parameter lpSendBuffer verweist. Dieser Parameter wird ignoriert, wenn der lpSendBuffer-ParameterNULL ist.

[in] lpOverlapped

Eine OVERLAPPED-Struktur , die zum Verarbeiten der Anforderung verwendet wird. Der lpOverlapped-Parameter muss angegeben werden und darf nicht NULL sein.

Rückgabewert

Bei Erfolg gibt die ConnectEx-FunktionTRUE zurück. Bei Einem Fehler gibt die Funktion FALSE zurück. Verwenden Sie die WSAGetLastError-Funktion , um erweiterte Fehlerinformationen abzurufen. Wenn ein Aufruf der WSAGetLastError-FunktionERROR_IO_PENDING zurückgibt, wurde der Vorgang erfolgreich initiiert und wird ausgeführt. Unter solchen Umständen kann der Aufruf weiterhin fehlschlagen, wenn der überlappende Vorgang abgeschlossen ist.

Wenn der zurückgegebene Fehlercode WSAECONNREFUSED, WSAENETUNREACH oder WSAETIMEDOUT lautet, kann die Anwendung ConnectEx, WSAConnect aufrufen oder erneut eine Verbindung mit demselben Socket herstellen.

Fehlercode	BESCHREIBUNG
WSANOTINITIALISIERT	Vor der Verwendung von ConnectEx muss ein erfolgreicher WSAStartup-Funktionsaufruf 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 normalerweise während eines Bindungsvorgangs auf, aber der Fehler kann bis zu einem Aufruf der ConnectEx-Funktion verzögert werden, wenn die Bindfunktion mit einer Für die lokale IP-Adresse angegebenen Wildcardadresse (INADDR_ANY oder in6addr_any) aufgerufen wurde. Eine bestimmte IP-Adresse muss implizit durch die ConnectEx-Funktion gebunden werden.
WSAEALREADY	Ein Funktionsaufruf ohne Blockierung,WSAConnect oder ConnectEx wird für den angegebenen Socket ausgeführt.
WSAEADDRNOTAVAIL	Die Remoteadresse ist keine gültige Adresse, z. B. ADDR_ANY (die ConnectEx-Funktion wird nur für verbindungsorientierte Sockets unterstützt).
WSAEAFNOSUPPORT	Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden.
WSAECONNREFUSED	Der Versuch, eine Verbindung herzustellen, wurde abgelehnt.
WSAEFAULT	Der Parameter name, lpSendBuffer oder lpOverlapped ist kein gültiger Teil des Benutzeradressraums oder namelen ist zu klein.
WSAEINVAL	Der Parameter s ist ein ungebundener oder ein lauschender Socket.
WSAEISCONN	Der Socket ist bereits verbunden.
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 Pufferspeicher verfügbar. der Socket kann nicht verbunden werden.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSAETIMEDOUT	Der Versuch, eine Verbindung herzustellen, hat ein Timeout ohne Herstellung einer Verbindung.

Hinweise

Die ConnectEx-Funktion kombiniert mehrere Socketfunktionen in einem einzelnen API-/Kernelübergang. Die folgenden Vorgänge werden ausgeführt, wenn ein Aufruf der ConnectEx-Funktion erfolgreich abgeschlossen wurde:

Eine neue Verbindung wird hergestellt.
Nach dem Herstellen der Verbindung wird ein optionaler Datenblock gesendet.

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.

Die ConnectEx-Funktion kann nur mit verbindungsorientierten Sockets verwendet werden. Der im s-Parameter übergebene Socket muss mit dem Sockettyp SOCK_STREAM, SOCK_RDM oder SOCK_SEQPACKET erstellt werden.

Der parameter lpSendBuffer verweist auf einen Datenpuffer, der nach dem Herstellen der Verbindung gesendet werden soll. Der dwSendDataLength-Parameter gibt die Länge dieser zu sendenden Daten in Bytes an. Eine Anwendung kann anfordern, einen großen Puffer von Daten mithilfe von ConnectEx auf die gleiche Weise zu senden, wie die Funktionen send und WSASend verwendet werden können. Entwicklern wird jedoch dringend davon abgeraten, einen riesigen Puffer in einem einzelnen Aufruf mithilfe von ConnectEx zu senden, da bei diesem Vorgang eine große Menge an Systemspeicherressourcen verwendet werden, bis der gesamte Puffer gesendet wurde.

Wenn die ConnectEx-Funktion erfolgreich war, wurde eine Verbindung hergestellt, und alle Daten, auf die der lpSendBuffer-Parameter verweist, wurden an die Adresse gesendet, die in der sockaddr-Struktur angegeben ist, auf die der name-Parameter verweist.

Hinweis Der Funktionszeiger für die ConnectEx-Funktion muss zur Laufzeit abgerufen werden, indem die WSAIoctl-Funktion mit dem angegebenen SIO_GET_EXTENSION_FUNCTION_POINTER Opcode aufgerufen wird. Der an die WSAIoctl-Funktion übergebene Eingabepuffer muss WSAID_CONNECTEX enthalten, einen global eindeutigen Bezeichner (GUID), dessen Wert die ConnectEx-Erweiterungsfunktion identifiziert. Bei Erfolg enthält die von der WSAIoctl-Funktion zurückgegebene Ausgabe einen Zeiger auf die ConnectEx-Funktion . Die WSAID_CONNECTEX GUID ist in der Headerdatei Mswsock.h definiert.

Die ConnectEx-Funktion verwendet überlappende E/A. Daher ermöglicht die ConnectEx-Funktion einer Anwendung, eine große Anzahl von Clients mit relativ wenigen Threads zu bedienen. Im Gegensatz dazu erfordert die WSAConnect-Funktion , die keine überlappenden E/A-Vorgänge verwendet, in der Regel einen separaten Thread, um jede Verbindungsanforderung zu verarbeiten, wenn gleichzeitige Anforderungen empfangen werden.

Hinweis Alle von einem bestimmten Thread initiierten E/A-Vorgänge werden abgebrochen, wenn dieser Thread beendet wird. Bei überlappenden Sockets können ausstehende asynchrone Vorgänge fehlschlagen, wenn der Thread geschlossen wird, bevor die Vorgänge abgeschlossen sind. Weitere Informationen finden Sie unter ExitThread .

Verbindungsorientierte Sockets können ihre Verbindung häufig nicht sofort abschließen, weshalb der Vorgang initiiert wird und die Funktion sofort mit dem ERROR_IO_PENDING oder WSA_IO_PENDING Fehler zurückgibt. Wenn der Verbindungsvorgang abgeschlossen ist und ein Erfolg oder Fehler erzielt wird, wird status mithilfe des in lpOverlapped angegebenen Vervollständigungsbenachrichtigungsmechanismus gemeldet. Wie bei allen überlappenden Funktionsaufrufen können Sie Ereignisse oder Abschlussports als Vervollständigungsbenachrichtigungsmechanismus verwenden. Der lpNumberOfBytesTransferred-Parameter der GetQueuedCompletionStatus- oder GetOverlappedResult- oder WSAGetOverlappedResult-Funktion gibt die Anzahl der in der Anforderung gesendeten Bytes an.

Wenn die ConnectEx-Funktion erfolgreich abgeschlossen wurde, können Sockethandles s nur an die folgenden Funktionen übergeben werden:

Wenn die TransmitFile-Funktion auf einem zuvor verbundenen Socket mit TF_DISCONNECT- und TF_REUSE_SOCKET-Flags aufgerufen wird, wird der angegebene Socket in einen Zustand zurückgegeben, in dem er nicht verbunden, aber weiterhin gebunden ist. In solchen Fällen kann das Handle des Sockets an die ConnectEx-Funktion im s-Parameter übergeben werden, aber der Socket kann nicht in einem AcceptEx-Funktionsaufruf wiederverwendet werden. Ebenso kann der akzeptierte Socket, der mithilfe der TransmitFile-Funktion wiederverwendet wird, nicht in einem Aufruf von ConnectEx verwendet werden. Beachten Sie, dass connectEx im Fall eines wiederverwendeten Sockets dem Verhalten des zugrunde liegenden Transports unterliegt. Beispielsweise kann ein TCP-Socket dem TCP-TIME_WAIT Zustand unterliegen, was dazu führt, dass der ConnectEx-Aufruf verzögert wird.

Wenn die ConnectEx-FunktionTRUE zurückgibt, befindet sich der Socket s im Standardzustand für einen verbundenen Socket. Der Socket s aktiviert zuvor festgelegte Eigenschaften oder Optionen erst, wenn SO_UPDATE_CONNECT_CONTEXT für den Socket festgelegt ist. 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 );

Die getockopt-Funktion kann mit der Option SO_CONNECT_TIME Socket verwendet werden, um zu überprüfen, ob eine Verbindung hergestellt wurde, während ConnectEx ausgeführt wird. Wenn eine Verbindung hergestellt wurde, ist der wert, der im optval-Parameter zurückgegeben wird, der an die getockopt-Funktion übergeben wird, die Anzahl der Sekunden, die der Socket verbunden hat. Wenn der Socket nicht verbunden ist, enthält der zurückgegebene optval-Parameter 0xFFFFFFFF. Die Überprüfung einer Verbindung auf diese Weise ist erforderlich, um festzustellen, ob Verbindungen für einen bestimmten Zeitraum hergestellt wurden, ohne Daten zu senden; in solchen Fällen wird empfohlen, diese Verbindungen zu beenden.

Beispiel:


//Need to #include <mswsock.h> for SO_CONNECT_TIME

int seconds;
int bytes = sizeof(seconds);
int iResult = 0;

iResult = getsockopt( s, SOL_SOCKET, SO_CONNECT_TIME,
                      (char *)&seconds, (PINT)&bytes );
if ( iResult != NO_ERROR ) {
    printf( "getsockopt(SO_CONNECT_TIME) failed with error: %u\n", 
        WSAGetLastError() );
}
else {
    if (seconds == 0xFFFFFFFF)
        printf("Connection not established yet\n");
    else
       printf("Connection has been established %ld seconds\n",
           seconds);
}

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

Wenn der Adressparameter der sockaddr-Struktur , auf die im name-Parameter verwiesen wird, alle Nullen aufweist, gibt ConnectEx den Fehler WSAEADDRNOTAVAIL zurück. Jeder Versuch, eine aktive Verbindung wiederherzustellen, schlägt mit dem Fehlercode WSAEISCONN fehl.

Wenn ein verbundener Socket aus irgendeinem Grund geschlossen wird, wird empfohlen, den Socket zu verwerfen und ein neues Socket zu erstellen. Der Grund hierfür ist, dass es am sichersten ist, davon auszugehen, dass die Anwendung den Socket verwerfen und den erforderlichen Socket erneut erstellen muss, um zu einem stabilen Punkt zurückzukehren, wenn die Dinge an einem verbundenen Socket aus irgendeinem Grund schief gehen.

Wenn die DisconnectEx-Funktion mit dem Flag TF_REUSE_SOCKET aufgerufen wird, wird der angegebene Socket in einen Zustand zurückgegeben, in dem er nicht verbunden, aber weiterhin gebunden ist. In solchen Fällen kann das Handle des Sockets an die ConnectEx-Funktion im s-Parameter übergeben werden.

Das Zeitintervall, das verstreichen muss, bevor TCP eine geschlossene Verbindung freigeben und seine Ressourcen wiederverwenden kann, wird als TIME_WAIT Zustand oder 2MSL-Zustand bezeichnet. Während dieser Zeit kann die Verbindung zu wesentlich geringeren Kosten für den Client und server wieder geöffnet werden als das Herstellen einer neuen Verbindung.

Das TIME_WAIT Verhalten wird in RFC 793 angegeben, was erfordert, dass TCP eine geschlossene Verbindung für ein Intervall unterhält, das mindestens dem Doppelten der maximalen Segmentlebensdauer (MSL) des Netzwerks entspricht. Wenn eine Verbindung freigegeben wird, können das Socketpaar und die internen Ressourcen, die für den Socket verwendet werden, verwendet werden, um eine andere Verbindung zu unterstützen.

Windows TCP wird nach dem Schließen einer Verbindung in einen TIME_WAIT Zustand zurückgesetzt. Im TIME_WAIT Zustand kann ein Socketpaar nicht wiederverwendet werden. Der TIME_WAIT Zeitraums kann durch Ändern der folgenden DWORD-Registrierungseinstellung konfiguriert werden, die den TIME_WAIT Zeitraums in Sekunden darstellt.

HKEY_LOCAL_MACHINE\System\Currentcontrolset\Dienstleistungen\TCPIP\Parameter\Tcptimedwaitdelay

Standardmäßig ist die MSL auf 120 Sekunden definiert. Die TcpTimedWaitDelay-Registrierungseinstellung ist standardmäßig auf einen Wert von 240 Sekunden festgelegt, der das 2-Fache der maximalen Segmentlebensdauer von 120 Sekunden oder 4 Minuten darstellt. Sie können diesen Eintrag jedoch verwenden, um das Intervall anzupassen.

Wenn Sie den Wert dieses Eintrags reduzieren, kann TCP geschlossene Verbindungen schneller freigeben und mehr Ressourcen für neue Verbindungen bereitstellen. Wenn der Wert jedoch zu niedrig ist, gibt TCP möglicherweise Verbindungsressourcen frei, bevor die Verbindung abgeschlossen ist, sodass der Server zusätzliche Ressourcen zum erneuten Herstellen der Verbindung verwenden muss.

Diese Registrierungseinstellung kann zwischen 0 und 300 Sekunden festgelegt 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	mswsock.h