SO_KEEPALIVE opção de soquete
A opção de soquete SO_KEEPALIVE foi projetada para permitir que um aplicativo habilite pacotes keep alive para uma conexão de soquete.
Para consultar o status dessa opção de soquete, chame a função getsockopt. Para definir essa opção, chame a função setsockopt com os parâmetros a seguir.
Valor da opção soquete
A constante que representa essa opção de soquete é 0x0008.
Sintaxe
int setsockopt(
(SOCKET) s, // descriptor identifying a socket
(int) SOL_SOCKET, // level
(int) SO_KEEPALIVE, // optname
(char *) optval, // input buffer,
(int) optlen // size of input buffer
);
Parâmetros
-
s [in]
-
Um descritor que identifica o soquete.
-
level [in]
-
O nível no qual a opção é definida. Use SOL_SOCKET para esta operação.
-
optname [in]
-
A opção de soquete para a qual o valor deve ser definido. Use SO_KEEPALIVE para esta operação.
-
optval [out]
-
Um ponteiro para o buffer que contém o valor da opção a ser definida. Esse parâmetro deve apontar para buffer igual ou maior que o tamanho de um valor DWORD .
Esse valor é tratado como um valor booliano com 0 usado para indicar FALSE (desabilitado) e um valor diferente de zero para indicar TRUE (habilitado).
-
optlen [in]
-
O tamanho, em bytes, do buffer optval . Esse tamanho deve ser igual ou maior que o tamanho de um valor DWORD .
Retornar valor
Se a operação for concluída com êxito, setsockopt retornará zero.
Se a operação falhar, um valor de SOCKET_ERROR será retornado e um código de erro específico poderá ser recuperado chamando WSAGetLastError.
| Código do erro | Significado |
|---|---|
| Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função. |
|
| O subsistema de rede falhou. |
|
| Um dos parâmetros optval ou optlen apontam para a memória que não está em uma parte válida do espaço de endereço do usuário. Esse erro também será retornado se o valor apontado pelo parâmetro optlen for menor que o tamanho de um valor DWORD . |
|
| Uma chamada do Windows Sockets 1.1 de bloqueio está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada. |
|
| O parâmetro de nível é desconhecido ou inválido. No Windows Vista e posterior, esse erro também será retornado se o soquete estiver em um estado de transição. |
|
| A opção é desconhecida ou sem suporte da família de protocolos indicada. Esse erro será retornado se o descritor de soquete passado no parâmetro s for para um soquete de datagrama. |
|
| O descritor não é um soquete. |
Comentários
A função getsockopt chamada com a opção de soquete SO_KEEPALIVE permite que um aplicativo recupere o estado atual da opção keepalive, embora esse recurso normalmente não seja usado. Se um aplicativo precisar habilitar pacotes keepalive em um soquete, ele apenas chamará a função setsockopt para habilitar a opção.
A função setsockopt chamada com a opção de soquete SO_KEEPALIVE permite que um aplicativo habilite pacotes keep alive para uma conexão de soquete. A opção SO_KEEPALIVE para um soquete é desabilitada (definida como FALSE) por padrão.
Quando essa opção de soquete está habilitada, a pilha TCP envia pacotes keep alive quando nenhum pacote de confirmação ou dados foi recebido para a conexão dentro de um intervalo. 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.)
A opção de soquete SO_KEEPALIVE é válida apenas para protocolos que dão suporte à noção de keep alive (protocolos orientados para conexão). Para TCP, o tempo limite padrão de keep alive é de 2 horas e o intervalo keep alive é de 1 segundo. O número padrão de investigações keep alive varia de acordo com a versão do Windows.
O código de controle SIO_KEEPALIVE_VALS pode ser usado para habilitar ou desabilitar o keep alive e ajustar o tempo limite e o intervalo para uma única conexão. Se keep-alive estiver habilitado com SO_KEEPALIVE, as configurações de TCP padrão serão usadas para o tempo limite e o intervalo de keep alive, 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. 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.
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.
No Windows Vista e posteriores, a opção de soquete SO_KEEPALIVE só pode ser definida usando a função setsockopt quando o soquete está em um estado conhecido e não em um estado de transição. Para TCP, a opção de soquete SO_KEEPALIVE deve ser definida antes da função de conexão (connect, ConnectEx, WSAConnect, WSAConnectByList ou WSAConnectByName) ser chamada ou depois que a solicitação de conexão for realmente concluída. Se a função connect foi chamada de forma assíncrona, isso requer aguardar a conclusão da conexão antes de tentar definir a opção de soquete SO_KEEPALIVE . Se um aplicativo tentar definir a opção de soquete SO_KEEPALIVE quando uma solicitação de conexão ainda estiver em processo, a função setsockopt falhará e retornará WSAEINVAL.
No Windows Server 2003, Windows XP e Windows 2000, a opção de soquete SO_KEEPALIVE pode ser definida usando a função setsockopt quando o soquete é um estado de transição (uma solicitação de conexão ainda está em andamento), bem como um estado bem conhecido.
Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente em Winsock2.h e nunca deve ser usado diretamente.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte |
Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte |
Windows 2000 Server [somente aplicativos da área de trabalho] |
| Cabeçalho |
|