Funzione WSAConnect (winsock2.h)

Articolo
03/04/2024

La funzione WSAConnect stabilisce una connessione a un'altra applicazione socket, scambia i dati di connessione e specifica la qualità necessaria del servizio in base alla struttura FLOWPEC specificata.

Sintassi

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
);

Parametri

[in] s

Descrittore che identifica un socket non connesso.

[in] name

Puntatore a una struttura sockaddr che specifica l'indirizzo a cui connettersi. Per IPv4, sockaddr contiene AF_INET per la famiglia di indirizzi, l'indirizzo IPv4 di destinazione e la porta di destinazione. Per IPv6, la struttura sockaddr contiene AF_INET6 per la famiglia di indirizzi, l'indirizzo IPv6 di destinazione, la porta di destinazione e può contenere informazioni aggiuntive sull'ID ambito e flusso.

[in] namelen

Lunghezza, in byte, della struttura sockaddr a cui punta il parametro name .

[in] lpCallerData

Puntatore ai dati utente che devono essere trasferiti all'altro socket durante l'istituzione della connessione. Vedere la sezione Osservazioni.

[out] lpCalleeData

Puntatore ai dati utente da trasferire dall'altro socket durante l'istituzione della connessione. Vedere la sezione Osservazioni.

[in] lpSQOS

Puntatore alle strutture FLOWPEC per socket s, una per ogni direzione.

[in] lpGQOS

Riservato per l'uso futuro con i gruppi di socket. Puntatore alle strutture FLOWPEC per il gruppo socket (se applicabile). Questo parametro deve essere NULL.

Valore restituito

Se non si verifica alcun errore, WSAConnect restituisce zero. In caso contrario, restituisce SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError. In un socket di blocco, il valore restituito indica l'esito positivo o negativo del tentativo di connessione.

Con un socket non sbloccante, il tentativo di connessione non può essere completato immediatamente. In questo caso, WSAConnect restituirà SOCKET_ERROR e WSAGetLastError restituirà WSAEWOULDBLOCK; l'applicazione potrebbe pertanto:

Utilizzare selezionare per determinare il completamento della richiesta di connessione controllando se il socket è scrivibile.
Se l'applicazione usa WSAAsyncSelect per indicare l'interesse per gli eventi di connessione, l'applicazione riceverà una notifica FD_CONNECT quando l'operazione di connessione è completata(riuscita o meno).
Se l'applicazione usa WSAEventSelect per indicare l'interesse negli eventi di connessione, l'oggetto evento associato verrà segnalato quando l'operazione di connessione è stata completata (riuscita o meno).

Per un socket non sbloccante, finché il tentativo di connessione non completa tutte le chiamate successive a WSAConnect nello stesso socket avrà esito negativo con il codice di errore WSAEALREADY.

Se il codice di errore restituito indica che il tentativo di connessione non è riuscito, ovvero WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT, l'applicazione può chiamare nuovamente WSAConnect per lo stesso socket.

Codice di errore	Significato
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.
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 durante l'esecuzione dell'associazione, ma potrebbe essere ritardato fino a quando la funzione di associazione opera su un indirizzo parzialmente jolly (che include ADDR_ANY) e se un indirizzo specifico deve essere "commit" al momento di questa funzione.
WSAEINTR	La chiamata windows Socket 1.1 (blocco) è stata annullata tramite WSACancelBlockingCall.
WSAEINPROGRESS	Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEALREADY	Una chiamata senza blocco o WSAConnect è in corso nel socket specificato.
WSAEADDRNOTAVAIL	L'indirizzo remoto non è un indirizzo valido, ad esempio ADDR_ANY.
WSAEAFNOSUPPORT	Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket.
WSAECONNREFUSED	Il tentativo di connessione è stato rifiutato.
WSAEFAULT	Il nome o il parametro namelen non è una parte valida dello spazio degli 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 in ascolto o l'indirizzo di destinazione specificato non è coerente con quello del gruppo vincolato a cui appartiene il socket o il parametro lpGQOS non è NULL.
WSAEISCONN	Il socket è già connesso (solo socket orientati alla connessione).
WSAENETUNREACH	Impossibile raggiungere la rete da questo host in questo momento.
WSAEHOSTUNREACH	Tentativo di operazione del socket verso un host non raggiungibile.
WSAENOBUFS	Nessuno spazio di buffer disponibile. Impossibile connettere il socket.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	Le strutture FLOWPEC specificate in lpSQOS e lpGQOS non possono essere soddisfatte.
WSAEPROTONOSUPPORT	Il parametro lpCallerData non è supportato dal provider di servizi.
WSAETIMEDOUT	Tentare di connettersi senza stabilire una connessione.
WSAEWOULDBLOCK	Il socket è contrassegnato come non sbloccante e la connessione non può essere completata immediatamente.
WSAEACCES	Tentativo di connettere il socket datagram all'indirizzo di trasmissione non riuscito perché setockopt SO_BROADCAST non è abilitato.

Commenti

La funzione WSAConnect viene usata per creare una connessione alla destinazione specificata e per eseguire una serie di altre operazioni ausiliarie che si verificano in fase di 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 le applicazioni destinate a Windows Vista e versioni successive, prendere in considerazione l'uso della funzione WSAConnectByList o WSAConnectByName che semplifica notevolmente la progettazione dell'applicazione client.

Per i socket orientati alla connessione (ad esempio, digitare SOCK_STREAM), viene avviata una connessione attiva all'host esterno usando il nome (un indirizzo nello spazio dei nomi del socket; per una descrizione dettagliata, vedere bind). Al termine della chiamata, il socket è pronto per inviare/ricevere dati. Se il parametro di indirizzo della struttura dei nomi è tutti zero, WSAConnect restituirà l'errore WSAEADDRNOTAVAIL. Qualsiasi tentativo di riconnessione di una connessione attiva avrà esito negativo con il codice di errore WSAEISCONN.

Nota Se viene aperto un socket, viene eseguita una chiamata setockopt e viene eseguita una chiamata sendto , Windows Sockets esegue una chiamata di funzione di associazione implicita.

Per i socket non sbloccati, spesso non è possibile completare immediatamente la connessione. In questi casi, questa funzione restituisce l'errore WSAEWOULDBLOCK. Tuttavia, l'operazione procede. 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 registra per la notifica. Se il client usa select, l'esito positivo viene segnalato nel set writefds e l'errore viene segnalato nel set exceptfds . Se il client usa WSAAsyncSelect o WSAEventSelect, la notifica viene annunciata con FD_CONNECT e il codice di errore associato alla 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 WSAConnect è semplicemente per stabilire un indirizzo di destinazione predefinito in modo che il socket possa essere usato nelle operazioni successive di invio e ricezione orientate alla connessione (send, WSASend, recv e WSARecv). Tutti i datagrammi ricevuti da un indirizzo diverso dall'indirizzo di destinazione specificato verranno eliminati. Se l'intera struttura del nome è tutti zero (non solo il parametro dell'indirizzo della struttura del nome), il socket verrà disconnesso. L'indirizzo remoto predefinito verrà quindi indeterminato, quindi invia, WSASend, recv e chiamate WSARecv restituirà il codice di errore WSAENOTCONN. È tuttavia possibile usare sendto, WSASendTo, recvfrom e WSARecvFrom . La destinazione predefinita può essere modificata semplicemente chiamando WSAConnect , anche se il socket è già connesso. Tutti i datagrammi accodati per la ricezione vengono eliminati se il nome è diverso dal precedente WSAConnect.

Per i socket senza connessione, il nome può indicare qualsiasi indirizzo valido, incluso un indirizzo di trasmissione. Tuttavia, per connettersi a un indirizzo broadcast, un socket deve avere setockopt SO_BROADCAST abilitato. In caso contrario, WSAConnect 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.

L'applicazione è responsabile dell'allocazione di qualsiasi spazio di memoria a cui punta direttamente o indirettamente uno qualsiasi dei parametri specificati.

Il parametro lpCallerData contiene un puntatore a tutti i dati utente da inviare insieme alla richiesta di connessione (denominata dati di connessione). Si tratta di dati aggiuntivi, non nel normale flusso di dati di rete, che viene inviato con richieste di rete per stabilire una connessione. Questa opzione viene usata dai protocolli legacy, ad esempio DECNet, OSI TP4 e altri.

Nota I dati di connessione non sono supportati dal protocollo TCP/IP in Windows. I dati di connessione sono supportati solo su ATM (RAWWAN) su un socket non elaborato.

Se lpCallerData è NULL, al peer non verranno passati dati utente. LpCalleeData è un parametro di risultato che conterrà tutti i dati utente passati dall'altro socket come parte della creazione della connessione in una struttura WSABUF. Il membro len della struttura WSABUF a cui punta il parametro lpCalleeData contiene inizialmente la lunghezza del buffer allocata dall'applicazione per il membro buf della struttura WSABUF . Il membro len della struttura WSABUF a cui punta il parametro lpCalleeData verrà impostato su zero se non sono stati passati dati utente. Le informazioni lpCalleeData saranno valide al termine dell'operazione di connessione. Per i socket di blocco, l'operazione di connessione viene completata quando viene restituita la funzione WSAConnect . Per i socket non bloccanti, il completamento sarà dopo che si è verificata la notifica di 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.

Al momento della connessione, un'applicazione può usare il parametro lpSQOS e lpGQOS per eseguire l'override di qualsiasi specifica di servizio precedente eseguita per il socket tramite WSAIoctl con il codice operativo SIO_SET_QOS o SIO_SET_GROUP_QOS.

Il parametro lpSQOS specifica le strutture FLOWSPEC 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 qualità della richiesta di servizio, 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 specificati parametri specifici del provider, i membri buf e len della struttura WSABUF a cui punta il parametro lpCalleeData devono essere impostati rispettivamente su NULL e zero. Un valore NULL per il parametro lpSQOS indica che non è stata fornita alcuna qualità del servizio fornita dall'applicazione.

Riservato per uso futuro con i gruppi di socket lpGQOS specifica le strutture FLOWSPEC per il gruppo di socket (se applicabile), una per ogni direzione, seguita da eventuali parametri aggiuntivi specifici del provider. Se non vengono specificati parametri specifici del provider, i membri buf e len della struttura WSABUF a cui punta il parametro lpCalleeData devono essere impostati rispettivamente su NULL e zero. Un valore NULL per lpGQOS indica che la qualità del servizio del gruppo fornita dall'applicazione non è fornita dall'applicazione. Questo parametro verrà ignorato se s non è l'autore del gruppo di socket.

Quando i socket connessi vengono 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, l'applicazione deve eliminare e ricreare i socket necessari per tornare a un punto stabile.

Nota Quando si esegue una chiamata Winsock bloccante, ad esempio WSAConnect, Winsock potrebbe dover attendere il completamento di un evento di rete. Winsock esegue un'attesa avvisabile in questa situazione, che può essere interrotta da una chiamata di procedura asincrona pianificata nello stesso thread. L'esecuzione di un'altra chiamata Winsock bloccante all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread causerà un comportamento non definito e non deve mai essere tentata dai client Winsock.

Windows Phone 8: questa funzione è supportata per le app dello Store di Windows Phone in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll