funzione di arresto (winsock.h)

Articolo
03/04/2024

La funzione di arresto disabilita l'invio o la ricezione in un socket.

Sintassi

int shutdown(
  [in] SOCKET s,
  [in] int    how
);

Parametri

[in] s

Descrittore che identifica un socket.

[in] how

Flag che descrive quali tipi di operazione non saranno più consentiti. I valori possibili per questo flag sono elencati nel file di intestazione Winsock2.h .

Valore	Significato
SD_RECEIVE 0	Operazioni di ricezione di arresto.
SD_SEND 1	Arrestare le operazioni di invio.
SD_BOTH 2	Arrestare le operazioni di invio e ricezione.

Valore restituito

Se non si verifica alcun errore, l'arresto restituisce zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Codice di errore	Significato
WSAECONNABORTED	Circuito virtuale terminato a causa di un timeout o di un altro errore. L'applicazione deve chiudere il socket che non è più utilizzabile. Questo errore si applica solo a un socket orientato alla connessione.
WSAECONNRESET	Circuito virtuale reimpostato dal lato remoto durante l'esecuzione di una chiusura definitiva o anomala. L'applicazione deve chiudere il socket che non è più utilizzabile. Questo errore si applica solo a un socket orientato alla connessione.
WSAEINPROGRESS	Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINVAL	Il modo in cui il parametro non è valido o non è coerente con il tipo di socket. Ad esempio, SD_SEND viene usato con un tipo di socket UNI_RECV.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOTCONN	Il socket non è connesso. Questo errore si applica solo a un socket orientato alla connessione.
WSAENOTSOCK	Nota Il descrittore non è un socket.
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.

Commenti

La funzione di arresto viene usata in tutti i tipi di socket per disabilitare la ricezione, la trasmissione o entrambi.

Se il parametro è SD_RECEIVE, le chiamate successive alla funzione recv nel socket non saranno consentite. Questo non ha alcun effetto sui livelli di protocollo inferiori. Per i socket TCP, se nel socket sono ancora accodati dati in attesa di ricevere o i dati arrivano successivamente, la connessione viene reimpostata, poiché i dati non possono essere recapitati all'utente. Per i socket UDP, i datagrammi in ingresso vengono accettati e accodati. In nessun caso verrà generato un pacchetto di errore ICMP.

Se il parametro è SD_SEND, le chiamate successive alla funzione di invio non sono consentite. Per i socket TCP, un FIN verrà inviato dopo l'invio di tutti i dati e la conferma dal ricevitore.

L'impostazione di come SD_BOTH disabilita sia gli invii che le ricevute, come descritto in precedenza.

La funzione di arresto non chiude il socket. Tutte le risorse collegate al socket non verranno liberate finché non viene richiamato closesocket .

Per garantire che tutti i dati vengano inviati e ricevuti in un socket connesso prima della chiusura, un'applicazione deve usare l'arresto per chiudere la connessione prima di chiamare closesocket. Un metodo per attendere la notifica che l'estremità remota ha inviato tutti i dati e avviato una disconnessione normale usa la funzione WSAEventSelect come indicato di seguito:

Chiamare WSAEventSelect per la registrazione per la notifica di FD_CLOSE.
Chiamare l'arresto con how=SD_SEND.
Quando FD_CLOSE ricevuto, chiamare il recv o WSARecv fino al completamento della funzione con esito positivo e indica che sono stati ricevuti zero byte. Se SOCKET_ERROR viene restituito, la disconnessione grazia non è possibile.
Chiamare closesocket.

Un altro metodo per attendere la notifica che l'estremità remota ha inviato tutti i dati e avviato una disconnessione normale usa chiamate di ricezione sovrapposte segue:

Chiamare l'arresto con how=SD_SEND.
Chiamare recv o WSARecv fino al completamento della funzione con esito positivo e indica che sono stati ricevuti zero byte. Se SOCKET_ERROR viene restituito, la disconnessione grazia non è possibile.
Chiamare closesocket.

Nota La funzione di arresto non blocca indipendentemente dall'impostazione SO_LINGER sul socket.

Per altre informazioni, vedere la sezione relativa all'arresto graziato, alle opzioni di linger e alla chiusura del socket.

Dopo aver chiamato la funzione di arresto per disabilitare l'invio, la ricezione o entrambi, non esiste alcun metodo per abilitare nuovamente l'invio o la ricezione per la connessione socket esistente.

Un'applicazione non deve basarsi sulla possibilità di riutilizzare un socket dopo l'arresto. In particolare, un provider Windows Sockets non è necessario per supportare l'uso della connessione in un socket che è stato arrestato.

Se un'applicazione vuole riutilizzare un socket, la funzione DisconnectEx deve essere chiamata con il parametro dwFlags impostato su TF_REUSE_SOCKET per chiudere una connessione su un socket e preparare l'handle socket da riutilizzare. Al termine della richiesta DisconnectEx , l'handle del socket può essere passato alla funzione AcceptEx o ConnectEx .

Se un'applicazione vuole riutilizzare un socket, le funzioni TransmissionFile o TransmissionPackets possono essere chiamate con il parametro dwFlags impostato con TF_DISCONNECT e TF_REUSE_SOCKET per disconnettersi dopo che tutti i dati sono stati accodati per la trasmissione e preparare l'handle socket da riutilizzare. Al termine della richiesta TransmitFile, l'handle del socket può essere passato alla chiamata di funzione usata in precedenza per stabilire la connessione, ad esempio AcceptEx o ConnectEx. Al termine della funzione TransmitPackets , l'handle socket può essere passato alla funzione AcceptEx .

Nota La disconnessione a livello di socket è soggetta al comportamento del trasporto sottostante. Ad esempio, un socket TCP può essere soggetto allo stato tcp TIME_WAIT, causando il ritardo della chiamata DisconnectEx, TransmitFile o TransmitPackets .

Nota Quando si emette una chiamata Winsock bloccata, ad esempio l'arresto, 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 routine asincrona pianificata nello stesso thread. L'emissione di un'altra chiamata winsock bloccata all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread comporterà un comportamento non definito e non deve mai essere tentato dai client Winsock.

Note per ATM

Esistono problemi importanti associati al teardown della connessione quando si usa la modalità di trasferimento asincrona (ATM) e Windows Sockets 2. Per altre informazioni su queste importanti considerazioni, vedere la sezione intitolata Note per ATM nella sezione Osservazioni della funzione closesocket di riferimento.

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store 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	winsock.h (include Winsock2.h, Webhost.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll