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.
| Valor | Significado |
|---|---|
|
Resolve todos os nomes de host diretamente sem um 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.
A configuração de proxy WinHTTP é definida por um desses mecanismos.
|
|
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. |
|
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 |
|---|---|
|
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. |
|
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 |
|---|---|
|
Ocorreu um erro interno. |
|
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 .
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. |