Funzione WSAConnect (winsock2.h)

La funzione WSAConnect stabilisce una connessione a un'altra applicazione socket, scambia i dati di connessione e specifica la qualità del servizio richiesta in base alla struttura FLOWSPEC 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
);

Parameters

[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 sul flusso e sull'ID ambito.

[in] namelen

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

[in] lpCallerData

Puntatore ai dati utente da trasferire all'altro socket durante la connessione. Vedere la sezione Osservazioni.

[out] lpCalleeData

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

[in] lpSQOS

Puntatore alla struttura QOS per socket s.

[in] lpGQOS

Riservato per un uso futuro con i gruppi di socket. Puntatore alla struttura QOS per il gruppo di 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 bloccante, il tentativo di connessione non può essere completato immediatamente. In questo caso, WSAConnect restituirà SOCKET_ERROR e WSAGetLastError restituirà WSAEWOULDBLOCK; l'applicazione potrebbe quindi:

• Utilizzare select 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 è stata completata o meno.
• Se l'applicazione usa WSAEventSelect per indicare l'interesse per gli eventi di connessione, l'oggetto evento associato verrà segnalato al termine dell'operazione di connessione (esito positivo o negativo).

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.

Osservazioni:

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, è consigliabile usare la funzione WSAConnectByList o WSAConnectByName che semplifica notevolmente la progettazione dell'applicazione client.

Per i socket orientati alla connessione (ad esempio, tipo 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 l'invio/ricezione dei dati. Se il parametro address della struttura del nome è tutti zeri, WSAConnect restituirà l'errore WSAEADDRNOTAVAIL. Qualsiasi tentativo di riconnessione di una connessione attiva avrà esito negativo con il codice di errore WSAEISCONN.

Per un socket senza connessione (ad esempio, tipo SOCK_DGRAM), l'operazione eseguita da WSAConnect consiste semplicemente nel stabilire un indirizzo di destinazione predefinito in modo che il socket possa essere usato nelle successive operazioni 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 zeri (non solo il parametro address della struttura del nome), il socket verrà disconnesso. L'indirizzo remoto predefinito sarà quindi indeterminato, quindi le chiamate send, WSASend, recv e WSARecv restituiranno il codice di errore WSAENOTCONN. È tuttavia possibile usare sendto, WSASendTo, recvfrom e WSARecvFrom . La destinazione predefinita può essere modificata semplicemente chiamando di nuovo WSAConnect , anche se il socket è già connesso. Gli eventuali datagrammi accodati per la ricevuta vengono eliminati se il nome è diverso da WSAConnect precedente.

Per i socket senza connessione, il nome può indicare qualsiasi indirizzo valido, incluso un indirizzo broadcast. Tuttavia, per connettersi a un indirizzo di trasmissione, 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 dei parametri specificati.

Il parametro lpCallerData contiene un puntatore a tutti i dati utente da inviare insieme alla richiesta di connessione (denominata connect data). 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.

Se lpCallerData è NULL, nessun dato utente verrà passato al peer. 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 allocato 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.

In fase di 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 è disponibile alcuna qualità del servizio fornita dall'applicazione.

Riservato per un 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 non è disponibile alcuna qualità del servizio 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 rimossi 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.

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

Vedere anche

WSAAsyncSelect

WSABUF

WSAConnect

ConnectEx

WSAConnectByList

WSAEventSelect

Funzioni Winsock

Informazioni di riferimento su Winsock

accettare

associare

connect

getsockname

getsockopt

Selezionare

presa