| |
| 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 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 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.
- 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
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
HttpDisconnect,
HttpInitialize,
HttpProxyConnect
|
|