Funzione di callback LPWSPCONNECT (ws2spi.h)

Articolo
03/04/2024

La funzione LPWSPConnect stabilisce una connessione a un peer, scambia i dati di connessione e specifica la qualità del servizio necessaria in base alla specifica del flusso fornita.

Sintassi

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
)
{...}

Parametri

[in] s

Descrittore che identifica un socket non connesso.

[in] name

Nome del peer a cui deve essere connesso il socket nel sockaddr .

[in] namelen

Lunghezza del nome, in byte.

[in] lpCallerData

Puntatore ai dati utente da trasferire al peer durante la creazione della connessione.

[out] lpCalleeData

Puntatore a un buffer in cui è possibile copiare tutti i dati utente ricevuti dal peer durante la creazione della connessione.

[in] lpSQOS

Puntatore alle specifiche del flusso per socket s, una per ogni direzione.

[in] lpGQOS

Riservato.

[out] lpErrno

Puntatore al codice di errore.

Valore restituito

Se non si verifica alcun errore, LPWSPConnect restituisce zero. In caso contrario, restituisce SOCKET_ERROR e un codice di errore specifico è disponibile in lpErrno.

In un socket di blocco, il valore restituito indica l'esito positivo o negativo del tentativo di connessione. Se il codice di errore restituito indica che il tentativo di connessione non è riuscito, ovvero WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT, il client WINSock SPI può chiamare nuovamente LPWSPConnect per lo stesso socket.

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEADDRINUSE	L'indirizzo locale del socket è già in uso e il socket non è stato contrassegnato per consentire il riutilizzo degli indirizzi con SO_REUSEADDR. Questo errore si verifica in genere al momento dell'associazione, ma potrebbe essere ritardato fino a quando questa funzione non è stata associata a un indirizzo con caratteri jolly parzialmente (che coinvolgono ADDR_ANY) e se è necessario eseguire il commit di un indirizzo specifico al momento di questa funzione.
WSAEINTR	(Blocking) la chiamata è stata annullata tramite LPWSPCancelBlockingCall.
WSAEINPROGRESS	Il blocco della chiamata Winsock è in corso o il provider di servizi sta ancora elaborando una funzione di callback.
WSAEALREADY	La chiamata LPWSPConnect non bloccante è in corso sul socket specificato. Per mantenere la compatibilità con le versioni precedenti, questo errore viene segnalato come WSAEINVAL alle applicazioni Windows Sockets 1.1 che si collegano a Winsock.dll o Wsock32.dll.
WSAEADDRNOTAVAIL	L'indirizzo remoto non è un indirizzo valido, ad esempio ADDR_ANY.
WSAEAFNOSUPPORT	Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket.
WSAECONNREFUSED	È stato rifiutato un tentativo di connessione.
WSAEFAULT	Il nome o il parametro namelen non è una parte valida dello spazio indirizzi utente, il parametro namelen è troppo piccolo, la lunghezza del buffer per lpCalleeData, lpSQOS e lpGQOS è troppo piccola o la lunghezza del buffer per lpCallerData è troppo grande.
WSAEINVAL	Il parametro s è un socket di ascolto.
WSAEISCONN	Il socket è già connesso (solo socket orientati alla connessione).
WSAENETUNREACH	Impossibile raggiungere la rete da questo host in questo momento.
WSAENOBUFS	Nessuno spazio di buffer disponibile. Il socket non può essere connesso.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	Le specifiche del flusso specificate in lpSQOS non possono essere soddisfatte.
WSAEPROTONOSUPPORT	L'aumento lpCallerData non è supportato dal provider di servizi.
WSAETIMEDOUT	Tentativo di connessione timeout senza stabilire una connessione.
WSAEWOULDBLOCK	Il socket è contrassegnato come non bloccante e la connessione non può essere completata immediatamente. È possibile selezionare il socket usando la funzione LPWSPSelect durante la connessione tramite la funzione WSPSelect per selezionarla per la scrittura.
WSAEACCES	Tentativo di connessione del socket del datagram all'indirizzo broadcast non riuscito perché WSPSetSockOpt SO_BROADCAST non è abilitato.

Commenti

Questa funzione viene usata per creare una connessione alla destinazione specificata e per eseguire anche diverse altre operazioni ausiliarie che si verificano al momento della connessione. Se il socket, s, non è associato, i valori univoci vengono assegnati all'associazione locale dal sistema e il socket viene contrassegnato come associato.

Per i socket orientati alla connessione (ad esempio, digitare SOCK_STREAM), viene avviata una connessione attiva all'host specificato usando il nome (un indirizzo nello spazio dei nomi del socket. Per una descrizione dettagliata, vedere LPWSPBind. Al termine della chiamata, il socket è pronto per l'invio e la ricezione dei dati. Se il membro dell'indirizzo della struttura del nome è tutti zeri, LPWSPConnect restituirà l'errore WSAEADDRNOTAVAIL. Qualsiasi tentativo di riconnessione di una connessione attiva avrà esito negativo con il codice di errore WSAEISCONN.

Per i socket non bloccanti orientati alla connessione, spesso non è possibile completare immediatamente la connessione. In questo caso, questa funzione restituisce con l'errore WSAEWOULDBLOCK , ma l'operazione continua. Quando il risultato dell'esito positivo o negativo diventa noto, può essere segnalato in uno dei diversi modi a seconda del modo in cui il client esegue la registrazione per la notifica. Se il client usa LPWSPSelect, l'esito positivo viene segnalato nel set writefds e l'errore viene segnalato nel set exceptfds . Se il client usa LPWSPAsyncSelect o LPWSPEventSelect, la notifica viene annunciata con FD_CONNECT e il codice di errore associato al FD_CONNECT indica l'esito positivo o un motivo specifico per l'errore.

Per un socket senza connessione (ad esempio, digitare SOCK_DGRAM), l'operazione eseguita da LPWSPConnect consiste nel stabilire un indirizzo di destinazione predefinito in modo che il socket possa essere usato con le successive operazioni di invio e ricezione orientate alla connessione (LPWSPSend, LPWSPRecv). Gli eventuali datagrammi ricevuti da un indirizzo diverso dall'indirizzo di destinazione specificato verranno eliminati. Se il membro dell'indirizzo della struttura del nome è tutti zeri, il socket verrà disconnesso. L'indirizzo remoto predefinito sarà indeterminato, quindi le chiamate LPWSPSend e LPWSPRecv restituiranno il codice di errore WSAENOTCONN. Tuttavia, è comunque possibile usare LPWSPSendTo e LPWSPRecvFrom . La destinazione predefinita può essere modificata semplicemente chiamando di nuovo LPWSPConnect , anche se il socket è già connesso. Gli eventuali datagrammi accodati per la ricevuta vengono eliminati se il nome è diverso dal precedente LPWSPConnect.

Per i socket senza connessione, il nome può indicare qualsiasi indirizzo valido, incluso un indirizzo broadcast. Tuttavia, per connettersi a un indirizzo broadcast, un socket deve avere WSPSetSockOpt SO_BROADCAST abilitato. In caso contrario, LPWSPConnect avrà esito negativo con il codice di errore WSAEACCES.

Nei socket senza connessione, lo scambio di dati da utente a utente non è possibile e i parametri corrispondenti verranno ignorati automaticamente.

Il client WINSock SPI è responsabile dell'allocazione di qualsiasi spazio di memoria a cui punta direttamente o indirettamente da uno qualsiasi dei parametri specificati.

lpCallerData è un parametro di valore che contiene i dati utente da inviare insieme alla richiesta di connessione. Se lpCallerData è null, al peer non verranno passati dati utente. LpCalleeData è un parametro di risultato che farà riferimento a tutti i dati utente passati dal peer come parte della creazione della connessione. LpCalleeData-len> contiene inizialmente la lunghezza del buffer allocata dal client SPI Winsock e punta a lpCalleeData-buf.> LpCalleeData-len> verrà impostato su zero se non sono stati restituiti dati utente. Le informazioni lpCalleeData saranno valide al termine dell'operazione di connessione. Per i socket di blocco, si verifica quando viene restituita la funzione LPWSPConnect . Per i socket non bloccanti, questa operazione verrà eseguita dopo che si è verificata la notifica FD_CONNECT. Se lpCalleeData è null, non verranno restituiti dati utente. Il formato esatto dei dati utente è specifico della famiglia di indirizzi a cui appartiene il socket e/o alle applicazioni coinvolte.

Al momento della connessione, un client SPI Winsock può usare il parametro lpSQOS per eseguire l'override di qualsiasi specifica QoS precedente eseguita per il socket tramite LPWSPIoctl con il codice operativo SIO_SET_QOS.

LpSQOS specifica le specifiche del flusso per socket s, una per ogni direzione, seguita da eventuali parametri aggiuntivi specifici del provider. Se il provider di trasporto associato in generale o il tipo specifico di socket in particolare non può rispettare la richiesta QoS, verrà restituito un errore come indicato di seguito. I valori di specifica del flusso di invio o ricezione verranno ignorati, rispettivamente, per qualsiasi socket unidirezionale. Se non vengono forniti parametri specifici del provider, i membri buf e len di lpSQOS-ProviderSpecific> devono essere impostati rispettivamente su null e zero. Un valore Null per lpSQOS indica che nessuna applicazione ha fornito qualità del servizio.

Nota

Quando i socket connessi si interrompono (ovvero, diventano chiusi per qualsiasi motivo), devono essere eliminati e ricreati. È più sicuro presupporre che quando le cose vanno awry per qualsiasi motivo su un socket connesso, il client WINSock SPI deve eliminare e ricreare i socket necessari per tornare a un punto stabile.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ws2spi.h