FTPClient Component

Properties   Methods   Events   Config Settings   Errors  

The FTPClient component provides client-side functionality for FTP and FTPS protocols.

Syntax

TsbxFTPClient

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 component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

AccountInfo Property (FTPClient Component)

Parameters for the ACCT command.

Syntax

property AccountInfo: String read get_AccountInfo write set_AccountInfo;

Default Value

''

Remarks

Specifies the parameter for ACCT command. If AccountInfo is set, the client automatically sends ACCT command to the server during authentication.

AdjustPasvAddress Property (FTPClient Component)

Enables or disables automatic adjustment of passive-mode addresses.

Syntax

property AdjustPasvAddress: Boolean read get_AdjustPasvAddress write set_AdjustPasvAddress;

Default Value

true

Remarks

Occasional NAT'ed servers misbehave by returning local IP addresses in their PASV mode offers, which are not reachable from the outer network. Set this property to true to make the component enforce data connections to the same address as the control connection uses.

Note that sometimes (typically, with multi-faced FTP services aka FTP Clouds) you may need to disable this property to make the transfers work right.

BlockedCertificates Property (FTPClient Component)

The certificates that must be rejected as trust anchors.

Syntax

property BlockedCertificates: TsbxCertificateList read get_BlockedCertificates write set_BlockedCertificates;

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ClientChain Property (FTPClient Component)

The TLS client certificate chain.

Syntax

property ClientChain: TsbxCertificateList read get_ClientChain write set_ClientChain;

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the component. Note that the client's end-entity certificate should have a private key associated with it.

Use CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Connected Property (FTPClient Component)

Indicates whether the component is connected to the server.

Syntax

property Connected: Boolean read get_Connected;

Default Value

false

Remarks

Use this property to check if the connection to server is active.

This property is read-only and not available at design time.

ControlChannelLog Property (FTPClient Component)

Contains the control channel log of the FTP session.

Syntax

property ControlChannelLog: String read get_ControlChannelLog;

Default Value

''

Remarks

Use this property to access the FTP protocol log (client commands followed by server responses).

This property is read-only.

ControlConnectionInfo Property (FTPClient Component)

Returns the details of the control connection setup.

Syntax

property ControlConnectionInfo: TsbxConnectionInfo read get_ControlConnectionInfo;

Remarks

Use this property to learn about the control connection setup, such as protocol details and amounts of data transferred each way.

This property is read-only.

Please refer to the ConnectionInfo type for a complete list of fields.

CurrentListEntry Property (FTPClient Component)

Contains the details of the file entry reported by ListEntry .

Syntax

property CurrentListEntry: TsbxFTPListEntry read get_CurrentListEntry;

Remarks

A typical use of this property is to check it in ListEntry event handler. This property is updated with new details each time a new entry is processed.

This property is read-only and not available at design time.

Please refer to the FTPListEntry type for a complete list of fields.

DataConnectionInfo Property (FTPClient Component)

Returns the details of the data connection setup.

Syntax

property DataConnectionInfo: TsbxConnectionInfo read get_DataConnectionInfo;

Remarks

Use this property to learn about the data connection setup, such as protocol details and amounts of data transferred each way.

This property is read-only.

Please refer to the ConnectionInfo type for a complete list of fields.

EncryptDataChannel Property (FTPClient Component)

Enables or disables data channel encryption.

Syntax

property EncryptDataChannel: Boolean read get_EncryptDataChannel write set_EncryptDataChannel;

Default Value

true

Remarks

Use this property to enable or disable data channel encryption. This property should be configured before Connect method is called.

ExternalCrypto Property (FTPClient Component)

Provides access to external signing and DC parameters.

Syntax

property ExternalCrypto: TsbxExternalCrypto read get_ExternalCrypto;

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

Please refer to the ExternalCrypto type for a complete list of fields.

FIPSMode Property (FTPClient Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

KnownCertificates Property (FTPClient Component)

Additional certificates for chain validation.

Syntax

property KnownCertificates: TsbxCertificateList read get_KnownCertificates write set_KnownCertificates;

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

KnownCRLs Property (FTPClient Component)

Additional CRLs for chain validation.

Syntax

property KnownCRLs: TsbxCRLList read get_KnownCRLs write set_KnownCRLs;

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the CRL type for a complete list of fields.

KnownOCSPs Property (FTPClient Component)

Additional OCSP responses for chain validation.

Syntax

property KnownOCSPs: TsbxOCSPResponseList read get_KnownOCSPs write set_KnownOCSPs;

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the OCSPResponse type for a complete list of fields.

ModeZ Property (FTPClient Component)

Switches on data compression.

Syntax

property ModeZ: Boolean read get_ModeZ write set_ModeZ;

Default Value

true

Remarks

Switches the in-flight data compression on/off.

PassiveMode Property (FTPClient Component)

Enables or disables passive transfer mode.

Syntax

property PassiveMode: Boolean read get_PassiveMode write set_PassiveMode;

Default Value

true

Remarks

The transfer mode (active or passive) regulates which party is responsible for opening a listening port for data connections. Where passive mode is used, the FTP server is responsible for listening for data connections. In active mode, the listening port is opened by the client.

In today's Internet of firewalls it is a de-facto standard to use the passive mode for FTP transfers.

Password Property (FTPClient Component)

The connecting user's authentication password.

Syntax

property Password: String read get_Password write set_Password;

Default Value

''

Remarks

Assign the user's authentication password to this property. Use Username for username/login.

Proxy Property (FTPClient Component)

The proxy server settings.

Syntax

property Proxy: TsbxProxySettings read get_Proxy;

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

Please refer to the ProxySettings type for a complete list of fields.

RestartAt Property (FTPClient Component)

The offset to restart the file transfer from.

Syntax

property RestartAt: Int64 read get_RestartAt write set_RestartAt;

Default Value

-1

Remarks

If non-zero, tells the component to restart the file transfer operation at the specified position, rather than transfer the file in full.

ServerChain Property (FTPClient Component)

The TLS server's certificate chain.

Syntax

property ServerChain: TsbxCertificateList read get_ServerChain;

Remarks

Use this property to access the certificate chain sent by the TLS server. This property is ready to read when OnCertificateValidate event is fired by the client component.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

SocketSettings Property (FTPClient Component)

Manages network connection settings.

Syntax

property SocketSettings: TsbxSocketSettings read get_SocketSettings;

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Please refer to the SocketSettings type for a complete list of fields.

TLSSettings Property (FTPClient Component)

Manages TLS layer settings.

Syntax

property TLSSettings: TsbxTLSSettings read get_TLSSettings;

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Please refer to the TLSSettings type for a complete list of fields.

TransferType Property (FTPClient Component)

Sets the file transfer mode.

Syntax

property TransferType: TsbxFTPTransferTypes read get_TransferType write set_TransferType;

TsbxFTPTransferTypes = (
  cttText,
  cttBinary
);

Default Value

cttBinary

Remarks

Use this property to switch between binary and text transfer modes.

TrustedCertificates Property (FTPClient Component)

A list of trusted certificates for chain validation.

Syntax

property TrustedCertificates: TsbxCertificateList read get_TrustedCertificates write set_TrustedCertificates;

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Username Property (FTPClient Component)

The connecting user's username (login name).

Syntax

property Username: String read get_Username write set_Username;

Default Value

''

Remarks

Assign the user's login name to this property. Use Password to provide the password.

Abort Method (FTPClient Component)

Aborts the previous FTP service command and any associated transfer of data.

Syntax

procedure Abort();

Remarks

Use this method to abort the previous FTP service command and any associated data transfer.

Acct Method (FTPClient Component)

Sends an Account command.

Syntax

procedure Acct(AcctInfo: String);

Remarks

Some servers require the ACCT command to be sent after signing in to grant access to specific server resources.

Reply codes sometimes allow to differentiate the handling of ACCT command:

• when account information is required for login, the response to a successful PASSword command is reply code 332;
• if account information is NOT required for login, the reply to a successful PASSword command is 230;
• if account information is needed for a command issued later in the dialogue, the server should return a 332 or 532 reply depending on whether it stores (pending receipt of the ACCounT command) or discards the command, respectively.

AppendBytes Method (FTPClient Component)

Appends a byte array to a server-side file.

Syntax

procedure AppendBytes(Bytes: TBytes; RemoteFile: String);

Remarks

Use this method to append Bytes to RemoteFile on the server.

AppendFile Method (FTPClient Component)

Uploads a file to the server.

Syntax

procedure AppendFile(LocalFile: String; RemoteFile: String);

Remarks

Use this method to upload LocalFile or its part to RemoteFile on the server.

AppendStream Method (FTPClient Component)

Uploads a file to the server.

Syntax

procedure AppendStream(LocalStream: TStream; RemoteFile: String);

Remarks

Use this method to upload data contained in LocalStream to RemoteFile on the server.

ChangeDir Method (FTPClient Component)

Changes the current directory.

Syntax

procedure ChangeDir(RemoteDir: String);

Remarks

Call this method to change the current server directory to RemoteDir.

ClearCommandChannel Method (FTPClient Component)

Sends CCC (Clear Command Channel) command to the server.

Syntax

procedure ClearCommandChannel(GracefulSSLClosure: Boolean);

Remarks

Use this method to send a CCC command. CCC clears command channel encryption state, turning off TLS encryption.

Some servers expect this command to allow for the control channel to be properly handled by NATs.

Config Method (FTPClient Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Connect Method (FTPClient Component)

Connects to the FTP server.

Syntax

procedure Connect(Address: String; Port: Integer);

Remarks

Call this method to connect to the FTP server residing at Address:Port.

The component will connect to the server using the connection settings provided. If the connection is successful, it will also authenticate using the provided Username and Password.

DeleteDir Method (FTPClient Component)

Deletes a directory on the server.

Syntax

procedure DeleteDir(RemoteDir: String);

Remarks

This method sends an RMD command to the server to request deletion of a remote directory.

DeleteFile Method (FTPClient Component)

Deletes a file on the server.

Syntax

procedure DeleteFile(RemoteFile: String);

Remarks

This method sends a DELE command to the server to request deletion of a remote file.

DirExists Method (FTPClient Component)

Checks if a directory exists on the server.

Syntax

function DirExists(RemoteDir: String): Boolean;

Remarks

Use this method to check if the RemoteDir exists on the server.

The test is performed by attempting to change the current directory to RemoteDir, and checking the response code returned by the server.

Note that this method will return false if the directory does exist but is not accessible for the client (e.g. due to a permission issue).

Disconnect Method (FTPClient Component)

Disconnects from the server.

Syntax

procedure Disconnect();

Remarks

Call this method to disconnect from the server.

DoAction Method (FTPClient Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): String;

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

DownloadBytes Method (FTPClient Component)

Downloads a file from the server into an array of bytes.

Syntax

function DownloadBytes(RemoteFile: String): TBytes;

Remarks

Use this method to download RemoteFile into a byte array.

DownloadFile Method (FTPClient Component)

Downloads a file from the server.

Syntax

procedure DownloadFile(RemoteFile: String; LocalFile: String);

Remarks

Use this method to download RemoteFile into LocalFile.

DownloadFiles Method (FTPClient Component)

Downloads multiple files from the server.

Syntax

procedure DownloadFiles(RemotePath: String; LocalDir: String);

Remarks

Use this method do download a collection of files from the server.

RemotePath can contain a simple mask, a set of masks, or a regular expression. All the files that match the provided rule will be downloaded to LocalDir.

DownloadStream Method (FTPClient Component)

Downloads a file from the server into a stream.

Syntax

procedure DownloadStream(RemoteFile: String; LocalStream: TStream);

Remarks

Use this method to download RemoteFile into a stream object.

FileExists Method (FTPClient Component)

Checks if a file exists on the server.

Syntax

function FileExists(RemoteFile: String): Boolean;

Remarks

Use this method to check if RemoteFile exists in the current remote directory. This method attempts to detect file existence using SIZE and MLST commands first, and falls back to LIST command if they are not available.

Please note that this command only looks for the file in the current directory. To check for existence of a file in a different directory, change to it with ChangeDir command first, then call this method.

GetCurrentDir Method (FTPClient Component)

Returns the server-side current directory.

Syntax

function GetCurrentDir(): String;

Remarks

Use this method to find out the current directory on the server.

GetFileSize Method (FTPClient Component)

Returns the size of a remote file.

Syntax

function GetFileSize(RemoteFile: String): Int64;

Remarks

Use this method to retrieve the size of a remote file. This method attempts to use SIZE and MLST commands if available, and resorts to LIST command otherwise.

Please note that this command only looks for the file in the current directory. To check for existence of a file in a different directory, change to it with ChangeDir command first, then call this method.

ListDir Method (FTPClient Component)

Lists the contents of a remote directory.

Syntax

function ListDir(IncludeFiles: Boolean; IncludeDirectories: Boolean): String;

Remarks

Use the IncludeFiles and IncludeDirectories parameters to tune up the output. The output of IncludeFiles also includes symbolic links.

This method returns a human-readable string containing the requested list. It also fires ListEntry for each entry in the list, propagating its details in CurrentListEntry.

This method uses some heuristics internally by choosing the most appropriate listing method among MLSD, NLST, and LIST.

MakeDir Method (FTPClient Component)

Creates a new directory on the server.

Syntax

procedure MakeDir(RemoteDir: String);

Remarks

This method creates a directory. The path provided via RemoteDir can either be absolute or relative.

Depending on the server, the directory structure up to the innermost element might need to exist.

Noop Method (FTPClient Component)

Sends a NOOP command to the server.

Syntax

procedure Noop();

Remarks

Call this method to send a NOOP (No Operation) command to the server.

Rename Method (FTPClient Component)

Renames a file.

Syntax

procedure Rename(SourceFile: String; DestFile: String);

Remarks

Use this method to rename a server-side SourceFile to DestFile.

SendCommand Method (FTPClient Component)

Sends a custom command to the server.

Syntax

function SendCommand(Command: String): Integer;

Remarks

This method sends an arbitrary command to the server and returns the status code received. Use it to send custom or non-standard commands, or tune up the session flow as required by the server.

UploadBytes Method (FTPClient Component)

Uploads a byte array to the server.

Syntax

procedure UploadBytes(Bytes: TBytes; RemoteFile: String);

Remarks

Use this method to upload Bytes or its part to RemoteFile on the server.

UploadFile Method (FTPClient Component)

Uploads a file to the server.

Syntax

procedure UploadFile(LocalFile: String; RemoteFile: String);

Remarks

Use this method to upload LocalFile or its part to RemoteFile on the server.

UploadFiles Method (FTPClient Component)

Uploads multiple files to the server.

Syntax

procedure UploadFiles(LocalPath: String; RemoteDir: String);

Remarks

This method uploads all the files that match the LocalPath criteria to RemoteDir directory on the server. LocalPath accepts a simple mask, a set of masks, or a regular expression.

For each file being uploaded a pair of FileOperation and FileOperationResult events are invoked.

UploadStream Method (FTPClient Component)

Uploads a file to the server.

Syntax

procedure UploadStream(LocalStream: TStream; RemoteFile: String);

Remarks

Use this method to upload data contained in LocalStream to RemoteFile on the server.

ControlReceive Event (FTPClient Component)

Fires when data is received via the control channel.

Syntax

type TControlReceiveEvent = procedure (
  Sender: TObject;
  const TextLine: String
) of Object;

property OnControlReceive: TControlReceiveEvent read FOnControlReceive write FOnControlReceive;

Remarks

TextLine contains the data that was received, which would typically contain a reply to a command (e.g. 200 Command OK).

ControlSend Event (FTPClient Component)

Fires when data is about to be set via the control channel.

Syntax

type TControlSendEvent = procedure (
  Sender: TObject;
  const TextLine: String
) of Object;

property OnControlSend: TControlSendEvent read FOnControlSend write FOnControlSend;

Remarks

TextLine contains the data to be sent, which would typically contain a command issued by the client (e.g. CWD dir).

Error Event (FTPClient Component)

Information about errors during data delivery.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the FTP section.

ExternalSign Event (FTPClient Component)

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

type TExternalSignEvent = procedure (
  Sender: TObject;
  const OperationId: String;
  const HashAlgorithm: String;
  const Pars: String;
  const Data: String;
  var SignedData: String
) of Object;

property OnExternalSign: TExternalSignEvent read FOnExternalSign write FOnExternalSign;

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the component via the SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contains algorithm-dependent parameters.

The component uses base16 (hex) encoding for the Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses the .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

FileOperation Event (FTPClient Component)

Marks the start of a file transfer.

Syntax

type TFileOperationEvent = procedure (
  Sender: TObject;
  Operation: Integer;
  const RemotePath: String;
  const LocalPath: String;
  var Skip: Boolean;
  var Cancel: Boolean
) of Object;

property OnFileOperation: TFileOperationEvent read FOnFileOperation write FOnFileOperation;

Remarks

The component fires this event from DownloadFiles and UploadFiles to notify the application that the transfer of the next file in the list is about to start.

Use the Skip parameter to skip this particular file, or Cancel to cancel the whole multi-file operation.

Operations:

FileOperationResult Event (FTPClient Component)

Reports the result of a file transfer operation.

Syntax

type TFileOperationResultEvent = procedure (
  Sender: TObject;
  Operation: Integer;
  const RemotePath: String;
  const LocalPath: String;
  ErrorCode: Integer;
  const Comment: String;
  var Cancel: Boolean
) of Object;

property OnFileOperationResult: TFileOperationResultEvent read FOnFileOperationResult write FOnFileOperationResult;

Remarks

The component fires this event from DownloadFiles and UploadFiles to notify the application of the completion of a file operation.

ErrorCode and Comment provide the details of the operation. Use the Cancel parameter to terminate the whole multi-file operation if needed.

Operations:

ListEntry Event (FTPClient Component)

Reports a single entry from the requested directory listing.

Syntax

type TListEntryEvent = procedure (
  Sender: TObject;
  const Filename: String
) of Object;

property OnListEntry: TListEntryEvent read FOnListEntry write FOnListEntry;

Remarks

FileName contains the filename of the reported entry. Read the details of the entry from CurrentListEntry property.

Notification Event (FTPClient Component)

This event notifies the application about an underlying control flow event.

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

Progress Event (FTPClient Component)

Reports the data transfer progress.

Syntax

type TProgressEvent = procedure (
  Sender: TObject;
  Total: Int64;
  Current: Int64;
  var Cancel: Boolean
) of Object;

property OnProgress: TProgressEvent read FOnProgress write FOnProgress;

Remarks

This event fires periodically during a file transfer operation to report its progress.

Use the Cancel parameter to terminate the transfer if needed.

TextDataLine Event (FTPClient Component)

Reports next transferred data line.

Syntax

type TTextDataLineEvent = procedure (
  Sender: TObject;
  const TextLine: String
) of Object;

property OnTextDataLine: TTextDataLineEvent read FOnTextDataLine write FOnTextDataLine;

Remarks

The component fires this event in series when transferring a file in ASCII mode to report each line being transferred.

TLSCertNeeded Event (FTPClient Component)

Fires when a remote TLS party requests a client certificate.

Syntax

type TTLSCertNeededEvent = procedure (
  Sender: TObject;
  const Host: String;
  const CANames: String
) of Object;

property OnTLSCertNeeded: TTLSCertNeededEvent read FOnTLSCertNeeded write FOnTLSCertNeeded;

Remarks

This event fires to notify the implementation that a remote TLS server has requested a client certificate. The Host parameter identifies the host that makes a request, and the CANames parameter (optional, according to the TLS spec) advises on the accepted issuing CAs.

Use the TLSClientChain property in response to this event to provide the requested certificate. Please make sure the client certificate includes the associated private key. Note that you may set the certificates before the connection without waiting for this event to fire.

This event is preceded by the TLSHandshake event for the given host and, if the certificate was accepted, succeeded by the TLSEstablished event.

TLSCertValidate Event (FTPClient Component)

This event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Syntax

type TTLSCertValidateEvent = procedure (
  Sender: TObject;
  const ServerHost: String;
  const ServerIP: String;
  var Accept: Boolean
) of Object;

property OnTLSCertValidate: TTLSCertValidateEvent read FOnTLSCertValidate write FOnTLSCertValidate;

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, components may contact a number of TLS endpoints during their work, depending on their configuration.

Accept is assigned in accordance with the outcome of the internal validation check performed by the component, and can be adjusted if needed.

TLSEstablished Event (FTPClient Component)

Fires when a TLS handshake with Host successfully completes.

Syntax

type TTLSEstablishedEvent = procedure (
  Sender: TObject;
  const Host: String;
  const Version: String;
  const Ciphersuite: String;
  ConnectionId: TBytes;
  var Abort: Boolean
) of Object;

property OnTLSEstablished: TTLSEstablishedEvent read FOnTLSEstablished write FOnTLSEstablished;

Remarks

The component uses this event to notify the application about a successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate the security parameters of the new connection. Use the Abort parameter if you need to terminate the connection at this stage.

TLSHandshake Event (FTPClient Component)

Fires when a new TLS handshake is initiated, before the handshake commences.

Syntax

type TTLSHandshakeEvent = procedure (
  Sender: TObject;
  const Host: String;
  var Abort: Boolean
) of Object;

property OnTLSHandshake: TTLSHandshakeEvent read FOnTLSHandshake write FOnTLSHandshake;

Remarks

The component uses this event to notify the application about the start of a new TLS handshake to Host. If the handshake is successful, this event will be followed by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSPSK Event (FTPClient Component)

Notifies the application about the PSK key exchange.

Syntax

type TTLSPSKEvent = procedure (
  Sender: TObject;
  const Host: String;
  const Hint: String
) of Object;

property OnTLSPSK: TTLSPSKEvent read FOnTLSPSK write FOnTLSPSK;

Remarks

The component fires this event to notify the application about the beginning of TLS-PSK key exchange with Host. The Hint parameter may be used by the server to identify the key or service to use. Use the PreSharedKey field of TLSSettings to provide the pre-shared key to the component.

TLSShutdown Event (FTPClient Component)

Reports the graceful closure of a TLS connection.

Syntax

type TTLSShutdownEvent = procedure (
  Sender: TObject;
  const Host: String
) of Object;

property OnTLSShutdown: TTLSShutdownEvent read FOnTLSShutdown write FOnTLSShutdown;

Remarks

This event notifies the application about the closure of an earlier established TLS connection. Note that only graceful connection closures are reported.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

Creates a new object with default field values.

ConnectionInfo Type

Contains information about a network connection.

Remarks

Use this property to check various details of the network connection. These include the total amounts of data transferred, the availability of TLS, and its parameters.

Fields

Constructors

>

constructor Create();

Creates a new ConnectionInfo object.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

>

constructor Create();

Creates an empty CRL object.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

>

constructor Create();

Creates a new ExternalCrypto object with default field values.

FTPListEntry Type

Represents a basic container for the remote file details.

Remarks

The component represents the details of a file entry returned by the FTP server.

Fields

Constructors

>

constructor Create();

Creates a new FTPListEntry object.

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRLs).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

>

constructor Create();

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

>

constructor Create();

Creates a new ProxySettings object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

>

constructor Create();

Creates a new SocketSettings object.

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

>

constructor Create();

Creates a new TLSSettings object.

Config Settings (FTPClient Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

FTPClient Config Settings

Base Config Settings

Trappable Errors (FTPClient Component)

FTPClient Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Component is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) 
	18874368   Unsupported file operation (SB_ERROR_FTP_UNSUPPORTED_FILEOPERATION)