LPWSPCONNECT-Rückruffunktion (ws2spi.h)

Artikel
08/28/2023

Die LPWSPConnect-Funktion stellt eine Verbindung mit einem Peer her, tauscht Verbindungsdaten aus und gibt die erforderliche Dienstqualität basierend auf der angegebenen Datenflussspezifikation an.

Syntax

LPWSPCONNECT Lpwspconnect;

int Lpwspconnect(
  [in]  SOCKET s,
  [in]  const sockaddr *name,
  [in]  int namelen,
  [in]  LPWSABUF lpCallerData,
  [out] LPWSABUF lpCalleeData,
  [in]  LPQOS lpSQOS,
  [in]  LPQOS lpGQOS,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Deskriptor, der einen nicht verbundenen Socket identifiziert.

[in] name

Name des Peers, mit dem der Socket in der sockaddr verbunden werden soll.

[in] namelen

Länge des Namens in Byte.

[in] lpCallerData

Zeiger auf die Benutzerdaten, die während der Verbindungsherstellung an den Peer übertragen werden sollen.

[out] lpCalleeData

Zeiger auf einen Puffer, in den alle Benutzerdaten kopiert werden können, die während der Verbindungsherstellung vom Peer empfangen wurden.

[in] lpSQOS

Zeiger auf die Datenflussspezifikationen für Sockets, eine für jede Richtung.

[in] lpGQOS

Reserviert.

[out] lpErrno

Zeiger auf den Fehlercode.

Rückgabewert

Wenn kein Fehler auftritt, gibt LPWSPConnect null zurück. Andernfalls wird SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode ist in lpErrno verfügbar.

Bei einem blockierenden Socket gibt der Rückgabewert den Erfolg oder Fehler des Verbindungsversuchs an. Wenn der Rückgabefehlercode angibt, dass der Verbindungsversuch fehlgeschlagen ist (d. h. WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), kann der Winsock SPI-Client LPWSPConnect für denselben Socket erneut aufrufen.

Fehlercode	Bedeutung
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 zum Zeitpunkt der Bindung auf, kann aber bis zu dieser Funktion verzögert werden, wenn die Bindung an eine teilweise Wildcardadresse (mit ADDR_ANY) erfolgte und eine bestimmte Adresse zum Zeitpunkt dieser Funktion committet werden muss.
WSAEINTR	Der (Blockierende) Anruf wurde über LPWSPCancelBlockingCall abgebrochen.
WSAEINPROGRESS	Der Winsock-Aufruf wird blockiert, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion.
WSAEALREADY	Der nicht blockierende LPWSPConnect-Aufruf wird für den angegebenen Socket ausgeführt. Um die Abwärtskompatibilität aufrechtzuerhalten, wird dieser Fehler als WSAEINVAL an Windows Sockets 1.1-Anwendungen gemeldet, die entweder mit Winsock.dll oder Wsock32.dll verknüpft sind.
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	Ein 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	Parameter s ist ein lauschender Socket.
WSAEISCONN	Socket ist bereits verbunden (nur verbindungsorientierte Sockets).
WSAENETUNREACH	Das Netzwerk kann von diesem Host zurzeit nicht erreicht werden.
WSAENOBUFS	Es ist kein Pufferplatz verfügbar. Der Socket kann nicht verbunden werden.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSAEOPNOTSUPP	Die in lpSQOS angegebenen Flussspezifikationen können nicht erfüllt werden.
WSAEPROTONOSUPPORT	LpCallerData augment wird vom Dienstanbieter nicht unterstützt.
WSAETIMEDOUT	Bei einem Verbindungsversuch ist ein Timeout ohne Verbindungsherstellung erfolgt.
WSAEWOULDBLOCK	Socket ist als nicht blockierend gekennzeichnet, und die Verbindung kann nicht sofort hergestellt werden. Es ist möglich, den Socket mit der LPWSPSelect-Funktion auszuwählen, während die Verbindung hergestellt wird, indem die WSPSelect-Funktion verwendet wird, um ihn zum Schreiben auszuwählen.
WSAEACCES	Ein Versuch, datagram socket mit broadcast address zu verbinden, ist fehlgeschlagen, weil WSPSetSockOpt SO_BROADCAST nicht aktiviert ist.

Hinweise

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

Für verbindungsorientierte Sockets (z. B. typisiert SOCK_STREAM) wird eine aktive Verbindung mit dem angegebenen Host mithilfe des Namens (eine Adresse im Namespace des Sockets) initiiert. Eine ausführliche Beschreibung finden Sie unter LPWSPBind. Wenn dieser Aufruf erfolgreich abgeschlossen wurde, ist der Socket bereit, Daten zu senden und zu empfangen. Wenn der Adressmember der Namensstruktur alle Nullen aufweist, gibt LPWSPConnect den Fehler WSAEADDRNOTAVAIL zurück. Jeder Versuch, eine aktive Verbindung wiederherzustellen, schlägt mit dem Fehlercode WSAEISCONN fehl.

Für verbindungsorientierte, nicht blockierende Sockets ist es oft nicht möglich, die Verbindung sofort abzuschließen. In diesem Fall gibt diese Funktion mit dem Fehler WSAEWOULDBLOCK zurück, aber der Vorgang wird 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 LPWSPSelect verwendet, wird der Erfolg in der writefds-Gruppe und fehler in der exceptfds-Gruppe gemeldet. Wenn der Client LPWSPAsyncSelect oder LPWSPEventSelect verwendet, wird die Benachrichtigung mit FD_CONNECT angekündigt, und der dem FD_CONNECT zugeordnete Fehlercode gibt entweder erfolg oder einen bestimmten Fehlergrund an.

Für einen verbindungslosen Socket (z. B. typisiert SOCK_DGRAM) besteht der von LPWSPConnect ausgeführte Vorgang darin, eine Standardzieladresse festzulegen, damit der Socket mit nachfolgenden verbindungsorientierten Sende- und Empfangsvorgängen (LPWSPSend, LPWSPRecv) verwendet werden kann. Alle Datagramme, die von einer anderen Adresse als der angegebenen Zieladresse empfangen werden, werden verworfen. Wenn der Adressmember der Namensstruktur nullen ist, wird der Socket getrennt. Die Standard-Remoteadresse ist unbestimmt, sodass LPWSPSend - und LPWSPRecv-Aufrufe den Fehlercode WSAENOTCONN zurückgeben. LPWSPSendTo und LPWSPRecvFrom können jedoch weiterhin verwendet werden. Das Standardziel kann durch einfaches erneutes Aufrufen von LPWSPConnect geändert werden, 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 LPWSPConnect 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 WSPSetSockOpt SO_BROADCAST aktiviert sein. Andernfalls schlägt LPWSPConnect mit dem Fehlercode WSAEACCES fehl.

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

Der Winsock SPI-Client ist für die Zuweisung von Speicherplatz verantwortlich, auf den durch einen der angegebenen Parameter direkt oder indirekt verwiesen wird.

LpCallerData ist ein Wertparameter, der alle Benutzerdaten enthält, die zusammen mit der Verbindungsanforderung gesendet werden sollen. Wenn lpCallerData NULL ist, werden keine Benutzerdaten an den Peer übergeben. LpCalleeData ist ein Ergebnisparameter, der auf alle Benutzerdaten verweist, die im Rahmen der Verbindungsherstellung vom Peer zurückgegeben werden. Das lpCalleeData-len> enthält anfänglich die Länge des Puffers, der vom Winsock SPI-Client zugewiesen wird und auf denlpCalleeData-buf> verweist. LpCalleeData-len> wird auf null festgelegt, wenn keine Benutzerdaten zurückgegeben wurden. Die lpCalleeData-Informationen sind gültig, wenn der Verbindungsvorgang abgeschlossen ist. Beim Blockieren von Sockets wird dies der Fall sein, wenn die LPWSPConnect-Funktion zurückgegeben wird. Bei Sockets ohne Blockierung erfolgt dies, nachdem die FD_CONNECT Benachrichtigung erfolgt ist. Wenn lpCalleeData NULL ist, werden keine Benutzerdaten zurückgegeben. Das genaue Format der Benutzerdaten ist spezifisch für die Adressfamilie, zu der der Socket gehört und/oder die betreffenden Anwendungen.

Zur Verbindungszeit kann ein Winsock SPI-Client den lpSQOS-Parameter verwenden, um jede vorherige QoS-Spezifikation, die für den Socket über LPWSPIoctl mit dem SIO_SET_QOS Opcode erstellt wurde, außer Kraft zu setzen.

LpSQOS gibt die Datenflussspezifikationen für Sockets an, eine für jede Richtung, gefolgt von zusätzlichen anbieterspezifischen Parametern. Wenn entweder der zugeordnete Transportanbieter im Allgemeinen oder der spezifische Sockettyp im Besonderen die QoS-Anforderung nicht einhalten kann, wird ein Fehler wie unten angegeben zurückgegeben. Die Werte der sendenden oder empfangenden Flowspezifikation werden für alle unidirektionalen Sockets ignoriert. Wenn keine anbieterspezifischen Parameter angegeben werden, sollten die buf- und len-Member von lpSQOS-ProviderSpecific> auf NULL bzw. Null festgelegt werden. Ein NULL-Wert für lpSQOS gibt an, dass keine Anwendung die Dienstqualität bereitgestellt hat.

Hinweis

Wenn verbundene Sockets unterbrochen werden (d. h. aus irgendeinem Grund geschlossen werden), sollten sie verworfen und neu erstellt werden. Es ist am sichersten anzunehmen, dass der Winsock SPI-Client die erforderlichen Sockets verwerfen und neu erstellen muss, um zu einem stabilen Punkt zurückzukehren, wenn dinge aus irgendeinem Grund schief gehen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Kopfzeile	ws2spi.h