Função WinHttpSetCredentials (winhttp.h)

Artigo
08/27/2023

A função WinHttpSetCredentials passa as credenciais de autorização necessárias para o servidor.

Sintaxe

WINHTTPAPI BOOL WinHttpSetCredentials(
  [in] HINTERNET hRequest,
  [in] DWORD     AuthTargets,
  [in] DWORD     AuthScheme,
  [in] LPCWSTR   pwszUserName,
  [in] LPCWSTR   pwszPassword,
  [in] LPVOID    pAuthParams
);

Parâmetros

[in] hRequest

Identificador HINTERNET válido retornado por WinHttpOpenRequest.

[in] AuthTargets

Um inteiro sem sinal que especifica um sinalizador que contém o destino de autenticação. Pode ser um dos valores na tabela a seguir.

Valor	Significado
WINHTTP_AUTH_TARGET_SERVER	As credenciais são passadas para um servidor.
WINHTTP_AUTH_TARGET_PROXY	As credenciais são passadas para um proxy.

[in] AuthScheme

Um inteiro sem sinal que especifica um sinalizador que contém o esquema de autenticação. Deve ser um dos esquemas de autenticação com suporte retornados de WinHttpQueryAuthSchemes. A tabela a seguir identifica os valores possíveis.

Valor	Significado
WINHTTP_AUTH_SCHEME_BASIC	Use a autenticação básica.
WINHTTP_AUTH_SCHEME_NTLM	Use a autenticação NTLM.
WINHTTP_AUTH_SCHEME_PASSPORT	Use a autenticação de passaporte.
WINHTTP_AUTH_SCHEME_DIGEST	Use a autenticação de resumo.
WINHTTP_AUTH_SCHEME_NEGOTIATE	Seleciona entre a autenticação NTLM e Kerberos.

[in] pwszUserName

Ponteiro para uma cadeia de caracteres que contém um nome de usuário válido.

[in] pwszPassword

Ponteiro para uma cadeia de caracteres que contém uma senha válida. A senha pode estar em branco.

[in] pAuthParams

Esse parâmetro é reservado e deve ser NULL.

Valor retornado

Retorna TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, chame GetLastError. A tabela a seguir identifica os códigos de erro retornados.

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

As credenciais definidas por WinHttpSetCredentials são usadas apenas para uma única solicitação; O WinHTTP não armazena essas credenciais em cache para uso em solicitações subsequentes. Como resultado, os aplicativos devem ser gravados para que possam responder a vários desafios. Se uma conexão autenticada for reutilizada, as solicitações subsequentes não poderão ser contestadas, mas seu código deverá ser capaz de responder a um desafio a qualquer momento.

Para obter um código de exemplo que ilustra o uso de WinHttpSetCredentials, consulte Autenticação no WinHTTP.

Nota Ao usar a autenticação do Passport e responder a um código 407 status, um aplicativo WinHTTP 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, pois WinHttpSetOption é menos seguro.

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

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.