Função WinHttpQueryOption (winhttp.h)

Artigo
08/27/2023

A função WinHttpQueryOption consulta uma opção de Internet no identificador especificado.

Sintaxe

WINHTTPAPI BOOL WinHttpQueryOption(
  [in]      HINTERNET hInternet,
  [in]      DWORD     dwOption,
  [out]     LPVOID    lpBuffer,
  [in, out] LPDWORD   lpdwBufferLength
);

Parâmetros

[in] hInternet

Um identificador HINTERNET no qual consultar informações. Observe que isso pode ser um identificador de sessão ou um identificador de solicitação, dependendo de qual opção está sendo consultada; consulte o tópico Sinalizadores de Opção para determinar qual identificador é apropriado para usar na consulta de uma determinada opção.

[in] dwOption

Um valor inteiro longo sem sinal que contém a opção internet a ser consultada. Esse pode ser um dos valores de Sinalizadores de Opção .

[out] lpBuffer

Um ponteiro para um buffer que recebe a configuração de opção. As cadeias de caracteres retornadas pela função WinHttpQueryOption são alocadas globalmente, portanto, o aplicativo de chamada deve liberar globalmente a cadeia de caracteres quando terminar de usá-la. Definir esse parâmetro como NULL faz com que essa função retorne FALSE. Chamar GetLastError retorna ERROR_INSUFFICIENT_BUFFER e lpdwBufferLength contém o número de bytes necessários para manter as informações solicitadas.

[in, out] lpdwBufferLength

Um ponteiro para uma variável de inteiro longo sem sinal que contém o comprimento de lpBuffer, em bytes. Quando a função retorna, a variável recebe o comprimento dos dados colocados em lpBuffer. Se GetLastError retornar ERROR_INSUFFICIENT_BUFFER, esse parâmetro receberá o número de bytes necessários para manter as informações solicitadas.

Valor retornado

Retorna TRUE se tiver êxito ou FALSE caso contrário. Para obter uma mensagem de erro específica, 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_WINHTTP_INVALID_OPTION	Um valor de opção inválido foi especificado.
ERROR_NOT_ENOUGH_MEMORY	Não havia memória suficiente disponível para concluir a operação solicitada. (Código de erro do Windows)

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.

GetLastError retornará o ERROR_INVALID_PARAMETER se um sinalizador de opção inválido para o tipo de identificador especificado for passado para o parâmetro dwOption .

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 demonstra a recuperação do valor de tempo limite da conexão:

    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // 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 WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Requisitos


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.