| |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwVersion, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| ); |
The Connect method is used to establish a connection with the server.
Parameters
- lpszRemoteHost
- A pointer to 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:
| 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_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 using the system 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_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 either the SSL or TLS protocols. |
| 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 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 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
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. |
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 Connect in that thread. If
the application requires multiple simultaneous connections, it is
recommended you create a worker thread for each client session.
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 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.
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
Disconnect,
IsConnected,
ProxyConnect
|
|