WinHttpSetCredentials function

The WinHttpSetCredentials function passes the required authorization credentials to the server.

Syntax

BOOL WINAPI WinHttpSetCredentials(
  _In_       HINTERNET hRequest,
  _In_       DWORD     AuthTargets,
  _In_       DWORD     AuthScheme,
  _In_       LPCWSTR   pwszUserName,
  _In_       LPCWSTR   pwszPassword,
  _Reserved_ LPVOID    pAuthParams
);

Parameters

hRequest [in]

Valid HINTERNET handle returned by WinHttpOpenRequest.

AuthTargets [in]

An unsigned integer that specifies a flag that contains the authentication target. Can be one of the values in the following table.

Value	Meaning
WINHTTP_AUTH_TARGET_SERVER	Credentials are passed to a server.
WINHTTP_AUTH_TARGET_PROXY	Credentials are passed to a proxy.

 

AuthScheme [in]

An unsigned integer that specifies a flag that contains the authentication scheme. Must be one of the supported authentication schemes returned from WinHttpQueryAuthSchemes. The following table identifies the possible values.

Value	Meaning
WINHTTP_AUTH_SCHEME_BASIC	Use basic authentication.
WINHTTP_AUTH_SCHEME_NTLM	Use NTLM authentication.
WINHTTP_AUTH_SCHEME_PASSPORT	Use passport authentication.
WINHTTP_AUTH_SCHEME_DIGEST	Use digest authentication.
WINHTTP_AUTH_SCHEME_NEGOTIATE	Selects between NTLM and Kerberos authentication.

 

pwszUserName [in]

Pointer to a string that contains a valid user name.

pwszPassword [in]

Pointer to a string that contains a valid password. The password can be blank.

pAuthParams [in]

This parameter is reserved and must be NULL.

Return value

Returns TRUE if successful, or FALSE otherwise. For extended error information, call GetLastError. The following table identifies the error codes returned.

Remarks

Even when WinHTTP is used in asynchronous mode (that is, when WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates synchronously. The return value indicates success or failure. To get extended error information, call GetLastError.

The credentials set by WinHttpSetCredentials are only used for a single request; WinHTTP does not cache these credentials for use in subsequent requests. As a result, applications must be written so that they can respond to multiple challenges. If an authenticated connection is re-used, subsequent requests cannot be challenged, but your code should be able to respond to a challenge at any point.

For sample code that illustrates the use of WinHttpSetCredentials, see Authentication in WinHTTP.

Requirements

See also

About Microsoft Windows HTTP Services (WinHTTP)

Authentication in WinHTTP

WinHttpOpen

WinHttpOpenRequest

WinHttpConnect

WinHttpQueryAuthSchemes

WinHttpCloseHandle

WinHTTP Versions