The ConnectUrl method provides a simplified interface which can
be used to establish a connection using a URL. This method can only
be used to establish connections using TCP and does not currently support the
use of URLs to connect with a service which uses UDP. The general format
of the URL should look like this:
[scheme]:// [[username : password] @] hostname [:port] / [path;parameters ...]
This method recognizes most standard URI schemes which use this
format. The host name and port number specified in the URL will be
used to establish a connection and the remaining information will be
discarded. If the URL does not explicitly specify
a port number, the default port number associated with the scheme will
be used as the default value. For example, consider the following:
https://www.example.com
In this example, there is no port number specified; instead, the default
port for the https:// scheme would be used, which is port 443.
The host name www.example.com would be resolved into an IP
address and the connection established on port 443. This method will
also recognize a simpler format which only includes the host name and port
number without a URI scheme, such as:
www.example.com:443
When used in this way, the port number must always be provided.
Without a URI scheme or an explicit port number, the method cannot
determine what port number should be used when establishing the connection.
The same also applies if a custom, non-standard URI scheme is provided which is
not recognized.
If the URI scheme specifies a secure protocol which requires
implicit TLS, this method will automatically enable the
INET_OPTION_SECURE option. For example, providing a URL which uses the
https:// scheme will automatically enable a secure connection
regardless if the dwOptions parameter includes that option. If
a URI scheme is used in conjunction with a port number associated with
a secure service, security will also be enabled for
that connection. For example:
http://www.example.com:443
The standard http:// scheme is used which
does not indicate a secure connection. However, since port 443 is the
standard port designated for a secure HTTP connection, a secure
connection will be enabled by default, even if INET_OPTION_SECURE has
not been specified by the caller. Alternatively, if a custom port
number is specified in the URL or the scheme is not recognized as one
which requires implicit TLS, security options will not be
automatically enabled for the connection.
The host name portion of the URL can be specified as either a domain name
or an IP address. Because an IPv6 address can contain colon characters,
you must enclose the entire address in bracket [] characters. If this is
not done, this method will return an error indicating the port number is
invalid. For example, the URL https://[2001:db8:0:0:1::128]/
uses an IPv6 host address and this would be considered valid. Without the
brackets, this URL would not be accepted.
Important: The URL provided to this method will only be
used to establish a connection with a server. This is a general
purpose method which does not enable support for any particular
application protocol and all implementation details are the
responsibility of your application. If you require higher-level support
for a specific Internet protocol, the SocketTools API provides
comprehensive collection of higher-level classes which can be used
to access those services.
If you use the INET_OPTION_SECURE option to enable a secure
connection, the connection will always use implicit TLS. This means a
secure session will be initiated immediately after the socket
connection has been established with the server. A common example of a
service which uses implicit TLS is the HTTPS protocol. Another type of
secure connection is one that uses explicit TLS. This is when the
client establishes a normal (non-secure) connection with the server
and then explicitly switches to using a secure connection, typically
by sending a command. If the server you are connecting to requires
explicit TLS, you should not specify the INET_OPTION_SECURE option.
Instead, connect without this option and then call the
InetEnableSecurity method when you are ready to initiate the TLS
handshake.
To prevent this method from blocking the main user interface
thread, the application should create a background worker thread and
establish a connection by calling InetConnectUrl in
that thread. If the application requires multiple simultaneous
connections, it is recommended you create a worker thread for each
client session.
The dwOptions argument can be used to specify the threading
model that is used by the library when a connection is established.
By default, the handle is initially attached to the thread that
created it. From that point on, until the handle is released, only the
owner may call methods using that handle. The ownership of the
handle may be transferred from one thread to another using the
InetAttachThread method.
Specifying the INET_OPTION_FREETHREAD option enables any thread to
call any method using the socket handle, regardless of which thread
created it. It is important to note that this option disables certain
internal safety checks which are performed by the library and may
result in unexpected behavior unless access to the socket is
synchronized. If one thread calls a method in the library, it must
ensure that no other thread will call another method at the same
time using the same socket handle.