WinHttpSetCredentials function (winhttp.h)
The WinHttpSetCredentials function passes the required authorization credentials to the server.
Syntax
WINHTTPAPI BOOL WinHttpSetCredentials(
[in] HINTERNET hRequest,
[in] DWORD AuthTargets,
[in] DWORD AuthScheme,
[in] LPCWSTR pwszUserName,
[in] LPCWSTR pwszPassword,
[in] LPVOID pAuthParams
);
Parameters
[in] hRequest
Valid HINTERNET handle returned by WinHttpOpenRequest.
[in] AuthTargets
An unsigned integer that specifies a flag that contains the authentication target. Can be one of the values in the following table.
Value | Meaning |
---|---|
|
Credentials are passed to a server. |
|
Credentials are passed to a proxy. |
[in] AuthScheme
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.
[in] pwszUserName
Pointer to a string that contains a valid user name.
[in] pwszPassword
Pointer to a string that contains a valid password. The password can be blank.
[in] pAuthParams
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.
Error Code | Description |
---|---|
|
The requested operation cannot be carried out because the handle supplied is not in the correct state. |
|
The type of handle supplied is incorrect for this operation. |
|
An internal error has occurred. |
|
Not enough memory was available to complete the requested operation (Windows error code). |
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
Requirement | Value |
---|---|
Minimum supported client | Windows XP, Windows 2000 Professional with SP3 [desktop apps only] |
Minimum supported server | Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only] |
Target Platform | Windows |
Header | winhttp.h |
Library | Winhttp.lib |
DLL | Winhttp.dll |
Redistributable | WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000. |