BOOL ConnectUrl(
	LPCTSTR lpszUrl,
	UINT nTimeout,
	DWORD dwOptions
);

The ConnectUrl method establishes a connection with the specified server using a URL.

Parameters

lpszUrl

A null-terminated string which specifies the URL for the server. The URL must follow the conventions for the Hypertext Transfer Protocol and may specify either a standard or secure connection, alternate port number, username, password and optional working directory.

nTimeout

The number of seconds that the client will wait for a response from the server before failing the current operation.

dwOptions

An unsigned integer that specifies one or more options. This parameter 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. When connected to an HTTP 1.0 or earlier server, this directive may be ignored.
HTTP_OPTION_KEEPALIVE	This instructs the server to maintain a persistent connection between requests. This can improve performance because it eliminates the need to establish a separate connection for each resource that is requested.
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_ERRORDATA	This option specifies the client should return the content of an error response from the server, rather than returning an error code. Note that this option will disable automatic resource redirection, and should not be used with HTTP_OPTION_REDIRECT.
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. An application can provide its own custom user agent value using the SetHeader method.
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. This option will always establish a secure connection with the server. The value of the dwVersion parameter will be ignored when this option is used.
HTTP_OPTION_TUNNEL	This option specifies that a tunneled TCP connection and/or port-forwarding is being used to establish the connection to the server. This changes the behavior of the client with regards to internal checks of the destination IP address and remote port number, default capability selection and how the connection is established.
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 connections using the TLS protocol.
HTTP_OPTION_SECURE	This option specifies the client should attempt to establish a secure connection with the server. The server must support secure connections using the TLS protocol and the client will default to using TLS 1.2 or later. If HTTP_PORT_DEFAULT is specified as the remote port, this option will automatically change the port number to use HTTP_PORT_SECURE instead.
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. Although this option may permit connections with servers which do not support current standards, avoid using it unless absolutely necessary. Some servers may reject the connection if the client offers to use TLS 1.0, even when TLS 1.2 or later is also supported.
HTTP_OPTION_FREETHREAD	This option specifies that this instance of the class may be used by any thread, and is not limited to the thread which created it. The application is responsible for ensuring that access to the class instance is synchronized across multiple threads.
HTTP_OPTION_HIRES_TIMER	This option specifies the elapsed time for data transfers should be returned in milliseconds instead of seconds. This will return more accurate transfer times for smaller files being uploaded or downloaded using fast network connections.

Return Value

If the method succeeds, the return value is non-zero. If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The ConnectUrl method uses an HTTP URL to establish a connection with a server. The URL must be in the following format:

[http|https]://[username : password] @] hostname [:port] / [path / ...] [filename]

If no user name and password is provided, then the client session will be authenticated as an anonymous user. The URL scheme will always determine if the connection is secure, not the option. In other words, if the "http" scheme is used and the HTTP_OPTION_SECURE option is specified, that option will be ignored. To establish a secure connection, the "https" scheme must be specified. The ValidateUrl method can be used to verify that a URL is valid prior to calling this method.

The ConnectUrl method is designed to provide a simpler, more convenient interface to establishing a connection with a server. However, complex connections such as those using a specific proxy server or a secure connection which uses a client certificate will require the program to use the lower-level connection methods. If you only need to upload or download a file using a URL, then refer to the UploadFile and DownloadFile methods.

This method will block the current thread until a connection has been established or the timeout period has elapsed. To prevent it from blocking the main user interface thread, the application should create a background worker thread and establish a connection by calling the ConnectUrl method in that thread. If the application requires multiple simultaneous connections, it is recommended you create a worker thread for each connection.

Most applications should use HTTP_VERSION_DEFAULT as the value for the dwVersion parameter. This will default to an appropriate version for the Windows platform and 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 the HTTP_OPTION_KEEPALIVE option is specified and the server does not support persistent connections, the client will automatically reconnect when each resource is requested. Although it will not provide any performance benefits, this allows the option to be used with all servers. This option is automatically enabled when using HTTP/2.

If your application specifies the HTTP_OPTION_HTTP2 option, 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 Windows do not support the features required for a secure HTTP/2 connection. If 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 method will fail and return FALSE.

Specifying the HTTP_OPTION_FREETHREAD option enables any thread to invoke methods in the class instance, regardless of which thread created it. It is important to note that this option disables certain internal safety checks may result in unexpected behavior unless access to the class instance is synchronized.

Example

CHttpClient httpClient;

if (!httpClient.ConnectUrl(_T("https://example.com/")))
{
    httpClient.ShowError();
    return;
}

Requirements

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

See Also

Connect, Disconnect, DownloadFile, UploadFile, ValidateUrl

Copyright © 2025 Catalyst Development Corporation. All rights reserved.