| |
Establish a connection with a server.
Syntax
object.Connect( [RemoteHost],
[RemotePort], [UserName], [Password],
[Account], [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. If the secure port number is specified,
an implicit SSL/TLS connection will be established by default.
- UserName
- A string that specifies the user name to be used to
authenticate the current client session. If this argument is
omitted, then the value of the UserName property will be
used. If the user name is specified as an empty string, then the
login is considered to be anonymous.
- Password
- A string that specifies the password to be used to authenticate
the current client session. If this argument is omitted, then the
value of the Password property will be used. This argument
may be empty string if no password is required for the specified
user, or if no username has been specified.
- Account
- A string that specifies the account name to be used to
authenticate the current client session. If this argument is
omitted, then the value of the Account property will be
used. This parameter may be an empty string if no account name is
required for the specified user.
- 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
- A numeric value which specifies one or more options. If this
argument is omitted or a value of zero is specified, a default,
standard connection will be established. This argument is
constructed by using a bitwise operator with any of the following
values:
| Value |
Constant |
Description |
| 1 |
ftpOptionPassive |
This option specifies the client should attempt to
establish a passive connection to the server. This means that
instead of the client opening a port on the local system and
waiting for the server to establish a connection back to the
client, the client will establish a second data connection to
the server. This mode is recommended for most systems that are
behind a NAT router or firewall. |
| 2 |
ftpOptionFirewall |
This option specifies the client should always use the
host IP address to establish the data connection with the
server, not the address returned by the server in response to
the PASV command. This option may be necessary if the server is
behind a router that performs Network Address Translation (NAT)
and it returns an unreachable IP address for the data
connection. If this option is specified, it will also enable
passive mode data transfers. |
| 4 |
ftpOptionNoAuth |
This option specifies the server does not require
authentication, or that it requires an alternate authentication
method. When this option is used, the client connection is
flagged as authenticated as soon as the connection to the
server has been established. Note that using this option to
bypass authentication may result in subsequent errors when
attempting to retrieve a directory listing or transfer a file.
It is recommended that you consult the technical reference
documentation for the server to determine its specific
authentication requirements. |
| 8 |
ftpOptionKeepAlive |
This option specifies the client should attempt to
keep the connection with the server active for an extended
period of time. It is important to note that regardless of this
option, the server may still choose to disconnect client
sessions that are holding the command channel open but are not
performing file transfers. |
| &H10 |
ftpOptionNoAuthRSA |
This option specifies that RSA authentication should not be
used with SSH-1 connections. This option is ignored with SSH-2
connections and should only be specified if required by the
server. This option has no effect on standard or secure
connections using SSL. |
| &H20 |
ftpOptionNoPwdNul |
This option specifies the user password cannot be
terminated with a null character. This option is ignored with SSH-2
connections and should only be specified if required by the
server. This option has no effect on standard or secure
connections using SSL. |
| &H40 |
ftpOptionNoRekey |
This option specifies the client should never attempt
a repeat key exchange with the server. Some SSH servers do not
support rekeying the session, and this can cause the client to
become non-responsive or abort the connection after being
connected for an hour. This option has no effect on standard or
secure connections using SSL. |
| &H80 |
ftpOptionCompatSID |
This compatibility option changes how the session ID is
handled during public key authentication with older SSH
servers. This option should only be specified when connecting
to servers that use OpenSSH 2.2.0 or earlier versions. This
option has no effect on standard or secure connections using
SSL. |
| &H100 |
ftpOptionCompatHMAC |
This compatibility option changes how the HMAC
authentication codes are generated. This option should only be
specified when connecting to servers that use OpenSSH 2.2.0 or
earlier versions. This option has no effect on standard or
secure connections using SSL. |
| &H200 |
ftpOptionVirtualHost |
This option specifies the server supports virtual
hosting, where multiple domains are hosted by a server using
the same external IP address. If this option is enabled, the
client will send the HOST command to the server upon
establishing a connection. |
| &H400 |
ftpOptionVerify |
This option specifies that file transfers should be
automatically verified after the transfer has completed. If the
server supports the XMD5 command, the transfer will be verified
by calculating an MD5 hash of the file contents. If the server
does not support the XMD5 command, but does support the XCRC
command, the transfer will be verified by calculating a CRC32
checksum of the file contents. If neither the XMD5 or XCRC
commands are supported, the transfer is verified by comparing
the size of the file. Automatic file verification is only
performed for binary mode transfers because of the end-of-line
conversion that may occur when text files are uploaded or
downloaded. |
| &H800 |
ftpOptionTrustedSite |
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. |
| &1000 |
ftpOptionSecure |
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. |
| &H2000 |
ftpOptionSecureExplicit |
This option specifies the client should use the AUTH
TLS-P command to negotiate an explicit secure connection. Some
servers may only require this when connecting to the server on
ports other than 990. |
| &H4000 |
ftpOptionSecureShell |
This option specifies the client should use the Secure
Shell (SSH) protocol to establish the connection. This option
will automatically be selected if the connection is established
using port 22, the default port for SSH, and is only required
if the server is configured to use a non-standard port
number. |
| &H8000 |
ftpOptionSecureFallback |
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. |
| &H10000 |
ftpOptionTunnel |
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. This option also forces all
connections to be outbound and enables the firewall
compatibility features in the client. |
| &H20000 |
ftpOptionKeepAliveData |
This option specifies the client should attempt to keep the
control connection active during a file transfer. Normally, when a data
transfer is in progress, no additional commands are issued on
the control channel until the transfer completes. Specifying
this option automatically enables the ftpOptionKeepAlive
option and forces the client to continue to issue NOOP commands
during the file transfer. This option only applies to FTP and
FTPS connections and has no effect on connections using SFTP
(SSH). |
| &40000 |
ftpOptionPreferIPv6 |
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. |
| &100000 |
ftpOptionHiResTimer |
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 files being
uploaded or downloaded using fast network connections. |
| &200000 |
ftpOptionTLSReuse |
This option specifies that TLS session reuse should be
enabled for secure data connections. Some servers may require
this option be enabled, although it should only used when
required. This option is only valid for secure FTP (FTPS)
connections and is not used with SFTP or secure HTTP
connections. See the remarks below for more information. |
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 Options argument is omitted, then the value of the
Options property will be used. Note that specifying the
ftpOptionPassive option is the same as setting the
Passive property to True.
If the ftpOptionNoAuth option is specified, the control
will not attempt to authenticate the client session. Note that you
may still explicitly call the Login method after the
connection has been established.
If the ftpOptionSecureExplicit option is specified, the
client will first send an AUTH TLS command to the server. If the
server does not accept this command, it will then send an AUTH SSL
command. If both commands are rejected by the server, an explicit SSL
session cannot be established. By default, both the command and data
channels will be encrypted when a secure connection is established.
To change this, set the ChannelMode property.
The fileOptionTLSReuse option is only supported on
Windows 8.1 or Windows Server 2012 R2 and later platforms. This option
is not compatible with servers built using OpenSSL 1.0.2 and earlier
versions which do not provide Extended Master Secret (EMS) support as
outlined in RFC7627. To avoid potential problems with server
compatibility, you should not specify this option for all FTP
connections. It should only be used if specifically required by the
server and your end-users should have the ability to selectively
enable or disable this option.
See Also
ActivePort Property,
HostAddress Property,
HostName Property,
Options Property,
Passive Property.
RemotePort Property,
URL Property,
Disconnect Method,
OnConnect Event
|
|