|
|
Establish a connection with a remote server.
Syntax
object.Connect( [RemoteHost],
[RemotePort], [UserName], [Password],
[Account], [Timeout], [Options] )
Remarks
This method establishes a network connection with a remote
server. All arguments are optional. If a given argument is missing,
then a corresponding property or properties must be set before
attempting the connection, as follows:
- RemoteHost
- A string which specifies the host name or IP address of the
remote host. 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 remote
host. 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 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. A value of zero indicates that the
client should wait an indefinite period of time. 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 |
| &H0001 |
ftpOptionPassive |
This option specifies that the
client should attempt to establish the data connection with the
server. When the client uploads or downloads a file, normally the
server establishes a second connection back to the client which is
used to transfer the file data. However, if the local system is
behind a firewall or a NAT router, the server may not be able to
create the data connection and the transfer will fail. By
specifying this option, it forces the client to establish an
outbound data connection with the server. It is recommended that
applications use passive mode whenever possible. |
| &H0002 |
ftpOptionNATRouter |
This option specifies that 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. |
| &H0004 |
ftpOptionNoAuth |
This option specifies that 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. |
| &H0008 |
ftpOptionKeepAlive |
This option specifies that 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. |
| &H0010 |
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 remote host. This option has no effect
on standard or secure connections using SSL. |
| &H0020 |
ftpOptionNoPwdNul |
This options specifies that the
user password cannot be terminated with a null byte. This option is
ignored with SSH-2 connections and should only be specified if
required by the remote host. This option has no effect on standard
or secure connections using SSL. |
| &H0040 |
ftpOptionNoRekey |
This option specifies that 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. |
| &H0080 |
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. |
| &H0100 |
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. |
| &H0200 |
ftpOptionVirtualHost |
This option specifies that 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. |
| &H0400 |
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. |
| &H1000 |
ftpOptionSecure |
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. This option is only available in
the Secure Editions of SocketTools. |
| &H2000 |
ftpOptionSecureExplicit |
This option specifies that the
client should use the AUTH command to negotiate an explicit secure
connection. Some servers may only require this when connecting to
the server on ports other than 990. This option is only available
in the Secure Editions of SocketTools. |
| &H4000 |
ftpOptionSecureShell |
This option specifies that 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.
It is only required that you specify this option if you are
establishing the connection the server on a non-standard port. This
option is only available in the Secure Editions of
SocketTools. |
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. The security options are only
available when using one of the SocketTools Secure Editions,
otherwise an error will be returned when attempting to establish a
connection.
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.
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.
See Also
ActivePort Property,
HostAddress Property,
HostName Property, Passive Property. RemotePort Property, RemoteService Property,
URL Property, Disconnect Method, OnConnect Event
|
|