| |
| BOOL ProxyConnect( |
| |
UINT nProxyType, |
|
| |
LPCTSTR lpszProxyHost, |
|
| |
UINT nProxyPort, |
|
| |
LPCTSTR lpszProxyUser, |
|
| |
LPCTSTR lpszProxyPassword, |
|
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwVersion |
|
| ); |
| BOOL ProxyConnect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwVersion |
|
| ); |
The ProxyConnect method is used to establish a connection
through a proxy server.
Parameters
- nProxyType
- An unsigned integer which specifies the type of proxy that the
client is connecting to. The supported proxy server types are as
follows:
| 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. |
- lpszProxyHost
- A pointer to a string which specifies the proxy
server host name or IP address. This argument 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.
- nProxyPort
- The port number that the proxy server is listening for
connections on. A value of zero specifies that the default port
number 80 should be used. Note that in most cases, a proxy server
is not configured to use the default port. This argument 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.
- lpszProxyUser
- A pointer to a string which specifies the user
name that will be used to authenticate the client session to the
proxy server. If the server does not require user authentication,
then a NULL pointer may be passed in this argument.
- lpszProxyPassword
- A pointer to a string which specifies the
password that will be used to authenticate the client session to
the proxy server. If the server does not require user
authentication, then a NULL pointer may be passed in this
argument.
- lpszRemoteHost
- A pointer to a string which specifies the name
of the server to connect to through the proxy server. 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. |
| 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_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. 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_SECURE |
This option specifies the client should attempt to
establish a secure connection with the server. Note that the
server must support secure connections using the
TLS protocol. |
| 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. |
| HTTP_OPTION_FREETHREAD |
This option specifies the handle returned by this
function 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 handle 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.0 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. |
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
ProxyConnect method in that thread. If the application
requires multiple simultaneous connections, it is recommended you
create a worker thread for each connection.
If the HTTP_PROXY_WINDOWS proxy type is specified, then the proxy
configuration for the local system is used. If no proxy
server has been defined, then the proxy-related parameters will be
ignored and the function will establish a connection directly to the
server. The second form of the ProxyConnect method always
uses the the system configuration to determine if the connection
should be made through a proxy server, which is why there are no
parameters such as the proxy type or proxy server name.
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 it is released, only the
owner may call functions using that handle. The ownership of the
handle may be transferred from one thread to another using the
HttpAttachThread function.
Specifying the HTTP_OPTION_FREETHREAD option enables any thread to
call any function using the 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 handle is
synchronized. If one thread calls a function in the library, it must
ensure that no other thread will call another function at the same
time using the same handle.
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.
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 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 a value of zero.
Example
CHttpClient *pClient = new CHttpClient();
// Establish a connection using the default proxy server
// configuration for the local system
if (pClient->ProxyConnect(strHostName) == FALSE)
{
pClient->ShowError();
return;
}
// Retrieve the resource from the server and store it
// in the string buffer
nResult = pClient->GetData(strResource, strBuffer);
if (nResult == HTTP_ERROR)
pClient->ShowError();
pClient->Disconnect();
delete pClient;
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,
ConnectUrl,
Disconnect,
IsConnected
|
|