WinHttpSetOption Function (Windows)

WinHttpSetOption Function

The WinHttpSetOption function sets an Internet option.

Syntax

C++

BOOL WINAPI WinHttpSetOption(
  __in  HINTERNET hInternet,
  __in  DWORD dwOption,
  __in  LPVOID lpBuffer,
  __in  DWORD dwBufferLength
);

Parameters

hInternet [in]

The HINTERNET handle on which to set data. Be aware that this can be either a Session handle or a Request handle, depending on what option is being set. For more information about how to determine which handle is appropriate to use in setting a particular option, see the Option Flags.

dwOption [in]

An unsigned long integer value that contains the Internet option to set. This can be one of the Option Flags values.

lpBuffer [in]

A pointer to a buffer that contains the option setting.

dwBufferLength [in]

Unsigned long integer value that contains the length of the lpBuffer buffer. The length of the buffer is specified in characters for the following options; for all other options, the length is specified in bytes.

WINHTTP_OPTION_USER_NAME
WINHTTP_OPTION_PASSWORD
WINHTTP_OPTION_PROXY_USER_NAME
WINHTTP_OPTION_PROXY_PASSWORD
WINHTTP_OPTION_USER_AGENT

Return Value

Returns TRUE if successful, or FALSE otherwise. For extended error information, call GetLastError. Among the error codes returned are the following

Error Code	Description
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_WINHTTP_INVALID_OPTION	A request to WinHttpQueryOption or WinHttpSetOption specified an invalid option value.
ERROR_WINHTTP_OPTION_NOT_SETTABLE	The requested option cannot be set, only queried.
ERROR_NOT_ENOUGH_MEMORY	Not enough memory was available to complete the requested operation. (Windows error code)

Remarks

Credentials passed to WinHttpSetOption could be unexpectedly sent in plaintext. It is strongly recommended that you use WinHttpQueryAuthSchemes and WinHttpSetCredentials instead of WinHttpSetOption for setting credentials.

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

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.

GetLastError returns the error ERROR_INVALID_PARAMETER if an option flag is specified that cannot be set.

For more information and code examples that show the use of WinHttpSetOption, see Authentication in WinHTTP.

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
Minimum supported server	Windows Server 2003, Windows 2000 Server with SP3
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

Syntax

Parameters

Return Value

Remarks

Requirements

See Also