Funzione WSAConnect (winsock2.h)
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).
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 |
|---|---|
| Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita. | |
| Il sottosistema di rete non è riuscito. | |
| 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. | |
| La chiamata windows Socket 1.1 (blocco) è stata annullata tramite WSACancelBlockingCall. | |
| Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback. | |
| Una chiamata senza blocco oWSAConnect è in corso nel socket specificato. | |
| L'indirizzo remoto non è un indirizzo valido, ad esempio ADDR_ANY. | |
| Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket. | |
| Il tentativo di connessione è stato rifiutato. | |
| 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. | |
| 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. | |
| Il socket è già connesso (solo socket orientati alla connessione). | |
| Impossibile raggiungere la rete da questo host in questo momento. | |
| Tentativo di operazione del socket verso un host non raggiungibile. | |
| Nessuno spazio di buffer disponibile. Impossibile connettere il socket. | |
| Il descrittore non è un socket. | |
| Le strutture FLOWPEC specificate in lpSQOS e lpGQOS non possono essere soddisfatte. | |
| Il parametro lpCallerData non è supportato dal provider di servizi. | |
| Tentare di connettersi senza stabilire una connessione. | |
| Il socket è contrassegnato come non sbloccante e la connessione non può essere completata immediatamente. | |
| 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.
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.
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.
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 |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per