HTTPCONNECTION

The HTTPCONNECTION structure provides additional information used when submitting a request to the server.

typedef struct _HTTPCONNECTION
{
    DWORD   dwSize;
    DWORD   dwOptions;
    DWORD   dwVersion;
    UINT    nTimeout;
    UINT    nEncoding;
    UINT    nProxyType;
    UINT    nProxyPort;
    UINT    nAuthType;
    LPCTSTR lpszProxyServer;
    LPCTSTR lpszProxyUser;
    LPCTSTR lpszProxyPassword;
    LPCTSTR lpszUserAgent;
    LPCTSTR lpszUserName;
    LPCTSTR lpszPassword;
    LPCTSTR lpszContentType;
    LPCTSTR lpszHeaders;
    LPSECURITYCREDENTIALS lpCredentials;
} HTTPCONNECTION, *LPHTTPCONNECTION;

Members

dwSize

The size of this structure in bytes. If this member is not initialized to the correct value, the structure will be considered invalid.

dwOptions

A bitmask of supported options. The value of this structure member is constructed by using a bitwise operator with any of the following values:

Value Description

HTTP_OPTION_NOCACHE This instructs the server to not return a cached copy of the resource.

HTTP_OPTION_REDIRECT This option specifies the client should automatically handle resource redirection. If the server indicates that the requested resource has moved to a new location, the client will close the current connection and request the resource from the new location. Note that it is possible that the redirected resource will be located on a different server.

HTTP_OPTION_PROXY This option specifies the client should use the default proxy configuration for the local system. If the system is configured to use a proxy server, then the connection will be automatically established through that proxy; otherwise, a direct connection to the server is established. The local proxy configuration can be changed in the system settings or control panel.

HTTP_OPTION_NOUSERAGENT This option specifies the client should not include a User-Agent header with any requests made during the session. The user agent is a string which is used to identify the client application to the server. If this option is set, the value of the lpszUserAgent member will be ignored.

HTTP_OPTION_HTTP2 This option specifies the client should attempt a HTTP/2 connection with the server. If a connection cannot be established using HTTP/2 the client will attempt to connect using an earlier version of the protocol. The value of the dwVersion member will be ignored when this option is used.

HTTP_OPTION_TRUSTEDSITE This option specifies the server is trusted. The server certificate will not be validated and the connection will always be permitted. This option only affects secure connections.

HTTP_OPTION_SECURE This option specifies the client should attempt to establish a secure connection with the server even if the request URL does not use the https:// scheme. If this option is not specified, the type of connection depends on the URL scheme provided when submitting the request.

HTTP_OPTION_SECURE_FALLBACK This option specifies the client should permit the use of less secure cipher suites for compatibility with legacy servers. If this option is specified, the client will allow connections using TLS 1.0 and cipher suites that use RC4, MD5 and SHA1.

HTTP_OPTION_PREFER_IPV6 This option specifies the client should prefer the use of IPv6 if the server hostname can be resolved to both an IPv6 and IPv4 address. This option is ignored if the local system does not have IPv6 enabled, or when the hostname can only be resolved to an IPv4 address. If the server hostname can only be resolved to an IPv6 address, the client will attempt to establish a connection using IPv6 regardless if this option has been specified.

dwVersion

A value which specifies the requested protocol version used when sending requests to the server. The high word should specify the major version, and the low word should specify the minor version number. If this value is zero, the default protocol version will be used. The HTTPVERSION macro can be used to create a version value, or the following values can be used:

Value Description

HTTP_VERSION_DEFAULT The client should use the default protocol version for this session. This is the same as specifying HTTP_VERSION_11 and is recommended to ensure the broadest compatibility with most servers.

HTTP_VERSION_10 The client should use the HTTP/1.0 protocol standard originally defined in RFC 1945. This version of the protocol supports the use of request header blocks, however it does not support persistent connections or chunked data and has limited cache control mechanisms.

HTTP_VERSION_11 The client should use the HTTP/1.1 protocol standard defined in RFC 2616 and RFC 7230. This is the most widely used version of the protocol and is the default for client connections. It is recommended most applications use this version.

HTTP_VERSION_20 The client should use the HTTP/2 protocol standard defined in RFC 7540. This protocol version is a significant change from previous versions and can provide improved performance with header compression and optimizing how requests are serviced. If the client or server does not support HTTP/2, the client will automatically attempt to use an earlier version of the protocol.

nTimeout

The number of seconds that the client will wait for a response from the server before failing the operation. If this value is zero, a default timeout period of 20 seconds will be used.

nEncoding

A value which specifies the content encoding type for the request. If the value is zero, no encoding will be used. The following values are defined:

Value Description

HTTP_ENCODING_NONE No encoding will be applied to the content of a request and no default content type will be specified. This encoding type should be used with REST APIs and other services which expect XML or JSON request payloads.

HTTP_ENCODING_URL Non-printable and extended ASCII characters will be encoded so they can be safely used with URLs and form data. Encoded characters will be represented by a percent symbol prefix, followed by a two digit hexadecimal value which represents the ASCII character code. This encoding is typically used with web services which process HTML form data.

HTTP_ENCODING_XML This encoding is identical to URL encoding, except spaces are not encoded. It is used with legacy web services which expect form data in an XML format and cannot process encoded whitespace. This encoding should not be specified for services which use REST APIs.

nProxyType

A value which specifies the type of proxy server the client is connecting to. A value of zero specifies no proxy server is being used and the client should establish a direct connection to the server. The following proxy server types are supported:

Value Description

HTTP_PROXY_NONE A direct connection will be established with the server. When this value is specified the proxy parameters are ignored.

HTTP_PROXY_STANDARD A standard connection is established through the specified proxy server, and all resource requests will be specified using a complete URL. This proxy type should be used with standard connections.

HTTP_PROXY_SECURE A secure connection is established through the specified proxy server. This proxy type should be used with secure connections and the HTTP_OPTION_SECURE option should also be set via the dwOptions parameter.

HTTP_PROXY_WINDOWS The configuration options for the current system should be used. If the system is configured to use a proxy server, then the connection will be automatically established through that proxy; otherwise, a direct connection to the server is established. These settings are the same proxy server settings configured in Windows.

nProxyPort

A value which specifies the port the proxy server will use to accept connections. This value is ignored if the proxy type is set to HTTP_PROXY_NONE or HTTP_PROXY_WINDOWS and no proxy configuration has been specified for the local system.

nAuthType

A value which specifies the type of authentication used to establish the connection. If the value is zero, the client session will not be authenticated. The following values are defined:

Value Description

HTTP_AUTH_NONE No client authentication should be performed. The lpszUserName and lpszPassword members are ignored.

HTTP_AUTH_BASIC The Basic authentication scheme should be used. This option is supported by all servers that support at least version 1.0 of the protocol. The user credentials are not encrypted and Basic authentication should not be used over standard (non-secure) connections. Most web services which use Basic authentication require the connection to be secure.

HTTP_AUTH_BEARER The Bearer authentication scheme should be used. This authentication method does not require a user name and the lpszPassword member must specify the OAuth 2.0 bearer token issued by the service provider. If the access token has expired, the request will fail with an authorization error.

lpszProxyServer

A pointer to a null terminated string which identifies the proxy server which should be used to establish the connection. If this value is ignored if the nProxyType member is zero. If a proxy server type has been been specified, this value cannot be a NULL pointer or an empty string.

lpszProxyUser

A pointer to a null terminated string which specifies the user name used to authenticate the connection to the proxy server. If the proxy server does not require user authentication, this member can be a NULL pointer or an empty string. This member is ignored if the nProxyType member is zero.

lpszProxyPassword

A pointer to a null terminated string which specifies the password used to authenticate the connection to the proxy server. If the proxy server does not require user authentication, this member can be a NULL pointer or an empty string. This member is ignored if the nProxyType member is zero.

lpszUserAgent

A pointer to a null terminated string which identifies the application which is making a request to the server. If this value is NULL or an empty string, a default user agent string will be included with the request. To prevent a user agent from being included with the request, use the HTTP_OPTION_NOUSERAGENT option.

lpszUserName

A pointer to a null terminated string which specifies the user name used to authenticate the client session. This member may be NULL or an empty string if a user name is not required for the specified authentication type.

lpszPassword

A pointer to a null terminated string which specifies the password used to authenticate the client session. This member may be NULL or an empty string if a password is not required for the specified authentication type. If the authentication type is HTTP_AUTH_BEARER, this value must be the bearer token issued by the service provider.

lpszContentType

A pointer to a null terminated string which specifies the MIME content type for the request. If this member is NULL or specifies an empty string, the content type will be automatically determined based on the contents of the request payload. This value will only be used with PUT and POST methods.

lpszHeaders

A pointer to a null terminated string which specifies one or more additional header values which should be included with the request. The string must contain header name and value pairs separated by a colon, and multiple header values must be terminated with a carriage return/linefeed (CRLF) sequence after each value. The header values defined in this string will override any default values.

lpCredentials

A pointer to a SECURITYCREDENTIALS structure. This value is only used if the HTTP_OPTION_SECURE option is specified in the dwOptions member. This member may be NULL, in which case no client credentials will be provided to the server.

Remarks

This structure is used with the SubmitRequest method to provide additional information used to establish a connection with the server. The dwSize member must be initialized to the actual size of the structure in bytes, and all other members should be initialized to a value of zero or NULL. If the structure is not initialized correctly, the function will fail and the last error code will be set to ST_ERROR_INVALID_PARAMETER.

Member values which are zero or NULL pointers will either be ignored or cause the function to use appropriate default values.

If the dwVersion member has a value of zero, the protocol version will default to an appropriate value which ensures the broadest compatibility with most servers. If your application specifies HTTP_VERSION_20, a secure connection using TLS 1.2 or later will always be used. The minimum required platform for HTTP/2 support is Windows 10 (Build 1903) or Windows Server 2019. Earlier versions of the Schannel SSP do not support the features required for a secure HTTP/2 connection.

If your application requests a HTTP/2 connection and the server only accepts earlier versions of the protocol, the client will attempt to automatically downgrade the request to HTTP/1.1. If a connection using an earlier version of the protocol cannot be established, the connection attempt will fail.

If the server requires a secure connection with a client certificate, the CreateSecurityCredentials method can be used to allocate a credentials structure which can be assigned to the lpCredentials member.

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Unicode: Implemented as Unicode and ANSI versions

Members

Remarks

Requirements

See Also