Struct ipworks::FTP

Properties   Methods   Events   Config Settings   Errors  

The FTP Struct can be used to transfer files to and from FTP servers using the FTP protocol.

Syntax

ipworks::FTP

Remarks

The FTP Struct supports both plaintext and Secure Sockets Layer/Transport Layer Security (SSL/TLS) connections. When connecting over Secure Sockets Layer/Transport Layer Security (SSL/TLS) the on_ssl_server_authentication event allows you to check the server identity and other security attributes. The on_ssl_status event provides information about the SSL handshake. Additional SSL-related settings are also supported through the config method.

The FTP Struct implements a standard FTP client as specified in RFC 959 and RFC 1579 with the added option of SSL security (RFC 2228) in both the protocol and data channels.

The first step in using the struct is specifying the remote_host, user and password. The file to upload to or download from is given by the remote_file property. The file to download to or upload from is specified by local_file. The current path in the server is set by calling change_remote_path. The passive property is especially useful if the client is behind a firewall, which inhibits incoming connections to higher ports.

If local_file is set to something other than an empty string, then files are received in local_file, and otherwise data are received through the on_transfer event. on_start_transfer and on_end_transfer are fired at the beginning and end of transmission.

The on_pi_trail event traces the interaction between the client and the server (the FTP protocol interface connection).

Directory listings are received through the on_dir_list event.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorks. Due to this, the FTP struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of FTP when you have finished using the instance.

Property List

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

Method List

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

Event List

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

Config Settings

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

account property (FTP Struct)

The property includes the user account needed to log in.

Syntax

fn account(&self ) -> Result<String, IPWorksError> 
fn set_account(&self, value : &str) ->  Option<IPWorksError> 
fn set_account_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property contains the user account to use when logging in. Some servers may require an account to logon or to access specific privileges, such as uploading or deleting files.

Data Type

String

connected property (FTP Struct)

Whether the struct is connected.

Syntax

fn connected(&self ) -> Result<bool, IPWorksError> 

Default Value

false

Remarks

This property is used to determine whether or not the struct is connected to the remote host. Use the connect and disconnect methods to manage the connection.

This property is read-only.

Data Type

bool

dir_list_count property (FTP Struct)

The number of records in the DirList arrays.

Syntax

fn dir_list_count(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• dir_list_entry
• dir_list_file_name
• dir_list_file_size
• dir_list_file_time
• dir_list_is_dir

The array indices start at 0 and end at dir_list_count - 1.

This property is read-only.

Data Type

i32

dir_list_entry property (FTP Struct)

This property contains the raw entry as received from the server.

Syntax

fn dir_list_entry(&self , EntryIndex : i32) -> Result<String, IPWorksError> 

Default Value

""

Remarks

This property contains the raw entry as received from the server. It is the complete unparsed entry in the directory listing.

The EntryIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DirListCount property.

This property is read-only.

Data Type

String

dir_list_file_name property (FTP Struct)

This property shows the file name in the last directory listing.

Syntax

fn dir_list_file_name(&self , EntryIndex : i32) -> Result<String, IPWorksError> 

Default Value

""

Remarks

This property shows the file name in the last directory listing. This also may be the directory name if a directory is being listed. You can tell whether it is a file or a directory by the Boolean dir_list_is_dir property.

The EntryIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DirListCount property.

This property is read-only.

Data Type

String

dir_list_file_size property (FTP Struct)

This property shows the file size in the last directory listing.

Syntax

fn dir_list_file_size(&self , EntryIndex : i32) -> Result<i64, IPWorksError> 

Default Value

0

Remarks

This property shows the file size in the last directory listing.

The EntryIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DirListCount property.

This property is read-only.

Data Type

i64

dir_list_file_time property (FTP Struct)

This property shows the file time in the last directory listing.

Syntax

fn dir_list_file_time(&self , EntryIndex : i32) -> Result<String, IPWorksError> 

Default Value

""

Remarks

This property shows the file time in the last directory listing. This contains the date/time stamp in which the file was created.

NOTE: In Unix systems, the date is given in two types of formats: If the date is in the past 12 months, the exact time is specified and the year is omitted. Otherwise, only the date and the year, but not hours or minutes, are given.

The EntryIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DirListCount property.

This property is read-only.

Data Type

String

dir_list_is_dir property (FTP Struct)

This property specifies whether entries in the last directory listing are directories.

Syntax

fn dir_list_is_dir(&self , EntryIndex : i32) -> Result<bool, IPWorksError> 

Default Value

false

Remarks

This property specifies whether entries in the last directory listing are directories. This Boolean value denotes whether or not the directory entry listed in dir_list_file_name is a file or a directory.

The EntryIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DirListCount property.

This property is read-only.

Data Type

bool

firewall_auto_detect property (FTP Struct)

Whether to automatically detect and use firewall system settings, if available.

Syntax

fn firewall_auto_detect(&self ) -> Result<bool, IPWorksError> 
fn set_firewall_auto_detect(&self, value : bool) ->  Option<IPWorksError> 

Default Value

false

Remarks

Whether to automatically detect and use firewall system settings, if available.

Data Type

bool

firewall_type property (FTP Struct)

The type of firewall to connect through.

Syntax

fn firewall_type(&self ) -> Result<i32, IPWorksError> 
fn set_firewall_type(&self, value : i32) ->  Option<IPWorksError> 

Possible Values

0   // None
1   // Tunnel
2   // SOCKS4
3   // SOCKS5
10   // SOCKS4A

Default Value

0

Remarks

The type of firewall to connect through. The applicable values are as follows:

Data Type

i32

firewall_host property (FTP Struct)

The name or IP address of the firewall (optional).

Syntax

fn firewall_host(&self ) -> Result<String, IPWorksError> 
fn set_firewall_host(&self, value : &str) ->  Option<IPWorksError> 
fn set_firewall_host_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

The name or IP address of the firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the struct fails with an error.

Data Type

String

firewall_password property (FTP Struct)

A password if authentication is to be used when connecting through the firewall.

Syntax

fn firewall_password(&self ) -> Result<String, IPWorksError> 
fn set_firewall_password(&self, value : &str) ->  Option<IPWorksError> 
fn set_firewall_password_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the struct fails with an error.

Data Type

String

firewall_port property (FTP Struct)

The Transmission Control Protocol (TCP) port for the firewall Host .

Syntax

fn firewall_port(&self ) -> Result<i32, IPWorksError> 
fn set_firewall_port(&self, value : i32) ->  Option<IPWorksError> 

Default Value

0

Remarks

The Transmission Control Protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

NOTE: This property is set automatically when firewall_firewall_type is set to a valid value. See the description of the firewall_firewall_type property for details.

Data Type

i32

firewall_user property (FTP Struct)

A username if authentication is to be used when connecting through a firewall.

Syntax

fn firewall_user(&self ) -> Result<String, IPWorksError> 
fn set_firewall_user(&self, value : &str) ->  Option<IPWorksError> 
fn set_firewall_user_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

A username if authentication is to be used when connecting through a firewall. If firewall_host is specified, this property and the firewall_password property are used to connect and authenticate to the given Firewall. If the authentication fails, the struct fails with an error.

Data Type

String

idle property (FTP Struct)

The current status of the struct.

Syntax

fn idle(&self ) -> Result<bool, IPWorksError> 

Default Value

true

Remarks

This property will be False if the component is currently busy (communicating or waiting for an answer), and True at all other times.

This property is read-only.

Data Type

bool

last_reply property (FTP Struct)

This property indicates the last reply received from the server.

Syntax

fn last_reply(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

This property indicates the last reply received from the server. It can be used for informational purposes. The same information and more also can be retrieved through the on_pi_trail event.

This property is read-only.

Data Type

String

local_file property (FTP Struct)

This is the path to a local file for download or upload. If the file exists, it is overwritten.

Syntax

fn local_file(&self ) -> Result<String, IPWorksError> 
fn set_local_file(&self, value : &str) ->  Option<IPWorksError> 
fn set_local_file_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property is used by the upload and download methods to specify the path to a local file to be downloaded or uploaded. See the method descriptions for more information.

Example (Setting LocalFile)

FTPControl.LocalFile = "C:\localfile.txt" FTPControl.RemoteFile = "remotefile.txt" FTPControl.Download() FTPControl.LocalFile = "C:\localfile2.txt" FTPControl.RemoteFile = "folder/remotefile2.txt" FTPControl.Download()

Data Type

String

local_host property (FTP Struct)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

fn local_host(&self ) -> Result<String, IPWorksError> 
fn set_local_host(&self, value : &str) ->  Option<IPWorksError> 
fn set_local_host_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the struct initiate connections (or accept in the case of server structs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the struct is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: local_host is not persistent. You must always set it in code, and never in the property window.

Data Type

String

overwrite property (FTP Struct)

This indicates whether or not the struct should overwrite files during transfer.

Syntax

fn overwrite(&self ) -> Result<bool, IPWorksError> 
fn set_overwrite(&self, value : bool) ->  Option<IPWorksError> 

Default Value

false

Remarks

This property is a value indicating whether or not the struct should overwrite downloaded files. If overwrite is False, an error will be thrown whenever local_file exists before a download operation.

Data Type

bool

passive property (FTP Struct)

This controls whether or not to direct the server into a passive mode. It is recommended if behind a firewall.

Syntax

fn passive(&self ) -> Result<bool, IPWorksError> 
fn set_passive(&self, value : bool) ->  Option<IPWorksError> 

Default Value

true

Remarks

This property controls whether or not to direct the server into a passive mode. Many firewalls will not allow the FTP server to open a connection from outside to the higher ports where the FTP client struct expects them to be. If passive is set to TRUE, the struct will use the PASV command instead of the PORT command and thus will direct the server into a passive mode: connections are initiated only by the client.

Data Type

bool

password property (FTP Struct)

This is the password used to log in.

Syntax

fn password(&self ) -> Result<String, IPWorksError> 
fn set_password(&self, value : &str) ->  Option<IPWorksError> 
fn set_password_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property contains the password used to log in. It must be set before the struct connects to the FTP server.

Data Type

String

remote_file property (FTP Struct)

This is the name of the remote file for uploading, downloading, and performing other operations.

Syntax

fn remote_file(&self ) -> Result<String, IPWorksError> 
fn set_remote_file(&self, value : &str) ->  Option<IPWorksError> 
fn set_remote_file_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property contains the name of the remote file to be uploaded or downloaded and is either an absolute file path or a relative path based on the remote path set by calling change_remote_path.

A number of methods use remote_file as an argument.

Example 1. Setting RemoteFile:

FTPControl.LocalFile = "C:\localfile.txt" FTPControl.RemoteFile = "remotefile.txt" FTPControl.Download() FTPControl.LocalFile = "C:\localfile2.txt" FTPControl.RemoteFile = "folder/remotefile2.txt" FTPControl.Download()

NOTE: As long as file masks are supported by the server, then this property will act as a file mask when performing list_directory or list_directory_long. If not supported, then ApplyFileMaskLocally could be set to True to filter the results locally.

Example 2. Using RemoteFile as a file mask: FTPControl.RemoteFile = "*.txt" FTPControl.ListDirectory()

The following special characters are supported for pattern matching:

If these characters need to be used as a literal in a pattern, then they must be escaped by surrounding them with brackets []. NOTE: "]" and "-" do not need to be escaped. See below for the escape sequences:

For example, to match the value [Something].txt, specify the pattern [[]Something].txt.

Data Type

String

remote_host property (FTP Struct)

This is the domain name or IP address of the FTP server.

Syntax

fn remote_host(&self ) -> Result<String, IPWorksError> 
fn set_remote_host(&self, value : &str) ->  Option<IPWorksError> 
fn set_remote_host_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property specifies the IP address (IP number in dotted internet format) or the domain name of the FTP server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If this property is set to a domain name, a DNS request is initiated and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.

If the struct is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

Data Type

String

remote_port property (FTP Struct)

This is the port for the FTP service (default is 21).

Syntax

fn remote_port(&self ) -> Result<i32, IPWorksError> 
fn set_remote_port(&self, value : i32) ->  Option<IPWorksError> 

Default Value

21

Remarks

This property contains the port for the FTP service, which defaults to 21 if not set. A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

For an implicit Secure Sockets Layer (SSL), use port 990 (please see the ssl_start_mode property for more information).

Data Type

i32

ssl_accept_server_cert_effective_date property (FTP Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_accept_server_cert_effective_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_accept_server_cert_expiration_date property (FTP Struct)

The date on which the certificate expires.

Syntax

fn ssl_accept_server_cert_expiration_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_accept_server_cert_extended_key_usage property (FTP Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_accept_server_cert_extended_key_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint property (FTP Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint_sha1 property (FTP Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint_sha256 property (FTP Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_accept_server_cert_issuer property (FTP Struct)

The issuer of the certificate.

Syntax

fn ssl_accept_server_cert_issuer(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_accept_server_cert_private_key property (FTP Struct)

The private key of the certificate (if available).

Syntax

fn ssl_accept_server_cert_private_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_accept_server_cert_private_key may be available but not exportable. In this case, ssl_accept_server_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_accept_server_cert_private_key_available property (FTP Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_accept_server_cert_private_key_available(&self ) -> Result<bool, IPWorksError> 

Default Value

false

Remarks

Whether a ssl_accept_server_cert_private_key is available for the selected certificate. If ssl_accept_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_accept_server_cert_private_key_container property (FTP Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_accept_server_cert_private_key_container(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The name of the ssl_accept_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key property (FTP Struct)

The public key of the certificate.

Syntax

fn ssl_accept_server_cert_public_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key_algorithm property (FTP Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_accept_server_cert_public_key_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key_length property (FTP Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_accept_server_cert_public_key_length(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_accept_server_cert_serial_number property (FTP Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_accept_server_cert_serial_number(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_accept_server_cert_signature_algorithm property (FTP Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_accept_server_cert_signature_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_accept_server_cert_store property (FTP Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_accept_server_cert_store(&self ) -> Result<Vec<u8>, IPWorksError> 
fn set_ssl_accept_server_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksError> 
fn set_ssl_accept_server_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_accept_server_cert_store_type property denotes the type of the certificate store specified by ssl_accept_server_cert_store. If the store is password-protected, specify the password in ssl_accept_server_cert_store_password.

ssl_accept_server_cert_store is used in conjunction with the ssl_accept_server_cert_subject property to specify client certificates. If ssl_accept_server_cert_store has a value, and ssl_accept_server_cert_subject or ssl_accept_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_accept_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_accept_server_cert_store_password property (FTP Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_accept_server_cert_store_password(&self ) -> Result<String, IPWorksError> 
fn set_ssl_accept_server_cert_store_password(&self, value : &str) ->  Option<IPWorksError> 
fn set_ssl_accept_server_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_accept_server_cert_store_type property (FTP Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_accept_server_cert_store_type(&self ) -> Result<i32, IPWorksError> 
fn set_ssl_accept_server_cert_store_type(&self, value : i32) ->  Option<IPWorksError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_accept_server_cert_subject_alt_names property (FTP Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_accept_server_cert_subject_alt_names(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_md5 property (FTP Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_md5(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_sha1 property (FTP Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_sha256 property (FTP Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_usage property (FTP Struct)

The text description of UsageFlags .

Syntax

fn ssl_accept_server_cert_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of ssl_accept_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_accept_server_cert_usage_flags property (FTP Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_accept_server_cert_usage_flags(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_accept_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_accept_server_cert_usage property for a text representation of ssl_accept_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_accept_server_cert_version property (FTP Struct)

The certificate's version number.

Syntax

fn ssl_accept_server_cert_version(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_accept_server_cert_subject property (FTP Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_accept_server_cert_subject(&self ) -> Result<String, IPWorksError> 
fn set_ssl_accept_server_cert_subject(&self, value : &str) ->  Option<IPWorksError> 
fn set_ssl_accept_server_cert_subject_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_accept_server_cert_encoded property (FTP Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_accept_server_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksError> 
fn set_ssl_accept_server_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksError> 
fn set_ssl_accept_server_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

Data Type

Vec

ssl_cert_effective_date property (FTP Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_cert_effective_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_expiration_date property (FTP Struct)

The date on which the certificate expires.

Syntax

fn ssl_cert_expiration_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_extended_key_usage property (FTP Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_cert_extended_key_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_cert_fingerprint property (FTP Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha1 property (FTP Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha256 property (FTP Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_cert_issuer property (FTP Struct)

The issuer of the certificate.

Syntax

fn ssl_cert_issuer(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_cert_private_key property (FTP Struct)

The private key of the certificate (if available).

Syntax

fn ssl_cert_private_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_cert_private_key_available property (FTP Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_cert_private_key_available(&self ) -> Result<bool, IPWorksError> 

Default Value

false

Remarks

Whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_cert_private_key_container property (FTP Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_cert_private_key_container(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_cert_public_key property (FTP Struct)

The public key of the certificate.

Syntax

fn ssl_cert_public_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_cert_public_key_algorithm property (FTP Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_cert_public_key_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_public_key_length property (FTP Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_cert_public_key_length(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_cert_serial_number property (FTP Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_cert_serial_number(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_cert_signature_algorithm property (FTP Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_cert_signature_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_store property (FTP Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_cert_store(&self ) -> Result<Vec<u8>, IPWorksError> 
fn set_ssl_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksError> 
fn set_ssl_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_cert_store_password property (FTP Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_cert_store_password(&self ) -> Result<String, IPWorksError> 
fn set_ssl_cert_store_password(&self, value : &str) ->  Option<IPWorksError> 
fn set_ssl_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_cert_store_type property (FTP Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_cert_store_type(&self ) -> Result<i32, IPWorksError> 
fn set_ssl_cert_store_type(&self, value : i32) ->  Option<IPWorksError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_cert_subject_alt_names property (FTP Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_cert_subject_alt_names(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_md5 property (FTP Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_md5(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha1 property (FTP Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha256 property (FTP Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_usage property (FTP Struct)

The text description of UsageFlags .

Syntax

fn ssl_cert_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_cert_usage_flags property (FTP Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_cert_usage_flags(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_cert_version property (FTP Struct)

The certificate's version number.

Syntax

fn ssl_cert_version(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_cert_subject property (FTP Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_cert_subject(&self ) -> Result<String, IPWorksError> 
fn set_ssl_cert_subject(&self, value : &str) ->  Option<IPWorksError> 
fn set_ssl_cert_subject_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_cert_encoded property (FTP Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksError> 
fn set_ssl_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksError> 
fn set_ssl_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

Data Type

Vec

ssl_enabled property (FTP Struct)

This property indicates whether Transport Layer Security/Secure Sockets Layer (TLS/SSL) is enabled.

Syntax

fn ssl_enabled(&self ) -> Result<bool, IPWorksError> 
fn set_ssl_enabled(&self, value : bool) ->  Option<IPWorksError> 

Default Value

false

Remarks

This property specifies whether TLS/SSL is enabled in the struct. When False (default), the struct operates in plaintext mode. When True, TLS/SSL is enabled.

TLS/SSL may also be enabled by setting ssl_start_mode. Setting ssl_start_mode will automatically update this property value.

Data Type

bool

ssl_provider property (FTP Struct)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

fn ssl_provider(&self ) -> Result<i32, IPWorksError> 
fn set_ssl_provider(&self, value : i32) ->  Option<IPWorksError> 

Possible Values

0   // Automatic
1   // Platform
2   // Internal

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the struct will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are as follows:

In most cases using the default value (Automatic) is recommended. The struct will select a provider depending on the current platform.

When Automatic is selected, on Windows, the struct will use the platform implementation. On Linux/macOS, the struct will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the struct will always try and use the platform implementation. If the platform TLS 1.3 implementation is not available, the internal implementation will be used.

Data Type

i32

ssl_server_cert_effective_date property (FTP Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_server_cert_effective_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_server_cert_expiration_date property (FTP Struct)

The date on which the certificate expires.

Syntax

fn ssl_server_cert_expiration_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_server_cert_extended_key_usage property (FTP Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_server_cert_extended_key_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint property (FTP Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint_sha1 property (FTP Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint_sha256 property (FTP Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_server_cert_issuer property (FTP Struct)

The issuer of the certificate.

Syntax

fn ssl_server_cert_issuer(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_server_cert_private_key property (FTP Struct)

The private key of the certificate (if available).

Syntax

fn ssl_server_cert_private_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_server_cert_private_key may be available but not exportable. In this case, ssl_server_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_server_cert_private_key_available property (FTP Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_server_cert_private_key_available(&self ) -> Result<bool, IPWorksError> 

Default Value

false

Remarks

Whether a ssl_server_cert_private_key is available for the selected certificate. If ssl_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_server_cert_private_key_container property (FTP Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_server_cert_private_key_container(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The name of the ssl_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_server_cert_public_key property (FTP Struct)

The public key of the certificate.

Syntax

fn ssl_server_cert_public_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_server_cert_public_key_algorithm property (FTP Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_server_cert_public_key_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_server_cert_public_key_length property (FTP Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_server_cert_public_key_length(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_server_cert_serial_number property (FTP Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_server_cert_serial_number(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_server_cert_signature_algorithm property (FTP Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_server_cert_signature_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_server_cert_store property (FTP Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_server_cert_store(&self ) -> Result<Vec<u8>, IPWorksError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_server_cert_store_type property denotes the type of the certificate store specified by ssl_server_cert_store. If the store is password-protected, specify the password in ssl_server_cert_store_password.

ssl_server_cert_store is used in conjunction with the ssl_server_cert_subject property to specify client certificates. If ssl_server_cert_store has a value, and ssl_server_cert_subject or ssl_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

This property is read-only.

Data Type

Vec

ssl_server_cert_store_password property (FTP Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_server_cert_store_password(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is read-only.

Data Type

String

ssl_server_cert_store_type property (FTP Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_server_cert_store_type(&self ) -> Result<i32, IPWorksError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

This property is read-only.

Data Type

i32

ssl_server_cert_subject_alt_names property (FTP Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_server_cert_subject_alt_names(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_md5 property (FTP Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_md5(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_sha1 property (FTP Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_sha256 property (FTP Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_usage property (FTP Struct)

The text description of UsageFlags .

Syntax

fn ssl_server_cert_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of ssl_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_server_cert_usage_flags property (FTP Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_server_cert_usage_flags(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_server_cert_usage property for a text representation of ssl_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_server_cert_version property (FTP Struct)

The certificate's version number.

Syntax

fn ssl_server_cert_version(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_server_cert_subject property (FTP Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_server_cert_subject(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

This property is read-only.

Data Type

String

ssl_server_cert_encoded property (FTP Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_server_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_server_cert_store and ssl_server_cert_subject properties also may be used to specify a certificate.

When ssl_server_cert_encoded is set, a search is initiated in the current ssl_server_cert_store for the private key of the certificate. If the key is found, ssl_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_server_cert_subject is set to an empty string.

This property is read-only.

Data Type

Vec

ssl_start_mode property (FTP Struct)

This property determines how the struct starts the Secure Sockets Layer (SSL) negotiation.

Syntax

fn ssl_start_mode(&self ) -> Result<i32, IPWorksError> 
fn set_ssl_start_mode(&self, value : i32) ->  Option<IPWorksError> 

Possible Values

0   // Automatic
1   // Implicit
2   // Explicit
3   // None

Default Value

3

Remarks

The ssl_start_mode property may have one of the following values:

Data Type

i32

start_byte property (FTP Struct)

This is the byte index in RemoteFile and LocalFile from which to start a transmission.

Syntax

fn start_byte(&self ) -> Result<String, IPWorksError> 
fn set_start_byte(&self, value : &str) ->  Option<IPWorksError> 
fn set_start_byte_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

"0"

Remarks

This property contains a zero-based index in both remote_file and local_file that determines the point from which the transmission of data begins. This is useful for resuming interrupted downloads and uploads of files from FTP servers.

Once set, the start_byte index is used for all future downloads and uploads. The property must be reset to "0" for normal downloads and uploads.

The type of the property is a string instead of numeric value to allow for certain implementations that expect an alphanumeric marker for the start index.

In the on_transfer event, the TransferredBytes parameter will include the bytes skipped (i.e., it will show start_byte more bytes than actually transferred).

NOTE: Some FTP servers may not support the FTP REST command. If that is the case with the server you are accessing, you will not be able to use the start_byte property.

Data Type

String

timeout property (FTP Struct)

The timeout for the struct.

Syntax

fn timeout(&self ) -> Result<i32, IPWorksError> 
fn set_timeout(&self, value : i32) ->  Option<IPWorksError> 

Default Value

60

Remarks

If the timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If timeout is set to a positive value, the struct will wait for the operation to complete before returning control.

The struct will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not freeze and remains responsive.

If timeout expires, and the operation is not yet complete, the struct fails with an error.

NOTE: By default, all timeouts are inactivity timeouts, that is, the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the timeout property is 60 seconds.

Data Type

i32

transfer_mode property (FTP Struct)

This property indicates the transfer mode (ASCII or binary). If the value is 0 (default), the initial server mode will be used.

Syntax

fn transfer_mode(&self ) -> Result<i32, IPWorksError> 

Possible Values

0   // Default
1   // ASCII
2   // Binary

Default Value

0

Remarks

This property indicates the current transfer mode, which is either ASCII or binary. To change the transfer mode call the change_transfer_mode method. Possible values for this property are:

This property is read-only.

Data Type

i32

user property (FTP Struct)

This property contains the user identifier to use to log in.

Syntax

fn user(&self ) -> Result<String, IPWorksError> 
fn set_user(&self, value : &str) ->  Option<IPWorksError> 
fn set_user_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property contains the user identifier to be used when logging in. It must be set before the struct connects to the FTP server.

Data Type

String

abort method (FTP Struct)

The method aborts the current upload or download.

Syntax

fn abort(&self) -> Result<(), IPWorksError>

Remarks

This method sends an ABOR command to the FTP server. It is used to interrupt file uploads and downloads.

append method (FTP Struct)

This method appends data from LocalFile to a RemoteFile on an FTP server.

Syntax

fn append(&self) -> Result<(), IPWorksError>

Remarks

This method causes the server-data transfer process (DTP) to accept the data transferred through the data connection and to store the data in a file on the server site. If the file specified in the pathname exists on the server site, then the data shall be appended to that file; otherwise, the file specified in the pathname shall be created on the server site. This method is similar to the upload method, but the local file specified by local_file is appended to remote_file on the server as opposed to replacing it, as with the upload method. remote_file is either an absolute path on the server, or a path relative to the current path set by change_remote_path. The server will create a file with that name if it doesn't already exist (similar to upload). If no FTP session is in place, one is automatically created by first calling the logon method.

change_remote_path method (FTP Struct)

This method changes the current path on the FTP server.

Syntax

fn change_remote_path(&self, remote_path : &str) -> Result<(), IPWorksError>

Remarks

This method changes the current path on the FTP server to the specified remote_path. When called, the struct will issue a command to the server to change the directory. The remote_path parameter may hold an absolute or relative path.

Absolute Paths

If the path begins with a /, it is considered an absolute path and must specify the entire path from the root of the server. For instance:

component.ChangeRemotePath("/home/testuser/myfolder");

Relative Paths

If the path does not begin with a /, it is considered a relative path and is resolved in relation to the current directory. For instance, a value of myfolder will indicate a subfolder of the current directory. The special value .. refers to the parent directory of the current path. For instance:

//Change to the 'myfolder' sub-directory component.ChangeRemotePath("myfolder"); //Navigate up two levels and then into the 'another/folder' path. component.ChangeRemotePath("../../another/folder");

change_transfer_mode method (FTP Struct)

This method changes the transfer mode for the current connection.

Syntax

fn change_transfer_mode(&self, transfer_mode : i32) -> Result<(), IPWorksError>

Remarks

This method optionally changes the transfer mode used for the connection. The transfer_mode parameter indicates the new transfer mode to be used.

In many cases, it is not necessary to explicitly change the transfer mode; however, the binary transfer mode is useful to ensure that files are preserved byte-for-byte during the transfer. For instance, when uploading or downloading images or archives, the binary transfer mode will ensure that no line-ending transformations are performed by the server before data are transmitted.

Valid values for the transfer_mode parameter are as follows:

check_file_exists method (FTP Struct)

This method returns True if the file specified by RemoteFile exists on the server.

Syntax

fn check_file_exists(&self) ->  Result<bool, IPWorksError>

Remarks

This method sends a command to the server to determine if the file specified by remote_file exists. If the file exists, this method returns true, otherwise it returns false. remote_file must be specified before calling this method. For instance: component.ChangeRemotePath("/home/testuser/myfolder"); component.RemoteFile = "test.txt"; if(component.CheckFileExists()) { //Do something }

config method (FTP Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksError>

Remarks

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

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

This method connects to the FTP server without logging in.

Syntax

fn connect(&self) -> Result<(), IPWorksError>

Remarks

This method establishes a connection with the remote_host but does not log in. In most cases, it is recommended to use the logon method, which will both establish a connection and log in to the server.

This method may be useful in cases in which it is desirable to separate the connection and logon operations, for instance, confirming that a host is available by first creating the connection.

delete_file method (FTP Struct)

This method removes a file specified by FileName from an FTP server.

Syntax

fn delete_file(&self, file_name : &str) -> Result<(), IPWorksError>

Remarks

This method is used to remove a file specified by file_name from an FTP server. The remote file or directory specified by file_name is deleted. file_name is either an absolute path on the server, or a path relative to remote path set by change_remote_path. If no FTP session is in place, one is automatically created by first calling the logon method.

disconnect method (FTP Struct)

This method disconnects from the server without first logging off.

Syntax

fn disconnect(&self) -> Result<(), IPWorksError>

Remarks

This method immediately disconnects from the server without first logging off.

In most cases, the logoff method should be used to log off and disconnect from the server. Call the disconnect method in cases in which it is desirable to immediately disconnect without first logging off.

do_events method (FTP Struct)

This method processes events from the internal message queue.

Syntax

fn do_events(&self) -> Result<(), IPWorksError>

Remarks

When do_events is called, the struct processes any available events. If no events are available, it waits for a preset period of time, and then returns.

download method (FTP Struct)

This method downloads a RemoteFile from an FTP server.

Syntax

fn download(&self) -> Result<(), IPWorksError>

Remarks

This method is used to download the remote file specified by remote_file to the local file specified by local_file, or it is retrieved through the on_transfer event if the local_file property is "" (empty string). remote_file is either an absolute path on the server or a path relative to a remote path set by calling change_remote_path. If no FTP session is in place, one is automatically created by first calling the logon method.

Example (Download a File)

FTPControl.LocalFile = "C:\localfile.txt" FTPControl.RemoteFile = "remotefile.txt" FTPControl.Download() FTPControl.LocalFile = "C:\localfile2.txt" FTPControl.RemoteFile = "folder/remotefile2.txt" FTPControl.Download()

interrupt method (FTP Struct)

This method interrupts the current method.

Syntax

fn interrupt(&self) -> Result<(), IPWorksError>

Remarks

If there is no method in progress, interrupt simply returns, doing nothing.

list_directory method (FTP Struct)

List the current directory specified by ChangeRemotePath on an FTP server.

Syntax

fn list_directory(&self) -> Result<(), IPWorksError>

Remarks

This method is used to list the directory (or file mask) specified in remote_file. remote_file is either an absolute path on the server, or a path relative to the remote path set by change_remote_path. The file listing is received through the on_dir_list event.

Similar to list_directory_long, except that only file names are returned.

NOTE: Because remote_file acts as a file mask, to retrieve a complete directory listing remote_file should be set to an empty string or a mask like "*". If no FTP session is in place, one is automatically created by first calling the logon method.

list_directory_long method (FTP Struct)

This method lists extended directory information for the remote path specified by calling ChangeRemotePath .

Syntax

fn list_directory_long(&self) -> Result<(), IPWorksError>

Remarks

This method is used to request a directory (or file mask) listing specified in remote_file. remote_file is either an absolute path on the server, or a path relative to the remote path set by calling change_remote_path. The file listing is received through the on_dir_list event. Extended file information is returned.

NOTE: Because remote_file acts as a file mask, to retrieve a complete directory listing remote_file should be set to empty string or a mask like "*". If no FTP session is in place, one is automatically created by first calling the logon method.

logoff method (FTP Struct)

This method is used to log off from the FTP server by posting a QUIT command.

Syntax

fn logoff(&self) -> Result<(), IPWorksError>

Remarks

This method is used to log off from the FTP server by posting a QUIT command. If that fails, the connection is terminated by the local host.

logon method (FTP Struct)

This method is used to log on to the FTP RemoteHost using the current User and Password .

Syntax

fn logon(&self) -> Result<(), IPWorksError>

Remarks

This method is used to log on to the FTP server using the current user and password. If transfer_mode is not 0 (Default), then the FTP transfer mode is set to the appropriate value.

Example (Logging On)

FTPControl.RemoteHost = "ftpserver" FTPControl.User = "username" FTPControl.Password = "password" FTPControl.Logon()

make_directory method (FTP Struct)

This method is used to create a directory on the FTP server.

Syntax

fn make_directory(&self, new_dir : &str) -> Result<(), IPWorksError>

Remarks

This method is used to create a directory with a path specified by new_dir on the FTP server. new_dir is either an absolute path on the server, or a path relative to the remote path that is set by calling change_remote_path. If no FTP session is in place, one is automatically created by first calling the logon method.

NOTE: When make_directory is called, remote_file is changed to new_dir.

query_file_size method (FTP Struct)

This returns the size of the file specified by RemoteFile .

Syntax

fn query_file_size(&self) ->  Result<i64, IPWorksError>

Remarks

This method sends the SIZE command to the server to obtain the size (in bytes) of the file specified by remote_file. remote_file must be specified before calling this method. For instance: component.ChangeRemotePath("/home/testuser/myfolder"); component.RemoteFile = "test.txt"; long myFileSize = component.QueryFileSize();

If remote_file does not exist on the server, the struct fails with an error.

query_file_time method (FTP Struct)

This returns the modified time of the file specified by RemoteFile .

Syntax

fn query_file_time(&self) ->  Result<String, IPWorksError>

Remarks

This method sends the MDTM command to the server to obtain the modified time of the file specified by remote_file. The time returned by this method will be UTC time. remote_file must be specified before calling this method. For instance: component.ChangeRemotePath("/home/testuser/myfolder"); component.RemoteFile = "test.txt"; string myModifiedTime = component.QueryFileTime();

The FileTimeFormat configuration setting controls the format of the returned value.

query_remote_path method (FTP Struct)

This queries the server for the current path.

Syntax

fn query_remote_path(&self) ->  Result<String, IPWorksError>

Remarks

This method queries the server for the current path. When called, the struct will issue a command to the server to retrieve the current path value. The return value of this method is the path returned by the server. For instance:

string remotePath = component.QueryRemotePath();

remove_directory method (FTP Struct)

This removes a directory specified by DirName from an FTP server.

Syntax

fn remove_directory(&self, dir_name : &str) -> Result<(), IPWorksError>

Remarks

This method is used to remove a directory with path specified by dir_name from the FTP server. dir_name is either an absolute path on the server, or a path relative to the remote path set by calling change_remote_path. If no FTP session is in place, one is automatically created by first calling the logon method.

rename_file method (FTP Struct)

This changes the name of RemoteFile to NewName .

Syntax

fn rename_file(&self, new_name : &str) -> Result<(), IPWorksError>

Remarks

This method is used to change the name of a remote file, specified by remote_file to new_name. remote_file and new_name are either absolute paths on the server, or a path relative to a remote path set by calling change_remote_path. If no FTP session is in place, one is automatically created by first calling the logon method.

reset method (FTP Struct)

This method will reset the struct.

Syntax

fn reset(&self) -> Result<(), IPWorksError>

Remarks

This method will reset the struct's properties to their default values.

send_command method (FTP Struct)

This method sends the exact command directly to the server.

Syntax

fn send_command(&self, command : &str) -> Result<(), IPWorksError>

Remarks

This method sends the command specified by command to the server exactly as it is provided. Use this method to send additional or custom commands directly to the server.

After calling this method, check the last_reply property or monitor the on_pi_trail event to obtain the server's response.

store_unique method (FTP Struct)

This method uploads a file with a unique name to an FTP server.

Syntax

fn store_unique(&self) -> Result<(), IPWorksError>

Remarks

This method is used to upload a file with a unique name to an FTP server. This is similar to the upload method, but the server determines a unique name for the local_file to be saved on the current directory set by calling change_remote_path. The server includes the new name of the file in its response. The user should check the on_pi_trail event, or last_reply property to retrieve this generated filename.

upload method (FTP Struct)

This method uploads a file specified by LocalFile to an FTP server.

Syntax

fn upload(&self) -> Result<(), IPWorksError>

Remarks

This method uploads a local file specified by local_file to the remote file specified by remote_file. remote_file is either an absolute path on the server, or a path relative to the remote path set by calling change_remote_path. If no FTP session is in place, one is automatically created by first calling the logon method.

If you want to append to a server file, please refer to the append method.

Example 1: Upload a File

FTPControl.LocalFile = "C:\localfile.txt" FTPControl.RemoteFile = "remotefile.txt" FTPControl.Upload() FTPControl.LocalFile = "C:\localfile2.txt" FTPControl.RemoteFile = "folder/remotefile2.txt" FTPControl.Upload()

on_connection_status event (FTP Struct)

Fired to indicate changes in the connection state.

Syntax

// FTPConnectionStatusEventArgs carries the FTP ConnectionStatus event's parameters.
pub struct FTPConnectionStatusEventArgs {
  fn connection_event(&self) -> &String
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// FTPConnectionStatusEvent defines the signature of the FTP ConnectionStatus event's handler function.
pub trait FTPConnectionStatusEvent {
  fn on_connection_status(&self, sender : FTP, e : &mut FTPConnectionStatusEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_connection_status(&self) -> &'a dyn FTPConnectionStatusEvent;
  pub fn set_on_connection_status(&mut self, value : &'a dyn FTPConnectionStatusEvent);
  ...
}

Remarks

This event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The connection_event parameter indicates the type of connection event. Values may include the following:

on_dir_list event (FTP Struct)

This event is fired when a directory entry is received.

Syntax

// FTPDirListEventArgs carries the FTP DirList event's parameters.
pub struct FTPDirListEventArgs {
  fn dir_entry(&self) -> &String
  fn file_name(&self) -> &String
  fn is_dir(&self) -> bool
  fn file_size(&self) -> i64
  fn file_time(&self) -> &String
}

// FTPDirListEvent defines the signature of the FTP DirList event's handler function.
pub trait FTPDirListEvent {
  fn on_dir_list(&self, sender : FTP, e : &mut FTPDirListEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_dir_list(&self) -> &'a dyn FTPDirListEvent;
  pub fn set_on_dir_list(&mut self, value : &'a dyn FTPDirListEvent);
  ...
}

Remarks

The on_dir_list events are fired when a directory listing is received as a response to a list_directory or list_directory_long call.

The on_start_transfer and on_end_transfer events mark the beginning and end of the event stream.

The dir_entry parameter contains the filename when list_directory is called and includes extended file information when list_directory_long is called.

The struct tries to fill out the file_name, is_dir, file_size, and file_time parameters when calling the list_directory_long method. Except for file_name, these parameters are empty when a short "List Directory" is performed.

In Unix systems, the date is given in two types of formats: If the date is in the past 12 months the exact time is specified and the year is omitted. Otherwise, only the date and the year, but not hours or minutes, are given.

on_end_transfer event (FTP Struct)

This event is fired when a file finishes downloading or uploading.

Syntax

// FTPEndTransferEventArgs carries the FTP EndTransfer event's parameters.
pub struct FTPEndTransferEventArgs {
  fn direction(&self) -> i32
}

// FTPEndTransferEvent defines the signature of the FTP EndTransfer event's handler function.
pub trait FTPEndTransferEvent {
  fn on_end_transfer(&self, sender : FTP, e : &mut FTPEndTransferEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_end_transfer(&self) -> &'a dyn FTPEndTransferEvent;
  pub fn set_on_end_transfer(&mut self, value : &'a dyn FTPEndTransferEvent);
  ...
}

Remarks

The on_end_transfer event fires when a Data Interface connection is closed. This occurs when the file finishes transferring or a directory listing is finished.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_error event (FTP Struct)

Fired when information is available about errors during data delivery.

Syntax

// FTPErrorEventArgs carries the FTP Error event's parameters.
pub struct FTPErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// FTPErrorEvent defines the signature of the FTP Error event's handler function.
pub trait FTPErrorEvent {
  fn on_error(&self, sender : FTP, e : &mut FTPErrorEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_error(&self) -> &'a dyn FTPErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn FTPErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

The error_code parameter contains an error code, and the description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_pi_trail event (FTP Struct)

This event traces the commands sent to the server, and the respective replies.

Syntax

// FTPPITrailEventArgs carries the FTP PITrail event's parameters.
pub struct FTPPITrailEventArgs {
  fn direction(&self) -> i32
  fn message(&self) -> &String
}

// FTPPITrailEvent defines the signature of the FTP PITrail event's handler function.
pub trait FTPPITrailEvent {
  fn on_pi_trail(&self, sender : FTP, e : &mut FTPPITrailEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_pi_trail(&self) -> &'a dyn FTPPITrailEvent;
  pub fn set_on_pi_trail(&mut self, value : &'a dyn FTPPITrailEvent);
  ...
}

Remarks

The on_pi_trail event is useful for debugging purposes. It shows all of the interactions between the client and the server, line by line.

The message parameter contains the full text of the message. The direction parameter shows the originator of the message:

on_ssl_server_authentication event (FTP Struct)

Fired after the server presents its certificate to the client.

Syntax

// FTPSSLServerAuthenticationEventArgs carries the FTP SSLServerAuthentication event's parameters.
pub struct FTPSSLServerAuthenticationEventArgs {
  fn cert_encoded(&self) -> &[u8]
  fn cert_subject(&self) -> &String
  fn cert_issuer(&self) -> &String
  fn status(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// FTPSSLServerAuthenticationEvent defines the signature of the FTP SSLServerAuthentication event's handler function.
pub trait FTPSSLServerAuthenticationEvent {
  fn on_ssl_server_authentication(&self, sender : FTP, e : &mut FTPSSLServerAuthenticationEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_ssl_server_authentication(&self) -> &'a dyn FTPSSLServerAuthenticationEvent;
  pub fn set_on_ssl_server_authentication(&mut self, value : &'a dyn FTPSSLServerAuthenticationEvent);
  ...
}

Remarks

During this event, the client can decide whether or not to continue with the connection process. The accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When accept is False, status shows why the verification failed (otherwise, status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the accept parameter to True.

on_ssl_status event (FTP Struct)

Fired when secure connection progress messages are available.

Syntax

// FTPSSLStatusEventArgs carries the FTP SSLStatus event's parameters.
pub struct FTPSSLStatusEventArgs {
  fn message(&self) -> &String
}

// FTPSSLStatusEvent defines the signature of the FTP SSLStatus event's handler function.
pub trait FTPSSLStatusEvent {
  fn on_ssl_status(&self, sender : FTP, e : &mut FTPSSLStatusEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_ssl_status(&self) -> &'a dyn FTPSSLStatusEvent;
  pub fn set_on_ssl_status(&mut self, value : &'a dyn FTPSSLStatusEvent);
  ...
}

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

on_start_transfer event (FTP Struct)

This event fires when a file starts downloading or uploading.

Syntax

// FTPStartTransferEventArgs carries the FTP StartTransfer event's parameters.
pub struct FTPStartTransferEventArgs {
  fn direction(&self) -> i32
}

// FTPStartTransferEvent defines the signature of the FTP StartTransfer event's handler function.
pub trait FTPStartTransferEvent {
  fn on_start_transfer(&self, sender : FTP, e : &mut FTPStartTransferEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_start_transfer(&self) -> &'a dyn FTPStartTransferEvent;
  pub fn set_on_start_transfer(&mut self, value : &'a dyn FTPStartTransferEvent);
  ...
}

Remarks

The on_start_transfer event fires when a Data Interface connection is created. This is when the file starts transferring or a directory listing is started.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_transfer event (FTP Struct)

This event is fired during the file download or upload.

Syntax

// FTPTransferEventArgs carries the FTP Transfer event's parameters.
pub struct FTPTransferEventArgs {
  fn direction(&self) -> i32
  fn bytes_transferred(&self) -> i64
  fn percent_done(&self) -> i32
  fn text(&self) -> &[u8]
}

// FTPTransferEvent defines the signature of the FTP Transfer event's handler function.
pub trait FTPTransferEvent {
  fn on_transfer(&self, sender : FTP, e : &mut FTPTransferEventArgs);
}

impl <'a> FTP<'a> {
  pub fn on_transfer(&self) -> &'a dyn FTPTransferEvent;
  pub fn set_on_transfer(&mut self, value : &'a dyn FTPTransferEvent);
  ...
}

Remarks

One or more on_transfer events are fired during file transfer. The bytes_transferred parameter shows the number of bytes transferred since the beginning of the transfer.

text contains the portion of the file data being delivered.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

NOTE: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

Config Settings (FTP Struct)

FTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

Trappable Errors (FTP Struct)

FTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors