Função WinHttpOpen (winhttp.h)

  • Artigo

A função WinHttpOpen inicializa, para um aplicativo, o uso de funções WinHTTP e retorna um identificador de sessão WinHTTP.

Sintaxe

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

Parâmetros

[in, optional] pszAgentW

Um ponteiro para uma variável de cadeia de caracteres que contém o nome do aplicativo ou da entidade que chama as funções WinHTTP. Esse nome é usado como o agente do usuário no protocolo HTTP.

[in] dwAccessType

Tipo de acesso necessário. Esse pode ser um dos valores a seguir.

Valor Significado
WINHTTP_ACCESS_TYPE_NO_PROXY
 Resolve todos os nomes de host diretamente sem um proxy.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
Importante O uso dessa opção foi preterido no Windows 8.1 e mais recente. Em vez disso, use WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY.
 
Recupera o proxy estático ou a configuração direta do registro. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY não herda as configurações de proxy do navegador.

A configuração de proxy WinHTTP é definida por um desses mecanismos.
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 Passa solicitações para o proxy, a menos que uma lista de bypass de proxy seja fornecida e o nome a ser resolvido ignore o proxy. Nesse caso, essa função usa os valores passados para pwszProxyName e pwszProxyBypass.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 Usa configurações de proxy de sistema e por usuário (incluindo a configuração de proxy de Explorer da Internet) para determinar quais proxy/proxies usar. Tenta lidar automaticamente com o failover entre vários proxies, configurações de proxy diferentes por interface e autenticação. Com suporte em Windows 8.1 e mais recentes.

[in] pszProxyW

Um ponteiro para uma variável de cadeia de caracteres que contém o nome do servidor proxy a ser usado quando o acesso de proxy é especificado definindo dwAccessType como WINHTTP_ACCESS_TYPE_NAMED_PROXY. As funções WinHTTP reconhecem apenas proxies de tipo CERN para HTTP. Se dwAccessType não estiver definido como WINHTTP_ACCESS_TYPE_NAMED_PROXY, esse parâmetro deverá ser definido como WINHTTP_NO_PROXY_NAME.

[in] pszProxyBypassW

Um ponteiro para uma variável de cadeia de caracteres que contém uma lista delimitada por ponto e vírgula opcional de nomes de host ou endereços IP, ou ambos, que não deve ser roteado por meio do proxy quando dwAccessType é definido como WINHTTP_ACCESS_TYPE_NAMED_PROXY. A lista pode conter caracteres curinga. Não use uma cadeia de caracteres vazia, pois a função WinHttpOpen a usa como a lista de bypass de proxy. Se esse parâmetro especificar a macro "<local>" na lista como a única entrada, essa função ignorará qualquer nome de host que não contenha um ponto final. Se dwAccessType não estiver definido como WINHTTP_ACCESS_TYPE_NAMED_PROXY, esse parâmetro deverá ser definido como WINHTTP_NO_PROXY_BYPASS.

[in] dwFlags

Valor inteiro longo sem sinal que contém os sinalizadores que indicam várias opções que afetam o comportamento dessa função. Esse parâmetro pode ter o valor a seguir.

Valor Significado
WINHTTP_FLAG_ASYNC
 Use as funções WinHTTP de forma assíncrona. Por padrão, todas as funções WinHTTP que usam o identificador HINTERNET retornado são executadas de forma síncrona. Quando esse sinalizador é definido, o chamador precisa especificar uma função de retorno de chamada por meio de WinHttpSetStatusCallback.
WINHTTP_FLAG_SECURE_DEFAULTS
 Quando esse sinalizador for definido, o WinHttp exigirá o uso do TLS 1.2 ou mais recente. Se o chamador tentar habilitar versões mais antigas do TLS definindo WINHTTP_OPTION_SECURE_PROTOCOLS, ele falhará com ERROR_ACCESS_DENIED. Além disso, o fallback do TLS será desabilitado. Observe que definir esse sinalizador também define o sinalizador WINHTTP_FLAG_ASYNC.

Retornar valor

Retorna um identificador de sessão válido se tiver êxito ou NULL caso contrário. Para recuperar 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_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)

Comentários

É altamente recomendável que você use WinHTTP no modo assíncrono (ou seja, quando WINHTTP_FLAG_ASYNC tiver sido definido em WinHttpOpen, para que o uso do HINTERNET retornado se torne assíncrono). O valor retornado indica êxito ou falha. Para recuperar informações de erro estendidas, chame GetLastError.

A função WinHttpOpen é a primeira das funções WinHTTP chamadas por um aplicativo. Ele inicializa estruturas de dados WinHTTP internas e se prepara para chamadas futuras do aplicativo. Quando o aplicativo terminar de usar as funções WinHTTP, ele deverá chamar WinHttpCloseHandle para liberar o identificador de sessão e todos os recursos associados.

O aplicativo pode fazer qualquer número de chamadas para WinHttpOpen, embora uma única chamada normalmente seja suficiente. Cada chamada para WinHttpOpen abre um novo contexto de sessão. Como os dados do usuário não são compartilhados entre vários contextos de sessão, um aplicativo que faz solicitações em nome de vários usuários deve criar uma sessão separada para cada usuário, de modo a não compartilhar cookies específicos do usuário e o estado de autenticação. O aplicativo deve definir comportamentos separados para cada instância WinHttpOpen , como servidores proxy diferentes configurados para cada uma.

Depois que o aplicativo de chamada terminar de usar o identificador HINTERNET retornado por WinHttpOpen, ele deverá ser fechado usando a função WinHttpCloseHandle .

Nota Para Windows XP e Windows 2000, consulte Requisitos de tempo de execução.
 

Exemplos

O código de exemplo a seguir mostra como recuperar o valor de tempo limite de conexão padrã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.

Confira também

Sobre os Serviços HTTP do Microsoft Windows (WinHTTP)

Versões do WinHTTP

WinHttpCloseHandle