| |
Establish a connection with the specified FTP or HTTP server.
Syntax
object.Connect( [ServerName],
[ServerPort], [UserName], [Password],
[Timeout], [Options] )
Parameters
- ServerName
- An optional string value which specifies the host name
or IP address of the server. If this argument is not specified,
it defaults to the value of the ServerName property if
it is defined.
- ServerPort
- 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 ServerPort property. A value of zero indicates that
the default port number for the service type should be used to
establish the connection.
- UserName
- A string which specifies the user name which will be used to
authenticate the client session. This value must specify a valid
user name and cannot be an empty string. If this argument is not
specified, it defaults to the value of UserName property.
- Password
- A string which specifies the password which will be used to
authenticate the client session. If the user does not have a
password, this value can be an empty string. If this argument
is not specified, it defaults to the value of the Password
property. If the server requires public/private key authentication,
set the PrivateKey property to the name of the file
containing the private key prior to calling this method.
- 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 optional integer value which specifies one or more options.
If this argument is omitted or a value of zero is specified, a
default connection will be established. This argument is constructed
by using a bitwise operator with any of the following values
| Value |
Description |
| fileOptionNoCache |
This instructs an HTTP 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. |
| &H1000 |
fileOptionSecureImplicit |
This option specifies the client should immediately
negotiate for a secure session upon establishing a connection
with the server. This is the default method for connecting to a
secure HTTP server and may also be used with FTP servers that
accept secure connections on port 990. |
| &H2000 |
fileOptionSecureExplicit |
This option specifies the client should use the AUTH
server command to tell an FTP server that it wishes to explicitly
negotiate a secure connection. This requires that the server
support the AUTH TLS or AUTH SSL commands. Some servers may not
require this option, and some may require the option only if a
port other than 990 is specified. If this option is specified,
the Secure property will automatically be set to
True. |
| &H4000 |
fileOptionSecureShell |
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 |
fileOptionSecureFallback |
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 |
fileOptionPreferIPv6 |
This option specifies the client should only 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 |
fileOptionHiResTimer |
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. |
| &H200000 |
fileOptionTLSReuse |
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 method succeeds. Otherwise,
a non-zero error code is returned which indicates the cause of the
failure.
Remarks
The Connect method is used to establish a connection with
the specified server. This is the first method that must be called
prior to the application transferring files or issuing FTP
commands. If the Connect method is called when a connection already
exists, the current connection will be closed.
It is permissible to specify a complete URL as the first argument
to the method and the connection will be established with the server
using specified protocol. Passing a complete URL to the
Connect method has the same effect as setting the URL
property and then calling the method with no arguments.
Additional properties that affect the operation of the
Connect method are:
- KeepAlive Property (HTTP)
- ProtocolVersion Property (HTTP)
- ProxyPassword Property
- ProxyPort Property
- ProxyServer Property
- ProxyType Property
- ProxyUser Property
- Secure Property
- ServerType Property
- URL Property
If the ServerType property has the value
fileServerUndefined, then the Connect method will try
to infer the server type from the value of the ServerPort
property. If the server type cannot be automatically determined, an
error will be returned and the server type must be explicitly
specified.
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
FTP server and your end-users should have the ability to selectively
enable or disable this option.
This method will return a value of zero if the action was
successful. Otherwise, a non-zero error code is returned which
indicates the cause of the failure.
Example
nError = FileTransfer1.Connect("www.example.com", 443)
If nError > 0 Then
MsgBox FileTransfer1.LastErrorString, vbExclamation
Exit Sub
End If
nError = FileTransfer1.Connect("https://wwww.example.com")
If nError > 0 Then
MsgBox FileTransfer1.LastErrorString, vbExclamation
Exit Sub
End If
See Also
KeepAlive Property,
Options Property,
Secure Property,
ServerType Property,
ServerName Property,
ServerPort Property,
UserName Property,
Password Property,
Timeout Property,
URL Property
|
|