Export (0) Print
Expand All
1 out of 4 rated this helpful - Rate this topic

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.

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

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

Error CodeDescription
ERROR_WINHTTP_INCORRECT_HANDLE_STATE

The requested operation cannot be carried out because the handle supplied is not in the correct state.

ERROR_WINHTTP_INCORRECT_HANDLE_TYPE

The type of handle supplied is incorrect for this operation.

ERROR_WINHTTP_INTERNAL_ERROR

An internal error has occurred.

ERROR_NOT_ENOUGH_MEMORY

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.

Note  When using Passport authentication and responding to a 407 status code, a WinHTTP application must use WinHttpSetOption to provide proxy credentials rather than WinHttpSetCredentials. This is only true when using Passport authentication; in all other circumstances, use WinHttpSetCredentials, because WinHttpSetOption is less secure.

Note  For Windows XP and Windows 2000, see the Run-Time Requirements section of the WinHttp start page.

Requirements

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]

Redistributable

WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000.

Header

Winhttp.h

Library

Winhttp.lib

DLL

Winhttp.dll

See also

About Microsoft Windows HTTP Services (WinHTTP)
Authentication in WinHTTP
WinHttpOpen
WinHttpOpenRequest
WinHttpConnect
WinHttpQueryAuthSchemes
WinHttpCloseHandle
WinHTTP Versions

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.