Função WinHttpOpen (winhttp.h)

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.

[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.

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.

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 .

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

Confira também

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

Versões do WinHTTP

WinHttpCloseHandle