código de controle SIO_KEEPALIVE_VALS
Descrição
O código de controle SIO_KEEPALIVE_VALS habilita ou desabilita a configuração por conexão da opção keep alive TCP, que especifica o tempo limite e o intervalo de keep alive do TCP.
Para executar essa operação, chame a função WSAIoctl ou WSPIoctl com os parâmetros a seguir.
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.
);
Parâmetros
s
Um descritor que identifica um soquete.
Dwiocontrolcode
O código de controle para a operação. Use SIO_KEEPALIVE_VALS para esta operação.
Lpvinbuffer
Um ponteiro para o buffer de entrada. Esse parâmetro deve apontar para uma estrutura tcp_keepalive .
Cbinbuffer
O tamanho, em bytes, do buffer de entrada. Esse parâmetro deve ser igual ou maior que o tamanho da estrutura tcp_keepalive apontada pelo parâmetro lpvInBuffer .
Lpvoutbuffer
Um ponteiro para o buffer de saída. Esse parâmetro não é usado para essa operação.
cbOutBuffer
O tamanho, em bytes, do buffer de saída. Esse parâmetro deve ser definido como zero.
Lpcbbytesreturned
Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados armazenados no buffer de saída. Esse parâmetro retornado aponta para um valor DWORD igual a zero para essa operação, pois não há saída.
lpvOverlapped
Um ponteiro para uma estrutura WSAOVERLAPPED .
Se soquete s tiver sido criado sem o atributo sobreposto, o parâmetro lpOverlapped será ignorado.
Se s tiver sido aberto com o atributo sobreposto e o parâmetro lpOverlapped não for NULL, a operação será executada como uma operação sobreposta (assíncrona). Nesse caso, o parâmetro lpOverlapped deve apontar para uma estrutura WSAOVERLAPPED válida.
Para operações sobrepostas, a função WSAIoctl ou WSPIoctl retorna imediatamente e o método de conclusão apropriado é sinalizado quando a operação é concluída. Caso contrário, a função não retornará até que a operação seja concluída ou ocorra um erro.
Lpcompletionroutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Um ponteiro para a rotina de conclusão chamado quando a operação foi concluída (ignorado para soquetes não sobrepostos).
lpThreadId
Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro para o mesmo) até que a função WPUQueueApc retorne.
Nota Esse parâmetro se aplica somente à função WSPIoctl .
Lperrno
Um ponteiro para o código de erro.
Nota Esse parâmetro se aplica somente à função WSPIoctl .
Valor retornado
Se a operação for concluída com êxito, a função WSAIoctl ou WSPIoctl retornará zero.
Se a operação falhar ou estiver pendente, a função WSAIoctl ou WSPIoctl retornará SOCKET_ERROR. Para obter informações de erro estendidas, chame WSAGetLastError.
| Código do erro | Significado |
|---|---|
| WSA_IO_PENDING | Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente. |
| WSA_OPERATION_ABORTED | Uma operação sobreposta foi cancelada devido ao fechamento do soquete ou à execução do comando IOCTL SIO_FLUSH . |
| WSAEFAULT | O parâmetro lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário. |
| WSAEINPROGRESS | A função é invocada quando um retorno de chamada está em andamento. |
| WSAEINTR | Uma operação de bloqueio foi interrompida. |
| WSAEINVAL | O parâmetro dwIoControlCode não é um comando válido ou um parâmetro de entrada especificado não é aceitável ou o comando não é aplicável ao tipo de soquete especificado. |
| WSAENETDOWN | O subsistema de rede falhou. |
| WSAENOPROTOOPT | Não há suporte para a opção de soquete no protocolo especificado. Esse erro é retornado para um soquete de datagrama. |
| WSAENOTSOCK | O descritor s não é um soquete. |
| WSAEOPNOTSUPP | Não há suporte para o comando IOCTL especificado. Esse erro será retornado se o SIO_KEEPALIVE_VALS IOCTL não tiver suporte do provedor de transporte. |
Comentários
O SIO_KEEPALIVE_VALS IOCTL tem suporte no Windows 2000 e versões posteriores do sistema operacional.
O código de controle SIO_KEEPALIVE_VALS habilita ou desabilita a configuração por conexão da opção keep alive TCP, que especifica o tempo limite e o intervalo de keep alive TCP usados para pacotes keep alive TCP. Para obter mais informações sobre a opção keep alive, consulte a seção 4.2.3.6 sobre os Requisitos para Hosts da Internet — Camadas de Comunicação especificadas no RFC 1122 disponível no site do IETF. (Esse recurso só pode estar disponível em inglês.)
O parâmetro lpvInBuffer deve apontar para uma estrutura de tcp_keepalive definida no arquivo de cabeçalho Mstcpip.h . Essa estrutura é definida da seguinte maneira:
/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
u_long onoff;
u_long keepalivetime;
u_long keepaliveinterval;
};
O valor especificado no membro onoff determina se o keep alive TCP está habilitado ou desabilitado. Se o membro onoff estiver definido como um valor diferente de zero, o keep alive do TCP será habilitado e os outros membros na estrutura serão usados. O membro keepalivetime especifica o tempo limite, em milissegundos, sem atividade até que o primeiro pacote keep alive seja enviado. O membro keepaliveinterval especifica o intervalo, em milissegundos, entre quando pacotes keep alive sucessivos são enviados se nenhuma confirmação for recebida.
A opção SO_KEEPALIVE , que é uma das opções de soquete SOL_SOCKET, também pode ser usada para habilitar ou desabilitar o keep alive TCP em uma conexão, bem como consultar o estado atual dessa opção. Para consultar se o keep alive do TCP está habilitado em um soquete, a função getsockopt pode ser chamada com a opção SO_KEEPALIVE . Para habilitar ou desabilitar o keep alive do TCP, a função setsockopt pode ser chamada com a opção SO_KEEPALIVE . Se o keep alive do TCP estiver habilitado com SO_KEEPALIVE, as configurações de TCP padrão serão usadas para manter o tempo limite e o intervalo, a menos que esses valores tenham sido alterados usando SIO_KEEPALIVE_VALS.
O valor padrão de todo o sistema do tempo limite keep alive é controlável por meio da configuração do Registro KeepAliveTime , que usa um valor em milissegundos. Se a chave não estiver definida, o tempo limite padrão de keep alive será de 2 horas. O valor padrão em todo o sistema do intervalo keep alive é controlável por meio da configuração do Registro KeepAliveInterval , que usa um valor em milissegundos. Se a chave não estiver definida, o intervalo de keep alive padrão será de 1 segundo.
No Windows Vista e posteriores, o número de investigações keep alive (retransmissões de dados) é definido como 10 e não pode ser alterado.
No Windows Server 2003, Windows XP e Windows 2000, a configuração padrão para o número de investigações keep alive é 5. O número de investigações keep alive é controlável por meio das configurações do registro TcpMaxDataRetransmissions e PPTPTcpMaxDataRetransmissions . O número de investigações keep alive é definido como o maior dos dois valores de chave do Registro. Se esse número for 0, as investigações keep alive não serão enviadas. Se esse número estiver acima de 255, ele será ajustado para 255.