codice di controllo SIO_KEEPALIVE_VALS

Articolo
06/12/2023

Descrizione

Il codice di controllo SIO_KEEPALIVE_VALS abilita o disabilita l'impostazione per connessione dell'opzione TCP keep-alive che specifica il timeout e l'intervallo TCP keep-alive.

Per eseguire questa operazione, chiamare la funzione WSAIoctl o WSPIoctl con i parametri seguenti.

int WSAIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parametri

s

Descrittore che identifica un socket.

dwIoControlCode

Codice di controllo per l'operazione. Usare SIO_KEEPALIVE_VALS per questa operazione.

lpvInBuffer

Puntatore al buffer di input. Questo parametro deve puntare a una struttura tcp_keepalive .

cbInBuffer

Dimensioni, in byte, del buffer di input. Questo parametro deve essere uguale o maggiore delle dimensioni della struttura tcp_keepalive a cui punta il parametro lpvInBuffer .

lpvOutBuffer

Puntatore al buffer di output. Questo parametro non viene usato per questa operazione.

cbOutBuffer

Dimensioni, in byte, del buffer di output. Questo parametro deve essere impostato su zero.

lpcbBytesReturned

Puntatore a una variabile che riceve le dimensioni, in byte, dei dati archiviati nel buffer di output. Questo parametro restituito punta a un valore DWORD pari a zero per questa operazione, poiché non è presente alcun output.

lpvOverlapped

Puntatore a una struttura WSAOVERLAPPED .

Se il socket s è stato creato senza l'attributo sovrapposto, il parametro lpOverlapped viene ignorato .

Se s è stato aperto con l'attributo sovrapposto e il parametro lpOverlapped non è NULL, l'operazione viene eseguita come operazione sovrapposta (asincrona). In questo caso, il parametro lpOverlapped deve puntare a una struttura WSAOVERLAPPED valida.

Per le operazioni sovrapposte, la funzione WSAIoctl o WSPIoctl restituisce immediatamente e il metodo di completamento appropriato viene segnalato al termine dell'operazione. In caso contrario, la funzione non restituisce finché l'operazione non è stata completata o si verifica un errore.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntatore alla routine di completamento chiamata quando l'operazione è stata completata (ignorata per socket non sovrapposti).

lpThreadId

Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID a cui fa riferimento (non lo stesso puntatore) fino a quando la funzione WPUQueueApc restituisce.

Nota Questo parametro si applica solo alla funzione WSPIoctl .

lpErrno

Puntatore al codice di errore.

Nota Questo parametro si applica solo alla funzione WSPIoctl .

Valore restituito

Se l'operazione viene completata correttamente, la funzione WSAIoctl o WSPIoctl restituisce zero.

Se l'operazione ha esito negativo o è in sospeso, la funzione WSAIoctl o WSPIoctl restituisce SOCKET_ERROR. Per ottenere informazioni sull'errore estese, chiamare WSAGetLastError.

Codice di errore	Significato
WSA_IO_PENDING	Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSA_OPERATION_ABORTED	Un'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando IOCTL SIO_FLUSH .
WSAEFAULT	Il parametro lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio degli indirizzi utente.
WSAEINPROGRESS	La funzione viene richiamata quando un callback è in corso.
WSAEINTR	Un'operazione di blocco è stata interrotta.
WSAEINVAL	Il parametro dwIoControlCode non è un comando valido o un parametro di input specificato non è accettabile oppure il comando non è applicabile al tipo di socket specificato.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOPROTOOPT	L'opzione socket non è supportata nel protocollo specificato. Questo errore viene restituito per un socket di datagram.
WSAENOTSOCK	Il descrittore s non è un socket.
WSAEOPNOTSUPP	Il comando IOCTL specificato non è supportato. Questo errore viene restituito se il SIO_KEEPALIVE_VALS IOCTL non è supportato dal provider di trasporto.

Commenti

Il SIO_KEEPALIVE_VALS IOCTL è supportato in Windows 2000 e versioni successive del sistema operativo.

Il codice di controllo SIO_KEEPALIVE_VALS abilita o disabilita l'impostazione per connessione dell'opzione TCP keep-alive che specifica il timeout e l'intervallo TCP keep-alive usati per i pacchetti keep-alive TCP. Per altre informazioni sull'opzione keep-alive, vedere la sezione 4.2.3.6 sui requisiti per gli host Internet: livelli di comunicazione specificati in RFC 1122 disponibili nel sito Web IETF. Questa risorsa può essere disponibile solo in inglese.

Il parametro lpvInBuffer deve puntare a una struttura tcp_keepalive definita nel file di intestazione Mstcpip.h . Questa struttura è definita come segue:

/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
    u_long  onoff;
    u_long  keepalivetime;
    u_long  keepaliveinterval;
};

Il valore specificato nel membro onoff determina se TCP keep-alive è abilitato o disabilitato. Se il membro onoff è impostato su un valore diverso da zero, tcp keep-alive è abilitato e vengono usati gli altri membri della struttura. Il membro keepalivetime specifica il timeout, in millisecondi, senza attività finché non viene inviato il primo pacchetto keep-alive. Il membro keepaliveinterval specifica l'intervallo, in millisecondi, tra quando vengono inviati pacchetti keep-alive successivi se non viene ricevuto alcun riconoscimento.

L'opzione SO_KEEPALIVE , che è una delle opzioni socket SOL_SOCKET, può essere usata anche per abilitare o disabilitare il valore TCP keep-alive in una connessione, nonché eseguire una query sullo stato corrente di questa opzione. Per eseguire una query sul fatto che TCP keep-alive sia abilitato in un socket, è possibile chiamare la funzione getsockopt con l'opzione SO_KEEPALIVE . Per abilitare o disabilitare TCP keep-alive, la funzione setockopt può essere chiamata con l'opzione SO_KEEPALIVE . Se TCP keep-alive è abilitato con SO_KEEPALIVE, le impostazioni TCP predefinite vengono usate per il timeout e l'intervallo keep-alive, a meno che questi valori non siano stati modificati usando SIO_KEEPALIVE_VALS.

Il valore predefinito del timeout keep-alive è controllabile tramite l'impostazione del Registro di sistema KeepAliveTime che accetta un valore in millisecondi. Se la chiave non è impostata, il timeout keep-alive predefinito è di 2 ore. Il valore predefinito a livello di sistema dell'intervallo keep-alive è controllabile tramite l'impostazione del Registro di sistema KeepAliveInterval che accetta un valore in millisecondi. Se la chiave non è impostata, l'intervallo keep-alive predefinito è 1 secondo.

In Windows Vista e versioni successive il numero di probe keep-alive (ritrasmissioni dati) è impostato su 10 e non può essere modificato.

In Windows Server 2003, Windows XP e Windows 2000, l'impostazione predefinita per il numero di probe keep-alive è 5. Il numero di probe keep-alive è controllabile tramite le impostazioni del Registro di sistema TcpMaxDataRetransmissions e PPTPTcpMaxDataRetransmissions . Il numero di probe keep-alive è impostato sul valore maggiore dei due valori della chiave del Registro di sistema. Se questo numero è 0, i probe keep-alive non verranno inviati. Se questo numero è superiore a 255, viene modificato su 255.