| |
Establish a connection with a server.
Syntax
object.Connect( [RemoteHost],
[RemotePort], [UserName], [Password],
[Timeout], [Options] )
Parameters
- RemoteHost
- A string which specifies the host name or IP address of the
server. If this argument is not specified, it defaults to the
value of the HostAddress property if it is defined.
Otherwise, it defaults to the value of the HostName
property.
- RemotePort
- A number which specifies the port to connect to on the server.
If this argument is not specified, it defaults to the value
of the RemotePort property. A value of zero indicates that
the default port number for this service should be used to
establish the connection.
- UserName
- An optional string which specifies a username used to
authenticate the client session. This argument is only required if
access to the resource requires authentication. If this argument is
omitted, it defaults to the value of the UserName property.
An empty string means that no authentication will be
performed.
- Password
- An optional string which specifies the password used to
authenticate the client session. This argument is only required if
access to the resource requires authentication. If this argument is
omitted, it defaults to the value of the Password property.
An empty string means that no password will be provided.
- Timeout
- The number of seconds that the client will wait for a response
before failing the operation. If this argument is not specified,
the value of the Timeout property will be used as the default.
- Options
- An unsigned integer that specifies one or more options. If this
parameter is omitted, it defaults to the value of the
Options property. This parameter is constructed by using a
bitwise operator with any of the following values:
| Value |
Constant |
Description |
| 1 |
httpOptionNoCache |
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. |
| 2 |
httpOptionKeepAlive |
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. |
| 4 |
httpOptionRedirect |
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. |
| 8 |
httpOptionProxy |
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 in the system settings or control
panel. |
| 16 |
httpOptionErrorData |
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
httpOptionRedirect. |
| 32 |
httpOptionNoUserAgent |
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. |
| 64 |
httpOptionHttp2 |
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
ProtocolVersion property will be ignored when this
option is used. |
| &H400 |
httpOptionTunnel |
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. |
| &H800 |
httpOptionTrustedSite |
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. |
| &H1000 |
httpOptionSecure |
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. The client will default to using TLS 1.2 or later
for secure connections. |
| &H8000 |
httpOptionSecureFallback |
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. |
| &H40000 |
httpOptionPreferIPv6 |
This option specifies the client should attempt to
resolve a domain name to an IPv6 address. If the domain name has
both an IPv4 and IPv6 address assigned to it, the default is to
use the IPv4 address for compatibility purposes. Enabling this
option forces the client to always use the IPv6 address if one
is available. If the domain name does not have an assigned IPv4
address, the IPv6 address will always be used regardless if this
option is specified. |
| &H100000 |
httpOptionHiResTimer |
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
being uploaded or downloaded using fast network connections. |
Return Value
A value of zero is returned if the connection was successful.
Otherwise, a non-zero error code is returned which indicates the
cause of the failure.
Remarks
If the httpOptionKeepAlive 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.
Under some circumstances, a server may forcibly close or abort
a connection if the request fails. For example, this can happen when a
malformed request is submitted to the server or a server-side error
occurs. When this happens, the application will need to disconnect
from the server and establish a new connection, even if the keep-alive
option has been specified.
If your application specifies the httpOptionHttp2 option,
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 Windows do not support
the features required for a secure HTTP/2 connection. If the server
only accepts earlier versions of the protocol, the client will attempt
to automatically downgrade the request to HTTP/1.1.
See Also
AutoRedirect Property,
HostAddress Property,
HostName Property,
Options Property,
ProxyHost Property,
ProxyPort Property,
ProxyType Property,
RemotePort Property,
URL Property,
Disconnect Method,
OnConnect Event
|
|