FTPClient Class
Properties Methods Events Configuration Settings Errors
The FTPClient class provides client-side functionality for FTP and FTPS protocols.
Syntax
secureblackboxlite.Ftpclient
Remarks
FTPClient provides client-side support for the FTP (File Transfer Protocol) and FTPS (FTP-over-SSL) protocols. The FTPS protocol allows you to securely perform file transfer operations with a remote server over Transport Layer Security (TLS).
Note: TLS is a successor to the now deprecated SSL protocol, although the latter abbreviation is still widely used.
FTPClient is typically used in the following scenario:
- Setting up the connection parameters
- Connecting to the server and signing in
- Performing file transfer operations
- Closing the connection
Setting up the parameters
When working with FTP or FTP-over-TLS service you will often need to tune up several classes of settings:- Login credentials: these can be tuned up via the Username and Password properties.
- TLS settings: these includes the TLS mode: explicit, implicit, or no TLS. You must get this setting right; otherwise you may not be able to connect. Use TLSSettings property to adjust this setting.
- If your server requires you to authenticate with a certificate, you can provide one via the ClientChain property.
- FTPClient validates the server certificate against the local security settings. If your server uses a custom or non-public PKI, you may need to provide the required trust anchors and CA certificates via the TrustedCertificates and KnownCertificates collections.
- FTP protocol includes its own set of settings, such as PassiveMode, EncryptDataChannel, or AdjustPasvAddress. These may be configured on this stage, or later into the connection.
- In some network environments, you may also need to make adjustments to SocketSettings and Proxy.
Connecting to the server and signing in
Call Connect to open the connection to the server. The component will use the provided credentials to sign you in automatically.Performing file transfer operations
FTPClient offers the full set of FTP operations. These include file uploads (UploadFile or UploadBytes), file downloads (DownloadFile, DownloadBytes), and directory operations (ListDir, MakeDir).Note that unlike SFTP, FTP only supports one transfer operation at a time. An ongoing operation should be completed or aborted before a new one can be started.
Closing the connection
Use Disconnect to close the FTP connection.Useful info
During its work FTPClient communicates back via events. Progress event fires periodically during the transfer operation to let you know of the operation progress. ControlSend and ControlReceive report the protocol communication log. FileOperation and FileOperationResult report the start and completion of an individual transfer operation within a multi-file transfer call (such as UploadFiles).Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
AdjustPasvAddress | Enables or disables automatic adjustment of passive-mode addresses. |
BlockedCertificates | The certificates that must be rejected as trust anchors. |
ClientChain | The TLS client certificate chain. |
Connected | Indicates whether the class is connected to the server. |
ControlConnectionInfo | Returns the details of the control connection setup. |
CurrentListEntry | Contains the details of the file entry reported by ListEntry . |
DataConnectionInfo | Returns the details of the data connection setup. |
EncryptDataChannel | Enables or disables data channel encryption. |
ExternalCrypto | Provides access to external signing and DC parameters. |
KnownCertificates | Additional certificates for chain validation. |
KnownCRLs | Additional CRLs for chain validation. |
KnownOCSPs | Additional OCSP responses for chain validation. |
PassiveMode | Enables or disables passive transfer mode. |
Password | The connecting user's authentication password. |
Proxy | The proxy server settings. |
RestartAt | The offset to restart the file transfer from. |
ServerChain | The TLS server's certificate chain. |
SocketSettings | Manages network connection settings. |
TLSSettings | Manages TLS layer settings. |
TransferType | Sets the file transfer mode. |
TrustedCertificates | A list of trusted certificates for chain validation. |
Username | The connecting user's username (login name). |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
Abort | Aborts the previous FTP service command and any associated transfer of data. |
Acct | Sends an Account command. |
AppendBytes | Appends a byte array to a server-side file. |
AppendFile | Uploads a file to the server. |
AppendStream | Uploads a file to the server. |
ChangeDir | Changes the current directory. |
ClearCommandChannel | Sends CCC (Clear Command Channel) command to the server. |
Config | Sets or retrieves a configuration setting. |
Connect | Connects to the FTP server. |
DeleteDir | Deletes a directory on the server. |
DeleteFile | Deletes a file on the server. |
DirExists | Checks if a directory exists on the server. |
Disconnect | Disconnects from the server. |
DownloadBytes | Downloads a file from the server into an array of bytes. |
DownloadFile | Downloads a file from the server. |
DownloadFiles | Downloads multiple files from the server. |
DownloadStream | Downloads a file from the server into a stream. |
FileExists | Checks if a file exists on the server. |
GetCurrentDir | Returns the server-side current directory. |
GetFileSize | Returns the size of a remote file. |
ListDir | Lists the contents of a remote directory. |
MakeDir | Creates a new directory on the server. |
Noop | Sends a NOOP command to the server. |
Rename | Renames a file. |
SendCommand | Sends a custom command to the server. |
UploadBytes | Uploads a byte array to the server. |
UploadFile | Uploads a file to the server. |
UploadFiles | Uploads multiple files to the server. |
UploadStream | Uploads a file to the server. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
CertificateValidate | Fires when the server's TLS certificate has to be validated. |
ControlReceive | Fires when data is received via the control channel. |
ControlSend | Fires when data is about to be set via the control channel. |
Error | Information about errors during data delivery. |
ExternalSign | Handles remote or external signing initiated by the SignExternal method or other source. |
FileOperation | Marks the start of a file transfer. |
FileOperationResult | Reports the result of a file transfer operation. |
ListEntry | Reports a single entry from the requested directory listing. |
Notification | This event notifies the application about an underlying control flow event. |
Progress | Reports the data transfer progress. |
TextDataLine | Reports next transferred data line. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
AccountInfo | Parameters for the ACCT command. |
AuthCmd | Authorization command to be used to request an explicit SSL session. |
CaseConversion | Whether file names and paths should be case-converted. |
CaseSensitive | Case-sensitivity of file names and paths. |
CloseQuietly | Set this to true to avoid sending QUIT command on session closure. |
ConcurrentConnections | Number of simultaneous connections for download. |
CopyMode | What to do with the originals of the copied files. |
ErrorOrigin | Specifies where the error has been originated. |
ErrorSeverity | Error severity. |
EventOrigin | Indicates the channel that has fired the event. |
ExtHOSTSupported | Whether HOST extension is supported. |
ExtMDTMSupported | Whether MDTM extension is supported. |
ExtMFMTSupported | Whether MFMT extension is supported. |
ExtMLSTSupported | Whether MLST extension is supported. |
ExtOPTSUTF8Supported | Whether OPTS UTF8 extension is supported. |
ExtRESTSupported | Whether REST extension is supported. |
ExtSIZESupported | Whether SIZE extension is supported. |
ExtXCRCSupported | Whether XCRC extension is supported. |
ExtXMD5Supported | Whether XMD5 extension is supported. |
FTPBufferSize | Buffer size in binary mode. |
FTPTextBufferSize | Buffer size in text mode. |
IgnoreSystemTrust | Whether trusted Windows Certificate Stores should be treated as trusted. |
ListenTimeout | Listening socket timeout. |
LocalNewLineConvention | Defines the local newline convention. |
MinSizeForConcurrentDownload | Files bigger than this size will be downloaded concurrently. |
Mode | What to do if the destination file already exists. |
ModeZ | Switches on data compression. |
Options | Various FTP options. |
Recursive | Whether to scan subdirectories. |
TempPath | Path for storing temporary files. |
TolerateMinorChainIssues | Whether to tolerate minor chain issues. |
TransferKeepAliveInterval | Keep-alive interval for the data channel transfers. |
TransferTimeout | Timeout for data transfer in active mode. |
UseMicrosoftCTL | Enables or disables automatic use of Microsoft online certificate trust list. |
UseProxySettingsForDataChannel | Whether the proxy settings should be applied to data channel. |
UseSystemCertificates | Enables or disables the use of the system certificates. |