Função WinHttpSetOption (winhttp.h)

Artigo
03/13/2024

A função WinHttpSetOption define uma opção de Internet.

Sintaxe

WINHTTPAPI BOOL WinHttpSetOption(
  [in] HINTERNET hInternet,
  [in] DWORD     dwOption,
  [in] LPVOID    lpBuffer,
  [in] DWORD     dwBufferLength
);

Parâmetros

[in] hInternet

O identificador HINTERNET no qual definir dados. Lembre-se de que isso pode ser um identificador de sessão ou um identificador de solicitação, dependendo de qual opção está sendo definida. Para obter mais informações sobre como determinar qual identificador é apropriado para usar na configuração de uma opção específica, consulte Os Sinalizadores de Opção.

[in] dwOption

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

[in] lpBuffer

Um ponteiro para um buffer que contém a configuração de opção.

[in] dwBufferLength

Valor inteiro longo sem sinal que contém o comprimento do buffer lpBuffer . O comprimento do buffer é especificado em caracteres para as opções a seguir; para todas as outras opções, o comprimento é especificado em bytes.

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_WINHTTP_INVALID_OPTION	Uma solicitação para WinHttpQueryOption ou WinHttpSetOption especificou um valor de opção inválido.
ERROR_INVALID_PARAMETER	Um parâmetro não é válido. Esse valor será retornado se WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL for definido como um valor inferior a 15000.
ERROR_WINHTTP_OPTION_NOT_SETTABLE	A opção solicitada não pode ser definida, apenas consultada.
ERROR_INVALID_PARAMETER	Um parâmetro não é válido. Esse valor será retornado se WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL for definido como um valor inferior a 15000.
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

As credenciais passadas para WinHttpSetOption podem ser enviadas inesperadamente em texto não criptografado. É altamente recomendável que você use WinHttpQueryAuthSchemes e WinHttpSetCredentials em vez de WinHttpSetOption para definir credenciais.

Nota No entanto, ao usar a autenticação passport, um aplicativo WinHTTP respondendo a um código de status 407 deve usar WinHttpSetOption para fornecer credenciais de proxy em vez de WinHttpSetCredentials. Isso só é verdadeiro ao usar a autenticação do Passport; em todas as outras circunstâncias, use WinHttpSetCredentials.

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 erro ERROR_INVALID_PARAMETER se um sinalizador de opção for especificado que não pode ser definido.

Para obter mais informações e exemplos de código que mostram o uso de WinHttpSetOption, consulte Autenticação no WinHTTP.

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

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.