Função WinHttpSetTimeouts (winhttp.h)

Artigo
01/11/2024

A função WinHttpSetTimeouts define tempos limite envolvidos com transações HTTP.

Sintaxe

WINHTTPAPI BOOL WinHttpSetTimeouts(
  [in] HINTERNET hInternet,
  [in] int       nResolveTimeout,
  [in] int       nConnectTimeout,
  [in] int       nSendTimeout,
  [in] int       nReceiveTimeout
);

Parâmetros

[in] hInternet

O identificador HINTERNET retornado por WinHttpOpen ou WinHttpOpenRequest.

[in] nResolveTimeout

Um valor do inteiro de tipo que especifica o valor de tempo limite, em milissegundos, a ser usado para resolução de nomes. Se a resolução levar mais tempo do que esse valor de tempo limite, a solicitação será cancelada. O valor inicial é zero, o que significa que não há tempo limite (infinito).

Windows Vista e Windows XP: Se o tempo limite de DNS for especificado usando NAME_RESOLUTION_TIMEOUT, haverá uma sobrecarga de um thread por solicitação.

[in] nConnectTimeout

Um valor do tipo inteiro que especifica o valor de tempo limite, em milissegundos, a ser usado para solicitações de conexão de servidor. Se uma solicitação de conexão demorar mais do que esse valor de tempo limite, a solicitação será cancelada. O valor inicial é 60.000 (60 segundos).

O TCP/IP pode atingir o tempo limite ao configurar o soquete durante a troca SYN/ACK de três etapas, independentemente do valor desse parâmetro.

[in] nSendTimeout

Um valor do tipo inteiro que especifica o valor de tempo limite, em milissegundos, a ser usado para enviar solicitações. Se o envio de uma solicitação demorar mais do que esse valor de tempo limite, o envio será cancelado. O valor inicial é 30.000 (30 segundos).

[in] nReceiveTimeout

Um valor do tipo inteiro que especifica o valor de tempo limite, em milissegundos, para receber uma resposta a uma solicitação. Se uma resposta demorar mais do que esse valor de tempo limite, a solicitação será cancelada. O valor inicial é 30.000 (30 segundos).

Retornar valor

Retornará TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, chame GetLastError. Entre os códigos de erro retornados estão os seguintes.

Código do Erro	Descrição
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	A operação solicitada não pode ser executada porque o identificador fornecido não está no estado correto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	O tipo de identificador fornecido está incorreto para esta operação.
ERROR_WINHTTP_INTERNAL_ERROR	Ocorreu um erro interno.
ERROR_NOT_ENOUGH_MEMORY	Não havia memória suficiente disponível para concluir a operação solicitada. (Código de erro do Windows)
ERROR_INVALID_PARAMETER	Um ou mais dos parâmetros de tempo limite tem um valor negativo diferente de -1.

Comentários

Mesmo quando WinHTTP é usado no modo assíncrono (ou seja, quando WINHTTP_FLAG_ASYNC foi definido no WinHttpOpen), essa função opera de forma síncrona. O valor retornado indica êxito ou falha. Para obter informações de erro estendidas, chame GetLastError.

Um valor de 0 ou -1 define um tempo limite para esperar infinitamente. Um valor maior que 0 define o valor de tempo limite em milissegundos. Por exemplo, 30.000 definiriam o tempo limite como 30 segundos. Todos os valores negativos diferentes de -1 fazem com que a função falhe com ERROR_INVALID_PARAMETER.

Importante Se um tempo limite pequeno for definido usando WinHttpSetOption e WINHTTP_OPTION_RECEIVE_TIMEOUT, ele poderá substituir o valor definido com o parâmetro dwReceiveTimeout , fazendo com que uma resposta seja encerrada antes do esperado. Para evitar isso, não defina um tempo limite com a opção WINHTTP_OPTION_RECEIVE_TIMEOUT menor que o valor definido usando dwReceiveTimeout.

Nota Para Windows XP e Windows 2000, consulte a seção Requisitos de tempo de execução da página inicial do WinHTTP.

Exemplos

Este exemplo mostra como definir novos valores de tempo limite usando WinHttpSetTimeouts.

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {
        // Use WinHttpSetTimeouts to set a new time-out values.
        if (!WinHttpSetTimeouts( hSession, 10000, 10000, 10000, 10000))
            printf( "Error %u in WinHttpSetTimeouts.\n", GetLastError());
              
        // PLACE ADDITIONAL CODE HERE.
    
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP, Windows 2000 Professional com SP3 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003, Windows 2000 Server com SP3 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winhttp.h
Biblioteca	Winhttp.lib
DLL	Winhttp.dll
Redistribuível	WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000.