WinHttpSetOption function

The WinHttpSetOption function sets an Internet option.


BOOL WINAPI WinHttpSetOption(
  _In_ HINTERNET hInternet,
  _In_ DWORD     dwOption,
  _In_ LPVOID    lpBuffer,
  _In_ DWORD     dwBufferLength


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.

Return value

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

Error CodeDescription

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.


A request to WinHttpQueryOption or WinHttpSetOption specified an invalid option value.


A parameter is not valid.

This value will be returned if WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL is set to a value lower than 15000.


The requested option cannot be set, only queried.


A parameter is not valid.

This value will be returned if WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL is set to a value lower than 15000.


Not enough memory was available to complete the requested operation. (Windows error code)



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.


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]


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







See also

Option Flags
Authentication in WinHTTP
WinHTTP Versions