FTPClient Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

secureblackbox.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.

Method List

---

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

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.

Config Settings

---

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

AccountInfo Property (FTPClient Class)

Parameters for the ACCT command.

Syntax

public String getAccountInfo();


public void setAccountInfo(String 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 Class)

Enables or disables automatic adjustment of passive-mode addresses.

Syntax

public boolean isAdjustPasvAddress();


public void setAdjustPasvAddress(boolean 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 class 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 Class)

The certificates that must be rejected as trust anchors.

Syntax

public CertificateList getBlockedCertificates();


public void setBlockedCertificates(CertificateList 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 Class)

The TLS client certificate chain.

Syntax

public CertificateList getClientChain();


public void setClientChain(CertificateList clientChain);

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the class. 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 Class)

Indicates whether the class is connected to the server.

Syntax

public boolean isConnected();

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 Class)

Contains the control channel log of the FTP session.

Syntax

public String getControlChannelLog();

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 Class)

Returns the details of the control connection setup.

Syntax

public ConnectionInfo getControlConnectionInfo();

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 Class)

Contains the details of the file entry reported by ListEntry .

Syntax

public FTPListEntry getCurrentListEntry();

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 Class)

Returns the details of the data connection setup.

Syntax

public ConnectionInfo getDataConnectionInfo();

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 Class)

Enables or disables data channel encryption.

Syntax

public boolean isEncryptDataChannel();


public void setEncryptDataChannel(boolean 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 Class)

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

Remarks

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

This property is read-only.

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

FIPSMode Property (FTPClient Class)

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

KnownCertificates Property (FTPClient Class)

Additional certificates for chain validation.

Syntax

public CertificateList getKnownCertificates();


public void setKnownCertificates(CertificateList 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 certificates to be added to this collection is roughly equivalent to that of 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 Class)

Additional CRLs for chain validation.

Syntax

public CRLList getKnownCRLs();


public void setKnownCRLs(CRLList 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 Class)

Additional OCSP responses for chain validation.

Syntax

public OCSPResponseList getKnownOCSPs();


public void setKnownOCSPs(OCSPResponseList 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 Class)

Switches on data compression.

Syntax

public boolean isModeZ();


public void setModeZ(boolean modeZ);

Default Value

True

Remarks

Switches the in-flight data compression on/off.

PassiveMode Property (FTPClient Class)

Enables or disables passive transfer mode.

Syntax

public boolean isPassiveMode();


public void setPassiveMode(boolean 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 Class)

The connecting user's authentication password.

Syntax

public String getPassword();


public void setPassword(String password);

Default Value

""

Remarks

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

Proxy Property (FTPClient Class)

The proxy server settings.

Syntax

public ProxySettings getProxy();

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 Class)

The offset to restart the file transfer from.

Syntax

public long getRestartAt();


public void setRestartAt(long 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 Class)

The TLS server's certificate chain.

Syntax

public CertificateList getServerChain();

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 Class)

Manages network connection settings.

Syntax

public SocketSettings getSocketSettings();

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 Class)

Manages TLS layer settings.

Syntax

public TLSSettings getTLSSettings();

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 Class)

Sets the file transfer mode.

Syntax

public int getTransferType();


public void setTransferType(int transferType);


Enumerated values:
  public final static int cttText = 0;
  public final static int cttBinary = 1;

Default Value

1

Remarks

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

TrustedCertificates Property (FTPClient Class)

A list of trusted certificates for chain validation.

Syntax

public CertificateList getTrustedCertificates();


public void setTrustedCertificates(CertificateList 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 than that of 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 Class)

The connecting user's username (login name).

Syntax

public String getUsername();


public void setUsername(String username);

Default Value

""

Remarks

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

Abort Method (Ftpclient Class)

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

Syntax

public void abort();

Remarks

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

Acct Method (Ftpclient Class)

Sends an Account command.

Syntax

public void acct(String acctInfo);

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 Class)

Appends a byte array to a server-side file.

Syntax

public void appendBytes(byte[] bytes, String remoteFile);

Remarks

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

AppendFile Method (Ftpclient Class)

Uploads a file to the server.

Syntax

public void appendFile(String localFile, String remoteFile);

Remarks

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

AppendStream Method (Ftpclient Class)

Uploads a file to the server.

Syntax

public void appendStream(java.io.InputStream localStream, String remoteFile);

Remarks

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

ChangeDir Method (Ftpclient Class)

Changes the current directory.

Syntax

public void changeDir(String remoteDir);

Remarks

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

ClearCommandChannel Method (Ftpclient Class)

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

Syntax

public void clearCommandChannel(boolean gracefulSSLClosure);

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 Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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 Class)

Connects to the FTP server.

Syntax

public void connect(String address, int port);

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 Class)

Deletes a directory on the server.

Syntax

public void deleteDir(String remoteDir);

Remarks

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

DeleteFile Method (Ftpclient Class)

Deletes a file on the server.

Syntax

public void deleteFile(String remoteFile);

Remarks

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

DirExists Method (Ftpclient Class)

Checks if a directory exists on the server.

Syntax

public boolean dirExists(String remoteDir);

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 Class)

Disconnects from the server.

Syntax

public void disconnect();

Remarks

Call this method to disconnect from the server.

DoAction Method (Ftpclient Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. 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 insencitive) 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 Class)

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

Syntax

public byte[] downloadBytes(String remoteFile);

Remarks

Use this method to download RemoteFile into a byte array.

DownloadFile Method (Ftpclient Class)

Downloads a file from the server.

Syntax

public void downloadFile(String remoteFile, String localFile);

Remarks

Use this method to download RemoteFile into LocalFile.

DownloadFiles Method (Ftpclient Class)

Downloads multiple files from the server.

Syntax

public void downloadFiles(String remotePath, String localDir);

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 Class)

Downloads a file from the server into a stream.

Syntax

public void downloadStream(String remoteFile, java.io.OutputStream localStream);

Remarks

Use this method to download RemoteFile into a stream object.

FileExists Method (Ftpclient Class)

Checks if a file exists on the server.

Syntax

public boolean fileExists(String remoteFile);

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 Class)

Returns the server-side current directory.

Syntax

public String getCurrentDir();

Remarks

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

GetFileSize Method (Ftpclient Class)

Returns the size of a remote file.

Syntax

public long getFileSize(String remoteFile);

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 Class)

Lists the contents of a remote directory.

Syntax

public String listDir(boolean includeFiles, boolean includeDirectories);

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 Class)

Creates a new directory on the server.

Syntax

public void makeDir(String remoteDir);

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 Class)

Sends a NOOP command to the server.

Syntax

public void noop();

Remarks

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

Rename Method (Ftpclient Class)

Renames a file.

Syntax

public void rename(String sourceFile, String destFile);

Remarks

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

SendCommand Method (Ftpclient Class)

Sends a custom command to the server.

Syntax

public int sendCommand(String command);

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 Class)

Uploads a byte array to the server.

Syntax

public void uploadBytes(byte[] bytes, String remoteFile);

Remarks

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

UploadFile Method (Ftpclient Class)

Uploads a file to the server.

Syntax

public void uploadFile(String localFile, String remoteFile);

Remarks

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

UploadFiles Method (Ftpclient Class)

Uploads multiple files to the server.

Syntax

public void uploadFiles(String localPath, String remoteDir);

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 Class)

Uploads a file to the server.

Syntax

public void uploadStream(java.io.InputStream localStream, String remoteFile);

Remarks

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

ControlReceive Event (Ftpclient Class)

Fires when data is received via the control channel.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void controlReceive(FtpclientControlReceiveEvent e) {}
  ...
}

public class FtpclientControlReceiveEvent {
  public String textLine;
}

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 Class)

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

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void controlSend(FtpclientControlSendEvent e) {}
  ...
}

public class FtpclientControlSendEvent {
  public String textLine;
}

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 Class)

Information about errors during data delivery.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void error(FtpclientErrorEvent e) {}
  ...
}

public class FtpclientErrorEvent {
  public int errorCode;
  public String description;
}

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 Class)

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

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void externalSign(FtpclientExternalSignEvent e) {}
  ...
}

public class FtpclientExternalSignEvent {
  public String operationId;
  public String hashAlgorithm;
  public String pars;
  public String data;
  public String signedData;
}

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 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 contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for 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 a .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 Class)

Marks the start of a file transfer.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void fileOperation(FtpclientFileOperationEvent e) {}
  ...
}

public class FtpclientFileOperationEvent {
  public int operation;
  public String remotePath;
  public String localPath;
  public boolean skip;
  public boolean cancel;
}

Remarks

The class 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 Class)

Reports the result of a file transfer operation.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void fileOperationResult(FtpclientFileOperationResultEvent e) {}
  ...
}

public class FtpclientFileOperationResultEvent {
  public int operation;
  public String remotePath;
  public String localPath;
  public int errorCode;
  public String comment;
  public boolean cancel;
}

Remarks

The class 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 Class)

Reports a single entry from the requested directory listing.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void listEntry(FtpclientListEntryEvent e) {}
  ...
}

public class FtpclientListEntryEvent {
  public String filename;
}

Remarks

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

Notification Event (Ftpclient Class)

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

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void notification(FtpclientNotificationEvent e) {}
  ...
}

public class FtpclientNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class 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 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 Class)

Reports the data transfer progress.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void progress(FtpclientProgressEvent e) {}
  ...
}

public class FtpclientProgressEvent {
  public long total;
  public long current;
  public boolean cancel;
}

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 Class)

Reports next transferred data line.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void textDataLine(FtpclientTextDataLineEvent e) {}
  ...
}

public class FtpclientTextDataLineEvent {
  public String textLine;
}

Remarks

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

TLSCertNeeded Event (Ftpclient Class)

Fires when a remote TLS party requests a client certificate.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void TLSCertNeeded(FtpclientTLSCertNeededEvent e) {}
  ...
}

public class FtpclientTLSCertNeededEvent {
  public String host;
  public String CANames;
}

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 (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 Class)

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

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void TLSCertValidate(FtpclientTLSCertValidateEvent e) {}
  ...
}

public class FtpclientTLSCertValidateEvent {
  public String serverHost;
  public String serverIP;
  public boolean accept;
}

Remarks

This event is fired during a TLS handshake. Use TLSServerChain property to access the certificate chain. In general case, 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 Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void TLSEstablished(FtpclientTLSEstablishedEvent e) {}
  ...
}

public class FtpclientTLSEstablishedEvent {
  public String host;
  public String version;
  public String ciphersuite;
  public byte[] connectionId;
  public boolean abort;
}

Remarks

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

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

TLSHandshake Event (Ftpclient Class)

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

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void TLSHandshake(FtpclientTLSHandshakeEvent e) {}
  ...
}

public class FtpclientTLSHandshakeEvent {
  public String host;
  public boolean abort;
}

Remarks

The class 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 with TLSEstablished event. If the server chooses to request a client certificate, TLSCertNeeded event will also be fired.

TLSPSK Event (Ftpclient Class)

Notifies the application about the PSK key exchange.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void TLSPSK(FtpclientTLSPSKEvent e) {}
  ...
}

public class FtpclientTLSPSKEvent {
  public String host;
  public String hint;
}

Remarks

The class 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 Class)

Reports the graceful closure of a TLS connection.

Syntax

public class DefaultFtpclientEventListener implements FtpclientEventListener {
  ...
  public void TLSShutdown(FtpclientTLSShutdownEvent e) {}
  ...
}

public class FtpclientTLSShutdownEvent {
  public String host;
}

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

public Certificate( bytes,  startIndex,  count,  password);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( bytes,  startIndex,  count);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

public Certificate( path,  password);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certPath,  keyPath,  password);

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

public Certificate( path);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

public Certificate( stream);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

public Certificate( stream,  password);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certStream,  keyStream,  password);

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

public Certificate();

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

public ConnectionInfo();

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

public CRL( bytes,  startIndex,  count);

Creates a CRL object from a memory buffer. Bytes is a buffer containing raw (DER) CRL data, StartIndex and Count specify the starting position and the length of the CRL data in the buffer, respectively.

public CRL( location);

Creates a CRL object by downloading it from a remote location.

public CRL( stream);

Creates a CRL object from data contained in a stream.

public CRL();

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

public ExternalCrypto();

Creates a new ExternalCrypto object with default field values.

FTPListEntry Type

Represents a basic container for the remote file details.

Remarks

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

Fields

Constructors

public FTPListEntry();

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 (CRL).

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

Fields

Constructors

public OCSPResponse( bytes,  startIndex,  count);

Initializes the response from a memory buffer. Bytes is a buffer containing raw OCSP response data, StartIndex and Count specify the starting position and the number of bytes to be read from this buffer.

public OCSPResponse( location);

Downloads an OCSP response from a remote location.

public OCSPResponse( stream);

Initializes the response with the data from a stream.

public OCSPResponse();

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

public ProxySettings();

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

public SocketSettings();

Creates a new SocketSettings object.

TLSSettings Type

A container for TLS connection settings.

Remarks

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

Fields

Constructors

public TLSSettings();

Creates a new TLSSettings object.

Config Settings (Ftpclient Class)

The class 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 class, access to these internal properties is provided through the Config method.

FTPClient Config Settings

Base Config Settings

Trappable Errors (Ftpclient Class)

FTPClient Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Class 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)