| |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwVersion |
|
| ); |
The Connect method is used to establish a connection
with the specified server.
Parameters
- lpszRemoteHost
- The name of the server to connect to. This
may be a fully-qualified domain name or an IP address.
- nRemotePort
- The port number the server is listening on. A value of
zero specifies that the default port number should be used. For
standard connections, the default port number is 80. For secure
connections, the default port number is 443.
- 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. If the server
does not support the keep-alive option, 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. |
| 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_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. |
| 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 amounts of data
over fast network connections. |
- dwVersion
- 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. The HTTPVERSION macro
can be used to create a version value and the following values are
defined:
| 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_09 |
The client should use the original one-line protocol which
includes no version number and no request header block. This
version has been deprecated and should only be used with legacy
servers which do not support the protocol standard. This version
of the protocol does not support virtual hosts and is not
supported by most modern web services. |
| 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. |
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
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
Connect 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.
Under some circumstances, a server may forcibly close or abort
a connection if the request fails. For example, this can happen when a
malformed request is submitted to the server or a server-side error
occurs. When this happens, the application will need to disconnect
from the server and establish a new connection, even if the keep-alive
option has been specified.
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
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.
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
ConnectUrl,
Disconnect,
IsConnected,
ProxyConnect
|
|