Función WinHttpSetCredentials (winhttp.h)

Artículo
08/27/2023

La función WinHttpSetCredentials pasa las credenciales de autorización necesarias al servidor.

Sintaxis

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 devuelto por WinHttpOpenRequest.

[in] AuthTargets

Entero sin signo que especifica una marca que contiene el destino de autenticación. Puede ser uno de los valores de la tabla siguiente.

Value	Significado
WINHTTP_AUTH_TARGET_SERVER	Las credenciales se pasan a un servidor.
WINHTTP_AUTH_TARGET_PROXY	Las credenciales se pasan a un proxy.

[in] AuthScheme

Entero sin signo que especifica una marca que contiene el esquema de autenticación. Debe ser uno de los esquemas de autenticación admitidos devueltos desde WinHttpQueryAuthSchemes. En la tabla siguiente se identifican los valores posibles.

Value	Significado
WINHTTP_AUTH_SCHEME_BASIC	Use la autenticación básica.
WINHTTP_AUTH_SCHEME_NTLM	Use la autenticación NTLM.
WINHTTP_AUTH_SCHEME_PASSPORT	Use la autenticación de Passport.
WINHTTP_AUTH_SCHEME_DIGEST	Use la autenticación implícita.
WINHTTP_AUTH_SCHEME_NEGOTIATE	Selecciona entre la autenticación NTLM y Kerberos.

[in] pwszUserName

Puntero a una cadena que contiene un nombre de usuario válido.

[in] pwszPassword

Puntero a una cadena que contiene una contraseña válida. La contraseña puede estar en blanco.

[in] pAuthParams

Este parámetro está reservado y debe ser NULL.

Valor devuelto

Devuelve TRUE si es correcto o FALSE en caso contrario. Para obtener información de error extendida, llame a GetLastError. En la tabla siguiente se identifican los códigos de error devueltos.

Código de error	Descripción
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	No se puede llevar a cabo la operación solicitada porque el controlador suministrado no está en el estado correcto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	El tipo de identificador proporcionado es incorrecto para esta operación.
ERROR_WINHTTP_INTERNAL_ERROR	Se ha producido un error interno.
ERROR_NOT_ENOUGH_MEMORY	No había suficiente memoria disponible para completar la operación solicitada (código de error de Windows).

Comentarios

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando se ha establecido WINHTTP_FLAG_ASYNC en WinHttpOpen), esta función funciona de forma sincrónica. El valor devuelto indica éxito o error. Para obtener información de error extendida, llame a GetLastError.

Las credenciales establecidas por WinHttpSetCredentials solo se usan para una sola solicitud; WinHTTP no almacena en caché estas credenciales para su uso en solicitudes posteriores. Como resultado, las aplicaciones deben escribirse para que puedan responder a varios desafíos. Si se vuelve a usar una conexión autenticada, no se pueden impugnar las solicitudes posteriores, pero el código debe poder responder a un desafío en cualquier momento.

Para obtener código de ejemplo que ilustra el uso de WinHttpSetCredentials, consulte Autenticación en WinHTTP.

Nota Al usar la autenticación de Passport y responder a un código de estado 407, una aplicación WinHTTP debe usar WinHttpSetOption para proporcionar credenciales de proxy en lugar de WinHttpSetCredentials. Esto solo es cierto cuando se usa la autenticación de Passport; en todas las demás circunstancias, use WinHttpSetCredentials, porque WinHttpSetOption es menos seguro.

Nota Para Windows XP y Windows 2000, consulta la sección Requisitos en tiempo de ejecución de la página de inicio de WinHttp.

Requisitos


Cliente mínimo compatible	Windows XP, Windows 2000 Professional con SP3 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003, Windows 2000 Server con SP3 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winhttp.h
Library	Winhttp.lib
Archivo DLL	Winhttp.dll
Redistribuible	WinHTTP 5.0 e Internet Explorer 5.01 o posterior en Windows XP y Windows 2000.