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.
The dwOptions argument can be used to specify the threading
model that is used by the class when a connection is established. By
default, the client session is initially attached to the thread that
created it. From that point on, until the connection is terminated,
only the owner may invoke methods in that instance of the class. The
ownership of the class instance may be transferred from one thread to
another using the AttachThread method.
Specifying the HTTP_OPTION_FREETHREAD option enables any thread to
call methods in any instance of the class, regardless of which thread
created it. It is important to note that this option disables certain
internal safety checks which are performed by the class and may
result in unexpected behavior unless access to the class instance is
synchronized. If one thread calls a method in the class, it must
ensure that no other thread will call another method at the same time
using the same instance.
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
function will fail and return INVALID_CLIENT.