| |
| HCLIENT WINAPI HttpConnect(
|
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwVersion, |
|
| |
LPSECURITYCREDENTIALS lpCredentials |
|
| );
|
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 that 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 that 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 that 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 feature selection and how the connection is
established. |
| HTTP_OPTION_TRUSTEDSITE |
This option specifies that 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 that 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_FREETHREAD |
This option specifies that 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. |
- 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.
- lpCredentials
- Pointer to credentials structure SECURITYCREDENTIALS. This parameter
is only used if the HTTP_OPTION_SECURE option is specified for the
connection. This parameter may be NULL, in which case no client
credentials will be provided to the server. If client credentials
are required, the fields dwSize, lpszCertStore, and
lpszCertName must be defined, while other fields may be left
undefined. Set dwSize to the size of the
SECURITYCREDENTIALS structure.
Return Value
If the function succeeds, the return value is a handle to a
client session. If the function fails, the return value is
INVALID_CLIENT. To get extended error information, call
HttpGetLastError.
Remarks
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.
Requirements
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use cshtpav7.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
HttpAsyncConnect, HttpAsyncProxyConnect, HttpDisconnect, HttpInitialize, HttpProxyConnect
|
|