Options Property  
 

Gets and sets the options that are used in establishing a connection.

Syntax

object.Options [= value ]

Remarks

The Options property is an integer value which specifies one or more options. The value specified for this property will be used as the default options when connecting to the server. The property value is created by using a bitwise operator with one or more 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.

Note that setting the ftpOptionPassive option is the same as setting the Passive property to True.

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.

If the amount of time required to perform the transfer exceeds the server idle timeout period, the server may abort the connection. Using the ftpOptionKeepAliveData option tells the client to periodically send NOOP commands during the transfer to maintain the control connection. Some servers may not accept client commands while a transfer is in progress. You should only use this option if the server is timing out the control connection during large file transfers.

The ftpOptionTLSReuse 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.

Data Type

Integer (Int32)

Example

'
' The Ipswitch WS_FTP server accepts the AUTH command to establish
' an explicit SSL session on the default FTP port
'

FtpClient1.Options = ftpOptionSecureExplicit
nError = FtpClient1.Connect(strHostName)

'
' When the GlobalSCAPE Secure FTP server is configured in implicit
' authorization mode, it negotiates a secure session as soon as the
' connection is established and does not require a command
'

FtpClient1.Options = ftpOptionSecure
nError = FtpClient1.Connect(strHostName)

See Also

Priority Property, Secure Property, Connect Method