| |
| BOOL ProxyConnect( |
| |
UINT nProxyType, |
|
| |
LPCTSTR lpszProxyHost, |
|
| |
UINT nProxyPort, |
|
| |
LPCTSTR lpszProxyUser, |
|
| |
LPCTSTR lpszProxyPassword, |
|
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwVersion, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| ); |
| BOOL ProxyConnect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwVersion, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| ); |
The ProxyConnect method establishes 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:
| Constant |
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:
| Constant |
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_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_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 either the SSL or
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 version value.
- hEventWnd
- The handle to the event notification window. This window
receives messages which notify the client of various asynchronous
network events that occur. If this argument is NULL, then the
client session will be blocking and no network events will be sent
to the client.
- uEventMsg
- The message identifier that is used when an asynchronous
network event occurs. This value should be greater than WM_USER as
defined in the Windows header files. If the hEventWnd
argument is NULL, this argument should be specified as
WM_NULL.
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 use of Windows event notification messages has been deprecated
and may be unavailable in future releases. It was designed for use in
legacy single-threaded applications and requires the application to
have a message pump to process event messages. It should not be used
with applications which are designed to execute as a service or those
which do not have a graphical user interface.
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 ProxyConnect in that thread. If
the application requires multiple simultaneous connections, it is
recommended you create a worker thread for each client session.
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
method 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.
If you specify an event notification window, then the client
session will be asynchronous. When a message is posted to the
notification window, the low word of the lParam parameter
contains the event identifier. The high word of lParam
contains the low word of the error code, if an error has occurred.
The wParam parameter contains the client handle. One or more
of the following event identifiers may be sent:
| Constant |
Description |
| HTTP_EVENT_CONNECT |
The connection to the server has completed. The high
word of the lParam parameter should be checked, since this
notification message will be posted if an error has
occurred. |
| HTTP_EVENT_DISCONNECT |
The server has closed the connection to the client. The
client should read any remaining data and disconnect. |
| HTTP_EVENT_READ |
Data is available to read by the calling process. No
additional messages will be posted until the client has read at
least some of the data. This event is only generated if the
client is in asynchronous mode. |
| HTTP_EVENT_WRITE |
The client can now write data. This notification is sent
after a connection has been established, or after a previous
attempt to write data has failed because it would result in a
blocking operation. This event is only generated if the client is
in asynchronous mode. |
| HTTP_EVENT_TIMEOUT |
The network operation has exceeded the specified timeout
period. The client application may attempt to retry the
operation, or may disconnect from the server and report an error
to the user. |
| HTTP_EVENT_CANCEL |
The current operation has been canceled. Under most
circumstances the client should disconnect from the server and
re-connect if needed. After an operation has been canceled, the
server may abort the connection or refuse to accept further
commands from the client. |
| HTTP_EVENT_COMMAND |
A command has been issued by the client and the server
response has been received and processed. This event can be used
to log the result codes and messages returned by the server in
response to actions taken by the client. |
| HTTP_EVENT_PROGRESS |
The client is in the process of sending or receiving data
from the server. This event is called periodically during a
transfer so that the client can update any user interface
components such as a status control or progress bar. |
| HTTP_EVENT_REDIRECT |
This event is generated when a the server indicates that the
requested resource has been moved to a new location. The new
resource location may be on the same server, or it may be located
on another server. |
To cancel asynchronous notification and return the client to a
blocking mode, use the DisableEvents method.
It is recommended that you only establish an asynchronous
connection if you understand the implications of doing so. In most
cases, it is preferable to create a synchronous connection and create
threads for each additional session if more than one active client
session is required.
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.
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: cstools10.h
Import Library: cshtpv10.lib
Unicode: Implemented as Unicode and ANSI versions.
See Also
Connect,
Disconnect,
IsConnected
|
|