Fonction WinHttpSetCredentials (winhttp.h)

Article
08/27/2023

La fonction WinHttpSetCredentials transmet les informations d’identification d’autorisation requises au serveur.

Syntaxe

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

Paramètres

[in] hRequest

Handle HINTERNET valide retourné par WinHttpOpenRequest.

[in] AuthTargets

Entier non signé qui spécifie un indicateur qui contient la cible d’authentification. Peut être l’une des valeurs du tableau suivant.

Valeur	Signification
WINHTTP_AUTH_TARGET_SERVER	Les informations d’identification sont transmises à un serveur.
WINHTTP_AUTH_TARGET_PROXY	Les informations d’identification sont transmises à un proxy.

[in] AuthScheme

Entier non signé qui spécifie un indicateur qui contient le schéma d’authentification. Doit être l’un des schémas d’authentification pris en charge retournés par WinHttpQueryAuthSchemes. Le tableau suivant identifie les valeurs possibles.

Valeur	Signification
WINHTTP_AUTH_SCHEME_BASIC	Utilisez l’authentification de base.
WINHTTP_AUTH_SCHEME_NTLM	Utilisez l’authentification NTLM.
WINHTTP_AUTH_SCHEME_PASSPORT	Utilisez l’authentification de passeport.
WINHTTP_AUTH_SCHEME_DIGEST	Utilisez l’authentification digest.
WINHTTP_AUTH_SCHEME_NEGOTIATE	Sélectionne entre l’authentification NTLM et Kerberos.

[in] pwszUserName

Pointeur vers une chaîne qui contient un nom d’utilisateur valide.

[in] pwszPassword

Pointeur vers une chaîne qui contient un mot de passe valide. Le mot de passe peut être vide.

[in] pAuthParams

Ce paramètre est réservé et doit avoir la valeur NULL.

Valeur retournée

Retourne LA valeur TRUE si elle réussit ou FALSE dans le cas contraire. Pour obtenir des informations d’erreur étendues, appelez GetLastError. Le tableau suivant identifie les codes d’erreur retournés.

Code d'erreur	Description
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	L’opération demandée ne peut pas être effectuée, car le handle fourni n’est pas dans l’état correct.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Le type de handle fourni est incorrect pour cette opération.
ERROR_WINHTTP_INTERNAL_ERROR	Une erreur interne s'est produite.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible était insuffisante pour effectuer l’opération demandée (code d’erreur Windows).

Remarques

Même lorsque WinHTTP est utilisé en mode asynchrone (c’est-à-dire, lorsque WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen), cette fonction fonctionne de manière synchrone. La valeur de retour indique la réussite ou l’échec. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Les informations d’identification définies par WinHttpSetCredentials ne sont utilisées que pour une seule requête ; WinHTTP ne met pas en cache ces informations d’identification pour les utiliser dans les requêtes suivantes. Par conséquent, les applications doivent être écrites afin de pouvoir répondre à de multiples défis. Si une connexion authentifiée est réutilisée, les demandes suivantes ne peuvent pas être contestées, mais votre code doit être en mesure de répondre à une contestation à tout moment.

Pour obtenir un exemple de code illustrant l’utilisation de WinHttpSetCredentials, consultez Authentification dans WinHTTP.

Note Lors de l’utilisation de l’authentification Passport et de la réponse à un code 407 status, une application WinHTTP doit utiliser WinHttpSetOption pour fournir des informations d’identification proxy plutôt que WinHttpSetCredentials. Cela est uniquement vrai lors de l’utilisation de l’authentification Passport ; dans toutes les autres circonstances, utilisez WinHttpSetCredentials, car WinHttpSetOption est moins sécurisé.

Note Pour Windows XP et Windows 2000, consultez la section Conditions d’exécution de la page de démarrage WinHttp.

Configuration requise


Client minimal pris en charge	Windows XP, Windows 2000 Professionnel avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003, Windows 2000 Server avec SP3 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winhttp.h
Bibliothèque	Winhttp.lib
DLL	Winhttp.dll
Composant redistribuable	WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000.