Struct ipworksssh::SSHPlex

Properties   Methods   Events   Config Settings   Errors  

SSHPlex is a multiplexed struct that operates over a single Secure Shell (SSH) connection and allows file transfers using Secure File Transfer Protocol (SFTP) or Secure Copy Protocol (SCP). It can remotely execute commands using SExec or SShell.

Syntax

ipworksssh::SSHPlex

Remarks

The SSHPlex struct combines the functionality of the Secure Copy Protocol (SCP) struct, the Secure File Transfer Protocol (SFTP) struct, the SExec struct, and the SShell struct. All operations are performed over a single Secure Shell (SSH) connection.

The asynchronous design of the struct allows multiple operations to be performed simultaneously. For example, several SFTP file transfers may be started, and while the files are still transferring, commands may be executed over SExec. This is accomplished through the use of operation Ids to track ongoing and complete operations, and channel_type, which allows switching between SFTP, SCP, SExec, and SShell usage.

After establishing a connection, set channel_type to the desired protocol and set any relevant properties for the operation. Calling the desired method will return an operation Id (string) that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection.

When the operation completes, a corresponding event will fire indicating the success or failure of the operation. Examine the event parameters for further details. For instance, after calling upload, the on_upload_complete event will fire.

Ongoing operations may be canceled at any time by passing the operation Id to the cancel_operation method.

NOTE: The do_events method must be called frequently to process outstanding events. This is particularly important for SCP and SFTP operations. Call do_events in a loop for best results.

Authentication

Example. Logging On:

SSHPlexControl.SSHUser = "username" SSHPlexControl.SSHPassword = "password" SSHPlexControl.SSHLogon("sshHost", sshPort)

Channel Types

NOTE: cancel_operation and other methods not explicitly listed here are applicable to all channel types.

Listing Files and Folders

list_directory lists files and folders from the path specified by remote_path.

The directory entries are provided through the on_dir_list event and also through the dir_list property. SSHPlexControl.RemoteFile = ""; //Clear filemask SSHPlexControl.RemotePath = "MyFolder"; string opId = SSHPlexControl.ListDirectory(); // ListDirectory operates async so we must wait for it to finish while (SSHPlexControl.Operations.Keys.Contains(opId)) { SSHPlexControl.DoEvents(); } for (int i = 0; i < SSHPlexControl.DirList.Count; i++) { Console.WriteLine(SSHPlexControl.DirList[i].FileName); Console.WriteLine(SSHPlexControl.DirList[i].FileSize); Console.WriteLine(SSHPlexControl.DirList[i].FileTime); Console.WriteLine(SSHPlexControl.DirList[i].IsDir); }

The remote_file property may also be used as a filemask when listing files. For instance: SSHPlexControl.RemoteFile = "*.txt"; SSHPlexControl.ListDirectory();

NOTE: Because remote_file is used as a filemask, ensure that you clear or reset this value before calling list_directory

Downloading Files

The download method downloads a specific file.

Set remote_file to the name of the file to download before calling this method. If remote_file specifies only a filename, it will be downloaded from the path specified by remote_path. remote_file may also be set to an absolute path.

If local_file is set, the file will be saved to the specified location.

Code Example

SSHPlexControl.Localfile = "C:\localfile.txt"; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Download(); // Use Path in RemoteFile SSHPlexControl.Localfile = "C:\localfile2.txt"; SSHPlexControl.RemoteFile = "folder/remotefile2.txt"; string operationId = SSHPlexControl.Download();

Resuming Downloads

The struct also supports resuming failed downloads by using the start_byte property. If a download is interrupted or canceled, set start_byte to the appropriate offset before calling this method to resume the download.

string localFile = "C:\localfile.txt"; SSHPlexControl.Localfile = localFile; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Download(); // Cancel Download using the CancelOperation method SSHPlexControl.CancelOperation(operationId); // Get the size of the partially downloaded temp file and set StartByte SSHPlexControl.StartByte = new FileInfo(localFile).Length; // Resume download string operationId = SSHPlexControl.Download();

Uploading Files

The upload method is used to upload files. Set local_file to the name of the file to upload before calling this method.

remote_file should be set to either a relative or absolute path. If remote_file is not an absolute path, it will be uploaded relative to remote_path.

Code Example

SSHPlexControl.Localfile = "C:\localfile.txt"; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Upload(); // Use Path in RemoteFile SSHPlexControl.Localfile = "C:\localfile2.txt"; SSHPlexControl.RemoteFile = "folder/remotefile2.txt"; string operationId = SSHPlexControl.Upload();

Resuming Uploads

The struct also supports resuming failed uploads by using the start_byte property. If an upload is interrupted or canceled, set start_byte to the appropriate offset before calling this method to resume the upload.

string localFile = "C:\localfile.txt"; SSHPlexControl.Localfile = localFile; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Upload(); // Cancel Upload using the CancelOperation method SSHPlexControl.CancelOperation(operationId); // Get the size of the partially uploaded temp file and set StartByte SSHPlexControl.StartByte = SSHPlexControl.FileAttributes.Size; // Resume upload string operationId = SSHPlexControl.Upload();

Remote Execution

Executing commands on a remote host is done by using the cstSExec or cstSShell channel_type.

To execute a command, simply call the execute method with the command you wish to execute.

The output of the command is returned through the on_stdout event. Errors during command execution (the stderr stream) are given by the on_stderr 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 IPWorksSSH. Due to this, the SSHPlex struct cannot be disposed of automatically. Please, call the dispose(&self) method of SSHPlex 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.

channel_type property (SSHPlex Struct)

Specifies the channel type to be used by the struct.

Syntax

fn channel_type(&self) -> Result<i32, IPWorksSSHError> 
fn set_channel_type(&self, value : i32) ->  Option<IPWorksSSHError> 

Possible Values

0   // SShell
1   // SExec
2   // Scp
3   // Sftp

Default Value

0

Remarks

The channel_type property determines the protocol used by the component and therefore the applicable methods and properties for each channel. Valid values are as follows:

NOTE: cancel_operation and other methods not explicitly listed here are applicable to all channel types.

Data Type

i32

connected property (SSHPlex Struct)

Whether the struct is connected.

Syntax

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

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 (SSHPlex Struct)

The number of records in the DirList arrays.

Syntax

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

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
• dir_list_is_symlink

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 (SSHPlex Struct)

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

Syntax

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

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 dir_list_count property.

This property is read-only.

Data Type

String

dir_list_file_name property (SSHPlex Struct)

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

Syntax

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

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 dir_list_count property.

This property is read-only.

Data Type

String

dir_list_file_size property (SSHPlex Struct)

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

Syntax

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

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 dir_list_count property.

This property is read-only.

Data Type

i64

dir_list_file_time property (SSHPlex Struct)

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

Syntax

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

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 dir_list_count property.

This property is read-only.

Data Type

String

dir_list_is_dir property (SSHPlex Struct)

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

Syntax

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

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 dir_list_count property.

This property is read-only.

Data Type

bool

dir_list_is_symlink property (SSHPlex Struct)

This property indicates whether the entry is a symbolic link.

Syntax

fn dir_list_is_symlink(&self, EntryIndex : i32) -> Result<bool, IPWorksSSHError> 

Default Value

false

Remarks

This property indicates whether the entry is a symbolic link. When the entry is a symbolic link, the value of dir_list_is_dir will always be False because this information is not returned in the directory listing. To inspect a symlink to determine if it is a link to a file or a folder, set remote_file and query the file_attributes.sftp_file_is_dir property.

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

This property is read-only.

Data Type

bool

sftp_file_access_time property (SSHPlex Struct)

Contains the number of milliseconds since 12:00:00 AM, January 1, 1970, when this file was last accessed.

Syntax

fn sftp_file_access_time(&self) -> Result<i64, IPWorksSSHError> 
fn set_sftp_file_access_time(&self, value : i64) ->  Option<IPWorksSSHError> 

Default Value

0

Remarks

Contains the number of milliseconds since 12:00:00 AM, January 1, 1970, when this file was last accessed.

Data Type

i64

sftp_file_acl property (SSHPlex Struct)

Contains a string containing an access control list (ACL).

Syntax

fn sftp_file_acl(&self) -> Result<String, IPWorksSSHError> 
fn set_sftp_file_acl(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_sftp_file_acl_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

Contains a string containing an access control list (ACL).

Data Type

String

sftp_file_allocation_size property (SSHPlex Struct)

Specifies the size, in bytes, that this file consumes on disk.

Syntax

fn sftp_file_allocation_size(&self) -> Result<i64, IPWorksSSHError> 

Default Value

0

Remarks

Specifies the size, in bytes, that this file consumes on disk.

This property is read-only.

Data Type

i64

sftp_file_attribute_bits property (SSHPlex Struct)

AttributeBits and AttributeBitsValid each contain a bitmask representing attributes of the file on the secure file transfer protocol (SFTP) server.

Syntax

fn sftp_file_attribute_bits(&self) -> Result<i32, IPWorksSSHError> 

Default Value

0

Remarks

sftp_file_attribute_bits and sftp_file_attribute_bits_valid each contain a bitmask representing attributes of the file on the secure file transfer protocol (SFTP) server. These two values must be interpreted together. Any value present in sftp_file_attribute_bits_valid must be ignored in sftp_file_attribute_bits. This is done so that the server and client can communicate the attributes they know about without confusing any bits they do not understand.

This field can have one or more of the following values ORed together:

• 0x00000001 (SSH_FILEXFER_ATTR_FLAGS_READONLY)
• 0x00000002 (SSH_FILEXFER_ATTR_FLAGS_SYSTEM)
• 0x00000004 (SSH_FILEXFER_ATTR_FLAGS_HIDDEN)
• 0x00000008 (SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE)
• 0x00000010 (SSH_FILEXFER_ATTR_FLAGS_ARCHIVE)
• 0x00000020 (SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED)
• 0x00000040 (SSH_FILEXFER_ATTR_FLAGS_COMPRESSED)
• 0x00000080 (SSH_FILEXFER_ATTR_FLAGS_SPARSE)
• 0x00000100 (SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY)
• 0x00000200 (SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE)
• 0x00000400 (SSH_FILEXFER_ATTR_FLAGS_SYNC)
• 0x00000800 (SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR)

This property is read-only.

Data Type

i32

sftp_file_attribute_bits_valid property (SSHPlex Struct)

AttributeBits and AttributeBitsValid each contain a bitmask representing attributes of the file on the secure file transfer protocol (SFTP) server.

Syntax

fn sftp_file_attribute_bits_valid(&self) -> Result<i32, IPWorksSSHError> 

Default Value

0

Remarks

sftp_file_attribute_bits and sftp_file_attribute_bits_valid each contain a bitmask representing attributes of the file on the secure file transfer protocol (SFTP) server. These two values must be interpreted together. Any value present in sftp_file_attribute_bits_valid must be ignored in sftp_file_attribute_bits. This is done so that the server and client can communicate the attributes they know about without confusing any bits they do not understand.

This field can have one or more of the following values ORed together:

• 0x00000001 (SSH_FILEXFER_ATTR_FLAGS_READONLY)
• 0x00000002 (SSH_FILEXFER_ATTR_FLAGS_SYSTEM)
• 0x00000004 (SSH_FILEXFER_ATTR_FLAGS_HIDDEN)
• 0x00000008 (SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE)
• 0x00000010 (SSH_FILEXFER_ATTR_FLAGS_ARCHIVE)
• 0x00000020 (SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED)
• 0x00000040 (SSH_FILEXFER_ATTR_FLAGS_COMPRESSED)
• 0x00000080 (SSH_FILEXFER_ATTR_FLAGS_SPARSE)
• 0x00000100 (SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY)
• 0x00000200 (SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE)
• 0x00000400 (SSH_FILEXFER_ATTR_FLAGS_SYNC)
• 0x00000800 (SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR)

This property is read-only.

Data Type

i32

sftp_file_creation_time property (SSHPlex Struct)

Specifies the number of milliseconds since 12:00:00 AM, January 1, 1970, when this file was created.

Syntax

fn sftp_file_creation_time(&self) -> Result<i64, IPWorksSSHError> 
fn set_sftp_file_creation_time(&self, value : i64) ->  Option<IPWorksSSHError> 

Default Value

0

Remarks

Specifies the number of milliseconds since 12:00:00 AM, January 1, 1970, when this file was created.

Data Type

i64

sftp_file_type property (SSHPlex Struct)

The type of file.

Syntax

fn sftp_file_type(&self) -> Result<i32, IPWorksSSHError> 

Possible Values

1   // Regular
2   // Directory
3   // SymLink
4   // Special
5   // Unknown
6   // Socket
7   // CharDevice
8   // BlockDevice
9   // FIFO

Default Value

0

Remarks

The type of file. sftp_file_type may be one of the following values:

This property is read-only.

Data Type

i32

sftp_file_group_id property (SSHPlex Struct)

Specifies the Id of the group that has access rights this file.

Syntax

fn sftp_file_group_id(&self) -> Result<String, IPWorksSSHError> 
fn set_sftp_file_group_id(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_sftp_file_group_id_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

Specifies the Id of the group that has access rights this file.

Data Type

String

sftp_file_is_dir property (SSHPlex Struct)

Specifies whether or not the file represented by these attributes is a directory.

Syntax

fn sftp_file_is_dir(&self) -> Result<bool, IPWorksSSHError> 

Default Value

false

Remarks

Specifies whether or not the file represented by these attributes is a directory.

This property is read-only.

Data Type

bool

sftp_file_is_symlink property (SSHPlex Struct)

Specifies whether or not the file or directory represented by these attributes is a symbolic link.

Syntax

fn sftp_file_is_symlink(&self) -> Result<bool, IPWorksSSHError> 

Default Value

false

Remarks

Specifies whether or not the file or directory represented by these attributes is a symbolic link. This setting is applicable only when GetSymlinkAttrs is set to True. By default, the attributes of the actual file referred to by the link (not the symbolic link) are returned and this property will always be False.

This property is read-only.

Data Type

bool

sftp_file_modified_time property (SSHPlex Struct)

Specifies the number of milliseconds since 12:00:00 AM, January 1, 1970, that this file was last modified.

Syntax

fn sftp_file_modified_time(&self) -> Result<i64, IPWorksSSHError> 
fn set_sftp_file_modified_time(&self, value : i64) ->  Option<IPWorksSSHError> 

Default Value

0

Remarks

Specifies the number of milliseconds since 12:00:00 AM, January 1, 1970, that this file was last modified.

Data Type

i64

sftp_file_owner_id property (SSHPlex Struct)

Specifies the user Id of this file's owner.

Syntax

fn sftp_file_owner_id(&self) -> Result<String, IPWorksSSHError> 
fn set_sftp_file_owner_id(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_sftp_file_owner_id_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

Specifies the user Id of this file's owner.

Data Type

String

sftp_file_permissions property (SSHPlex Struct)

Includes a 32-bit integer containing the a POSIX-compatible file permission bitmask.

Syntax

fn sftp_file_permissions(&self) -> Result<i32, IPWorksSSHError> 
fn set_sftp_file_permissions(&self, value : i32) ->  Option<IPWorksSSHError> 

Default Value

0

Remarks

The bitmask should be interpreted as a decimal value of a series of octal digits. For example, an octal permission value of "100644" would be "33188" in Base10, and "40755" in octal would be "16877" in Base10.

The last three octal digits are the most significant and represent, in order, the file access capabilities of the file's owner, the owner's group, and other users. Each of these octal digits is, on its own, a 3-bit bitmask with the following possible values:

An octal permission digit of 7 would have all three values set and would mean that the file can be read, written, and executed by that user class. For example, the octal permissions "100644" would have a value "6" for the owner, "4" for the group, and "4" for other users. This would be interpreted to mean that all users can read the file, no users can execute it, and only the owner can write it. The permissions "40755" would mean that all users can read and execute the file, but only the owner can write it.

The previous octal digit is another bitmask with the following values:

The previous two octal digits are used together as a bitmask to determine the type of file. This bitmask has the following values:

For example, the octal file permissions "100644" would indicate a regular file and octal "40755" would indicate a directory.

NOTE: You will need to convert the octal permissions bitmask into its decimal representation.

Data Type

i32

sftp_file_permissions_octal property (SSHPlex Struct)

Includes an octal string containing the a POSIX-compatible file permission bitmask.

Syntax

fn sftp_file_permissions_octal(&self) -> Result<String, IPWorksSSHError> 
fn set_sftp_file_permissions_octal(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_sftp_file_permissions_octal_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

The bitmask should be interpreted as a series of octal digits. For example, "100644" and "40755".

The last three octal digits are the most significant and represent, in order, the file access capabilities of the file's owner, the owner's group, and other users. Each of these octal digits is, on its own, a 3-bit bitmask with the following possible values:

An octal permission digit of 7 would have all three values set and would mean that the file can be read, written, and executed by that user class. For example, the octal permissions "100644" would have a value "6" for the owner, "4" for the group, and "4" for other users. This would be interpreted to mean that all users can read the file, no users can execute it, and only the owner can write it. The permissions "40755" would mean that all users can read and execute the file, but only the owner can write it.

The previous octal digit is another bitmask with the following values:

The previous two octal digits are used together as a bitmask to determine the type of file. This bitmask has the following values:

For example, the octal file permissions "100644" would indicate a regular file and octal "40755" would indicate a directory.

Data Type

String

sftp_file_size property (SSHPlex Struct)

Specifies the total size, in bytes, of this file.

Syntax

fn sftp_file_size(&self) -> Result<i64, IPWorksSSHError> 

Default Value

0

Remarks

Specifies the total size, in bytes, of this file.

This property is read-only.

Data Type

i64

file_permissions property (SSHPlex Struct)

The file permissions for the RemoteFile .

Syntax

fn file_permissions(&self) -> Result<String, IPWorksSSHError> 
fn set_file_permissions(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_file_permissions_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

"0600"

Remarks

This property defines the permissions that will be assigned to the remote_file after an upload. The value is a four-digit octal value. This is the same format that is used with the Unix chmod command. The default value of "0600" gives read/write permissions to the file's owner.

The last three octal digits are the most significant and represent, in order, the file access capabilities of the file's owner, the owner's group, and other users. Each of these octal digits is, on its own, a 3-bit bitmask with the following possible values:

An octal permission digit of 7 would have all three values set and would mean that the file can be read, written, and executed by that user class. For example, the octal permissions "100644" would have a value "6" for the owner, "4" for the group, and "4" for other users. This would be interpreted to mean that all users can read the file, no users can execute it, and only the owner can write it. The permissions "40755" would mean that all users can read and execute the file, but only the owner can write it.

The previous octal digit is another bitmask with the following values:

NOTE: Not all servers support setting permissions after an upload.

Data Type

String

firewall_auto_detect property (SSHPlex Struct)

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

Syntax

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

Default Value

false

Remarks

Data Type

bool

firewall_type property (SSHPlex Struct)

The type of firewall to connect through.

Syntax

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

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 (SSHPlex Struct)

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

Syntax

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

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 (SSHPlex Struct)

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

Syntax

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

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 (SSHPlex Struct)

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

Syntax

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

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_type is set to a valid value. See the description of the firewall_type property for details.

Data Type

i32

firewall_user property (SSHPlex Struct)

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

Syntax

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

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

local_file property (SSHPlex Struct)

The path to a local file for upload or download.

Syntax

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

Default Value

""

Remarks

The local_file property is used by the upload and download methods. The file will be overwritten only if the overwrite property is set to True.

Example. Setting LocalFile:

SSHPlexControl.Localfile = "C:\localfile.txt" SSHPlexControl.RemoteFile = "remotefile.txt" string operationId = SSHPlexControl.Download() SSHPlexControl.Localfile = "C:\localfile2.txt" SSHPlexControl.RemoteFile = "folder/remotefile2.txt" string operationId = SSHPlexControl.Download()

Data Type

String

local_host property (SSHPlex 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, IPWorksSSHError> 
fn set_local_host(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_local_host_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

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

local_port property (SSHPlex Struct)

The TCP port in the local host where the struct binds.

Syntax

fn local_port(&self) -> Result<i32, IPWorksSSHError> 
fn set_local_port(&self, value : i32) ->  Option<IPWorksSSHError> 

Default Value

0

Remarks

This property must be set before a connection is attempted. It instructs the struct to bind to a specific port (or communication endpoint) in the local machine.

Setting this property to 0 (default) enables the system to choose an open port at random. The chosen port will be returned by the local_port property after the connection is established.

local_port cannot be changed once a connection is made. Any attempt to set this property when a connection is active will generate an error.

This property is useful when trying to connect to services that require a trusted port on the client side.

Data Type

i32

operation_count property (SSHPlex Struct)

The number of records in the Operation arrays.

Syntax

fn operation_count(&self) -> Result<i32, IPWorksSSHError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• operation_id

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

This property is read-only.

Data Type

i32

operation_id property (SSHPlex Struct)

This property contains the Id of the currently running operation.

Syntax

fn operation_id(&self, OperationIndex : i32) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

This property contains the Id of the currently running operation.

The OperationIndex parameter specifies the index of the item in the array. The size of the array is controlled by the operation_count property.

This property is read-only.

Data Type

String

overwrite property (SSHPlex Struct)

The value indicating Whether or not the struct should overwrite files during transfer.

Syntax

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

Default Value

false

Remarks

When channel_type is set to cstSFTP, this property is a value indicating whether or not the struct should overwrite local_file when downloading, and remote_file when uploading. If overwrite is False, an error will be thrown whenever local_file exists before a download operation.

When channel_type is set to cstSCP, this property is a value indicating whether or not the struct should overwrite local_file when downloading. If overwrite is False, an error will be thrown whenever local_file exists before a download operation.

Data Type

bool

remote_file property (SSHPlex Struct)

The name of the remote file for uploading, downloading, and so on.

Syntax

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

Default Value

""

Remarks

The remote_file is either an absolute file path or a relative path based on remote_path.

A number of methods use remote_file as an argument.

Example 1. Setting RemoteFile:

SSHPlexControl.Localfile = "C:\localfile.txt" SSHPlexControl.RemoteFile = "remotefile.txt" string operationId = SSHPlexControl.Download() SSHPlexControl.Localfile = "C:\localfile2.txt" SSHPlexControl.RemoteFile = "folder/remotefile2.txt" string operationId = SSHPlexControl.Download()

NOTE: This property will also act as a file mask when performing list_directory.

Example 2. Using RemoteFile as a File Mask: SSHPlexControl.RemoteFile = "*.txt" SSHPlexControl.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

ssh_accept_server_host_key_effective_date property (SSHPlex Struct)

The date on which this certificate becomes valid.

Syntax

fn ssh_accept_server_host_key_effective_date(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_expiration_date property (SSHPlex Struct)

The date on which the certificate expires.

Syntax

fn ssh_accept_server_host_key_expiration_date(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_extended_key_usage property (SSHPlex Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssh_accept_server_host_key_extended_key_usage(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_fingerprint property (SSHPlex Struct)

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

Syntax

fn ssh_accept_server_host_key_fingerprint(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_fingerprint_sha1 property (SSHPlex Struct)

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

Syntax

fn ssh_accept_server_host_key_fingerprint_sha1(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_fingerprint_sha256 property (SSHPlex Struct)

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

Syntax

fn ssh_accept_server_host_key_fingerprint_sha256(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_issuer property (SSHPlex Struct)

The issuer of the certificate.

Syntax

fn ssh_accept_server_host_key_issuer(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_private_key property (SSHPlex Struct)

The private key of the certificate (if available).

Syntax

fn ssh_accept_server_host_key_private_key(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

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

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

This property is read-only.

Data Type

String

ssh_accept_server_host_key_private_key_available property (SSHPlex Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssh_accept_server_host_key_private_key_available(&self) -> Result<bool, IPWorksSSHError> 

Default Value

false

Remarks

Whether a ssh_accept_server_host_key_private_key is available for the selected certificate. If ssh_accept_server_host_key_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

ssh_accept_server_host_key_private_key_container property (SSHPlex Struct)

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

Syntax

fn ssh_accept_server_host_key_private_key_container(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

ssh_accept_server_host_key_public_key property (SSHPlex Struct)

The public key of the certificate.

Syntax

fn ssh_accept_server_host_key_public_key(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_public_key_algorithm property (SSHPlex Struct)

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

Syntax

fn ssh_accept_server_host_key_public_key_algorithm(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_public_key_length property (SSHPlex Struct)

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

Syntax

fn ssh_accept_server_host_key_public_key_length(&self) -> Result<i32, IPWorksSSHError> 

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

ssh_accept_server_host_key_serial_number property (SSHPlex Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssh_accept_server_host_key_serial_number(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_signature_algorithm property (SSHPlex Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssh_accept_server_host_key_signature_algorithm(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_store property (SSHPlex Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssh_accept_server_host_key_store(&self) -> Result<Vec<u8>, IPWorksSSHError> 
fn set_ssh_accept_server_host_key_store(&self, value : Vec<u8>) ->  Option<IPWorksSSHError> 
fn set_ssh_accept_server_host_key_store_ref(&self, value : &[u8]) ->  Option<IPWorksSSHError> 

Default Value

"MY"

Remarks

The ssh_accept_server_host_key_store_type property denotes the type of the certificate store specified by ssh_accept_server_host_key_store. If the store is password-protected, specify the password in ssh_accept_server_host_key_store_password.

ssh_accept_server_host_key_store is used in conjunction with the ssh_accept_server_host_key_subject property to specify client certificates. If ssh_accept_server_host_key_store has a value, and ssh_accept_server_host_key_subject or ssh_accept_server_host_key_encoded is set, a search for a certificate is initiated. Please see the ssh_accept_server_host_key_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<u8>

ssh_accept_server_host_key_store_password property (SSHPlex 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 ssh_accept_server_host_key_store_password(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_accept_server_host_key_store_password(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_accept_server_host_key_store_password_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

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

ssh_accept_server_host_key_store_type property (SSHPlex Struct)

The type of certificate store for this certificate.

Syntax

fn ssh_accept_server_host_key_store_type(&self) -> Result<i32, IPWorksSSHError> 
fn set_ssh_accept_server_host_key_store_type(&self, value : i32) ->  Option<IPWorksSSHError> 

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

ssh_accept_server_host_key_subject_alt_names property (SSHPlex Struct)

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

Syntax

fn ssh_accept_server_host_key_subject_alt_names(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

ssh_accept_server_host_key_thumbprint_md5 property (SSHPlex Struct)

The MD5 hash of the certificate.

Syntax

fn ssh_accept_server_host_key_thumbprint_md5(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_thumbprint_sha1 property (SSHPlex Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssh_accept_server_host_key_thumbprint_sha1(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_thumbprint_sha256 property (SSHPlex Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssh_accept_server_host_key_thumbprint_sha256(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_usage property (SSHPlex Struct)

The text description of UsageFlags .

Syntax

fn ssh_accept_server_host_key_usage(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

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

ssh_accept_server_host_key_usage_flags property (SSHPlex Struct)

The flags that show intended use for the certificate.

Syntax

fn ssh_accept_server_host_key_usage_flags(&self) -> Result<i32, IPWorksSSHError> 

Default Value

0

Remarks

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

Please see the ssh_accept_server_host_key_usage property for a text representation of ssh_accept_server_host_key_usage_flags.

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

This property is read-only.

Data Type

i32

ssh_accept_server_host_key_version property (SSHPlex Struct)

The certificate's version number.

Syntax

fn ssh_accept_server_host_key_version(&self) -> Result<String, IPWorksSSHError> 

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

ssh_accept_server_host_key_subject property (SSHPlex Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssh_accept_server_host_key_subject(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_accept_server_host_key_subject(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_accept_server_host_key_subject_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

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

ssh_accept_server_host_key_encoded property (SSHPlex Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssh_accept_server_host_key_encoded(&self) -> Result<Vec<u8>, IPWorksSSHError> 
fn set_ssh_accept_server_host_key_encoded(&self, value : Vec<u8>) ->  Option<IPWorksSSHError> 
fn set_ssh_accept_server_host_key_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

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

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

Data Type

Vec<u8>

ssh_auth_mode property (SSHPlex Struct)

The authentication method to be used with the struct when calling SSHLogon .

Syntax

fn ssh_auth_mode(&self) -> Result<i32, IPWorksSSHError> 
fn set_ssh_auth_mode(&self, value : i32) ->  Option<IPWorksSSHError> 

Possible Values

0   // None
1   // MultiFactor
2   // Password
3   // PublicKey
4   // KeyboardInteractive
5   // GSSAPIWithMic
6   // GSSAPIKeyex
99   // Custom

Default Value

2

Remarks

The Secure Shell (SSH) Authentication specification (RFC 4252) specifies multiple methods by which a user can be authenticated by an SSH server. When a call is made to ssh_logon, the struct will connect to the SSH server and establish the security layer. After the connection has been secured, the client will send an authentication request to the ssh_host containing the ssh_user. The server will respond containing a list of methods by which that user may be authenticated.

The struct will attempt to authenticate the user by one of those methods based on the value of ssh_auth_mode and other property values supplied by the user. Currently, the struct supports the following authentication methods:

Example 1. User/Password Authentication: Control.SSHAuthMode = SftpSSHAuthModes.amPassword Control.SSHUser = "username" Control.SSHPassword = "password" Control.SSHLogon("server", 22) Example 2. Public Key Authentication: Control.SSHAuthMode = SftpSSHAuthModes.amPublicKey Control.SSHUser = "username" Control.SSHCertStoreType = SSHCertStoreTypes.cstPFXFile; Control.SSHCertStore = "cert.pfx"; Control.SSHCertStorePassword = "certpassword"; Control.SSHCertSubject = "*"; Control.SSHLogon("server", 22)

Data Type

i32

ssh_cert_effective_date property (SSHPlex Struct)

The date on which this certificate becomes valid.

Syntax

fn ssh_cert_effective_date(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_expiration_date property (SSHPlex Struct)

The date on which the certificate expires.

Syntax

fn ssh_cert_expiration_date(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_extended_key_usage property (SSHPlex Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssh_cert_extended_key_usage(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_fingerprint property (SSHPlex Struct)

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

Syntax

fn ssh_cert_fingerprint(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_fingerprint_sha1 property (SSHPlex Struct)

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

Syntax

fn ssh_cert_fingerprint_sha1(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_fingerprint_sha256 property (SSHPlex Struct)

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

Syntax

fn ssh_cert_fingerprint_sha256(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_issuer property (SSHPlex Struct)

The issuer of the certificate.

Syntax

fn ssh_cert_issuer(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_private_key property (SSHPlex Struct)

The private key of the certificate (if available).

Syntax

fn ssh_cert_private_key(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

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

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

This property is read-only.

Data Type

String

ssh_cert_private_key_available property (SSHPlex Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssh_cert_private_key_available(&self) -> Result<bool, IPWorksSSHError> 

Default Value

false

Remarks

Whether a ssh_cert_private_key is available for the selected certificate. If ssh_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

ssh_cert_private_key_container property (SSHPlex Struct)

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

Syntax

fn ssh_cert_private_key_container(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

The name of the ssh_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

ssh_cert_public_key property (SSHPlex Struct)

The public key of the certificate.

Syntax

fn ssh_cert_public_key(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_public_key_algorithm property (SSHPlex Struct)

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

Syntax

fn ssh_cert_public_key_algorithm(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_public_key_length property (SSHPlex Struct)

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

Syntax

fn ssh_cert_public_key_length(&self) -> Result<i32, IPWorksSSHError> 

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

ssh_cert_serial_number property (SSHPlex Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssh_cert_serial_number(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_signature_algorithm property (SSHPlex Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssh_cert_signature_algorithm(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_store property (SSHPlex Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssh_cert_store(&self) -> Result<Vec<u8>, IPWorksSSHError> 
fn set_ssh_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksSSHError> 
fn set_ssh_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksSSHError> 

Default Value

"MY"

Remarks

The ssh_cert_store_type property denotes the type of the certificate store specified by ssh_cert_store. If the store is password-protected, specify the password in ssh_cert_store_password.

ssh_cert_store is used in conjunction with the ssh_cert_subject property to specify client certificates. If ssh_cert_store has a value, and ssh_cert_subject or ssh_cert_encoded is set, a search for a certificate is initiated. Please see the ssh_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<u8>

ssh_cert_store_password property (SSHPlex 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 ssh_cert_store_password(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_cert_store_password(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

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

ssh_cert_store_type property (SSHPlex Struct)

The type of certificate store for this certificate.

Syntax

fn ssh_cert_store_type(&self) -> Result<i32, IPWorksSSHError> 
fn set_ssh_cert_store_type(&self, value : i32) ->  Option<IPWorksSSHError> 

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

ssh_cert_subject_alt_names property (SSHPlex Struct)

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

Syntax

fn ssh_cert_subject_alt_names(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

ssh_cert_thumbprint_md5 property (SSHPlex Struct)

The MD5 hash of the certificate.

Syntax

fn ssh_cert_thumbprint_md5(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_thumbprint_sha1 property (SSHPlex Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssh_cert_thumbprint_sha1(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_thumbprint_sha256 property (SSHPlex Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssh_cert_thumbprint_sha256(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_usage property (SSHPlex Struct)

The text description of UsageFlags .

Syntax

fn ssh_cert_usage(&self) -> Result<String, IPWorksSSHError> 

Default Value

""

Remarks

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

ssh_cert_usage_flags property (SSHPlex Struct)

The flags that show intended use for the certificate.

Syntax

fn ssh_cert_usage_flags(&self) -> Result<i32, IPWorksSSHError> 

Default Value

0

Remarks

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

Please see the ssh_cert_usage property for a text representation of ssh_cert_usage_flags.

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

This property is read-only.

Data Type

i32

ssh_cert_version property (SSHPlex Struct)

The certificate's version number.

Syntax

fn ssh_cert_version(&self) -> Result<String, IPWorksSSHError> 

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

ssh_cert_subject property (SSHPlex Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssh_cert_subject(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_cert_subject(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_cert_subject_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

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

ssh_cert_encoded property (SSHPlex Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssh_cert_encoded(&self) -> Result<Vec<u8>, IPWorksSSHError> 
fn set_ssh_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksSSHError> 
fn set_ssh_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

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

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

Data Type

Vec<u8>

ssh_compression_algorithms property (SSHPlex Struct)

The comma-separated list containing all allowable compression algorithms.

Syntax

fn ssh_compression_algorithms(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_compression_algorithms(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_compression_algorithms_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

"none,zlib"

Remarks

During the Secure Shell (SSH) handshake, this list will be used to negotiate the compression algorithm to be used between the client and server. This list is used for both directions: client to server and server to client. When negotiating algorithms, each side sends a list of all algorithms it supports or allows. The algorithm chosen for each direction is the first algorithm to appear in the sender's list that the receiver supports. Therefore, it is important to list multiple algorithms in preferential order. If no algorithm can be agreed on, the struct will raise an error and the connection will be aborted.

At least one supported algorithm must appear in this list. The following compression algorithms are supported by the struct:

• zlib
• zlib@openssh.com
• none

Data Type

String

ssh_encryption_algorithms property (SSHPlex Struct)

The comma-separated list containing all allowable encryption algorithms.

Syntax

fn ssh_encryption_algorithms(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_encryption_algorithms(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_encryption_algorithms_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

"aes256-ctr,aes192-ctr,aes128-ctr,3des-ctr,aes256-gcm@openssh.com,aes128-gcm@openssh.com,chacha20-poly1305@openssh.com"

Remarks

During the Secure Shell (SSH) handshake, this list will be used to negotiate the encryption algorithm to be used between the client and server. This list is used for both directions: client to server and server to client. When negotiating algorithms, each side sends a list of all algorithms it supports or allows. The algorithm chosen for each direction is the first algorithm to appear in the sender's list that the receiver supports. Therefore, it is important to list multiple algorithms in preferential order. If no algorithm can be agreed on, the struct will raise an error and the connection will be aborted.

At least one supported algorithm must appear in this list. The following encryption algorithms are supported by the struct:

• aes256-ctr
• aes256-cbc
• aes192-ctr
• aes192-cbc
• aes128-ctr
• aes128-cbc
• 3des-ctr
• 3des-cbc
• cast128-cbc
• blowfish-cbc
• arcfour
• arcfour128
• arcfour256
• aes256-gcm@openssh.com
• aes128-gcm@openssh.com
• chacha20-poly1305@openssh.com

Data Type

String

ssh_host property (SSHPlex Struct)

The address of the Secure Shell (SSH) host.

Syntax

fn ssh_host(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_host(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_host_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

The ssh_host property specifies the IP address (IP number in dotted internet format) or domain name of the remote host. It is set before a connection is attempted and cannot be changed once a connection is established.

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

The ssh_host must be the same host that will be assumed for SSH as for the remote service being connected to.

Data Type

String

ssh_password property (SSHPlex Struct)

The password for Secure Shell (SSH) password-based authentication.

Syntax

fn ssh_password(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_password(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_password_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

ssh_password specifies the password that is used to authenticate the client to the SSH server.

Data Type

String

ssh_port property (SSHPlex Struct)

The port on the Secure Shell (SSH) server where the SSH service is running; by default, 22.

Syntax

fn ssh_port(&self) -> Result<i32, IPWorksSSHError> 
fn set_ssh_port(&self, value : i32) ->  Option<IPWorksSSHError> 

Default Value

22

Remarks

The ssh_port specifies a service port on the SSH host to connect to.

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.

Data Type

i32

ssh_user property (SSHPlex Struct)

The username for Secure Shell (SSH) authentication.

Syntax

fn ssh_user(&self) -> Result<String, IPWorksSSHError> 
fn set_ssh_user(&self, value : &str) ->  Option<IPWorksSSHError> 
fn set_ssh_user_ref(&self, value : &String) ->  Option<IPWorksSSHError> 

Default Value

""

Remarks

ssh_user specifies the username that is used to authenticate the client to the SSH server. This property is required.

Example 1. User/Password Authentication: Control.SSHAuthMode = SftpSSHAuthModes.amPassword Control.SSHUser = "username" Control.SSHPassword = "password" Control.SSHLogon("server", 22) Example 2. Public Key Authentication: Control.SSHAuthMode = SftpSSHAuthModes.amPublicKey Control.SSHUser = "username" Control.SSHCertStoreType = SSHCertStoreTypes.cstPFXFile; Control.SSHCertStore = "cert.pfx"; Control.SSHCertStorePassword = "certpassword"; Control.SSHCertSubject = "*"; Control.SSHLogon("server", 22)

Data Type

String

start_byte property (SSHPlex Struct)

The offset in bytes at which to begin the upload or download.

Syntax

fn start_byte(&self) -> Result<i64, IPWorksSSHError> 
fn set_start_byte(&self, value : i64) ->  Option<IPWorksSSHError> 

Default Value

0

Remarks

The start_byte property is used by the upload and download methods to determine at what offset to begin the transfer. This allows for resuming both uploads and downloads. The value of this property is reset to 0 after a successful transfer. start_byte is not valid for use with append.

When downloading, this property can be used in conjunction with the TransferredDataLimit configuration setting to download only a specific range of data from the current remote_file.

Data Type

i64

timeout property (SSHPlex Struct)

This property includes the timeout for the struct.

Syntax

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

Default Value

60

Remarks

If the timeout property is set to 0, all operations return immediately, potentially failing with a WOULDBLOCK error if data cannot be sent immediately.

If timeout is set to a positive value, data is sent in a blocking manner and the struct will wait for the operation to complete before returning control. The struct will handle any potential WOULDBLOCK errors internally and automatically retry the operation for a maximum of timeout seconds.

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

append method (SSHPlex Struct)

Appends the data from a local file; to a remote file using SFTP.

Syntax

fn append(&self) -> Result<String, IPWorksSSHError>

Remarks

This method appends the data from local_file to the remote_file. The on_start_transfer, on_transfer, and on_end_transfer events provide details about the individual file transfers. If the local_file property is "" (empty string), then the file data will be available through the on_transfer event.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_append_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_append_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

Code Example

SSHPlexControl.Localfile = "C:\localfile.txt"; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Append(); // Use Path in RemoteFile SSHPlexControl.Localfile = "C:\localfile2.txt"; SSHPlexControl.RemoteFile = "folder/remotefile2.txt"; string operationId = SSHPlexControl.Append();

cancel_operation method (SSHPlex Struct)

Cancels the operation specified by OperationId .

Syntax

fn cancel_operation(&self, operation_id : &str) -> Result<(), IPWorksSSHError>

Remarks

When this method is called, the on_error event will fire and the associated operation's completion event will fire.

For example, if CancelOperation is called for an upload that is in progress, both the on_error event and the on_upload_complete event will fire.

The SSHPlexOperation associated with the OperationId will be removed from the operations collection.

change_remote_path method (SSHPlex Struct)

This method changes the current path on the FTP server.

Syntax

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

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");

check_file_exists method (SSHPlex Struct)

Returns true if the file specified by RemoteFile exists on the remote server.

Syntax

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

Remarks

This property returns true if the file exists on the remote server. It returns false if the file does not exist. You must specify the file you wish to check by setting the remote_file before calling this method.

If no session is in place, the value of this property will always be false.

config method (SSHPlex Struct)

Sets or retrieves a configuration setting.

Syntax

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

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 (SSHPlex Struct)

Connects to the Secure Shell (SSH) host without logging in.

Syntax

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

Remarks

This method establishes a connection with the ssh_host but does not log in. In most cases, it is recommended to use the ssh_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 (e.g., confirming a host is available by first creating the connection).

create_file method (SSHPlex Struct)

Creates a file on the remote server using SFTP.

Syntax

fn create_file(&self, file_name : &str) -> Result<String, IPWorksSSHError>

Remarks

This method creates an empty file on the server with the name specified by the FileName parameter. FileName is either an absolute path on the server or a path relative to remote_path.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_create_file_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_create_file_complete event to determine the result.

To upload a file with content, use upload instead.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

delete_file method (SSHPlex Struct)

Deletes a file on the remote server using SFTP.

Syntax

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

Remarks

This method deletes a file on the server with the name specified by the FileName parameter. FileName is either an absolute path on the server or a path relative to remote_path.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_delete_file_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_delete_file_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

disconnect method (SSHPlex Struct)

Disconnects from the server without first logging off.

Syntax

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

Remarks

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

In most cases, the ssh_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 (SSHPlex Struct)

This method processes events from the internal message queue.

Syntax

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

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 (SSHPlex Struct)

Download a RemoteFile using SFTP or SCP.

Syntax

fn download(&self) -> Result<String, IPWorksSSHError>

Remarks

This method downloads the remote file specified by remote_file to the local file specified by local_file. The on_start_transfer, on_transfer, and on_end_transfer events provide details about the individual file transfers. If the local_file property is "" (empty string) then the file data will be available through the on_transfer event.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes the on_download_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_download_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp or cstScp.

Set remote_file to the name of the file to download before calling this method. If remote_file specifies only a filename, it will be downloaded from the path specified by remote_path. remote_file may also be set to an absolute path.

If local_file is set, the file will be saved to the specified location.

Code Example

SSHPlexControl.Localfile = "C:\localfile.txt"; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Download(); // Use Path in RemoteFile SSHPlexControl.Localfile = "C:\localfile2.txt"; SSHPlexControl.RemoteFile = "folder/remotefile2.txt"; string operationId = SSHPlexControl.Download();

Resuming Downloads

The struct also supports resuming failed downloads by using the start_byte property. If a download is interrupted or canceled, set start_byte to the appropriate offset before calling this method to resume the download.

string localFile = "C:\localfile.txt"; SSHPlexControl.Localfile = localFile; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Download(); // Cancel Download using the CancelOperation method SSHPlexControl.CancelOperation(operationId); // Get the size of the partially downloaded temp file and set StartByte SSHPlexControl.StartByte = new FileInfo(localFile).Length; // Resume download string operationId = SSHPlexControl.Download();

Downloading Multiple Files Using a Filemask

NOTE: Using a filemask for downloads is applicable only when channel_type is set to cstScp. To download files matching a filemask, set remote_file to a filemask. The path may be specified as part of the value in remote_file or may be set separately in remote_path. local_file should be set to a local directory where files will be downloaded. When download is called, all matching files are downloaded. See remote_file for more information.

execute method (SSHPlex Struct)

Executes a specified command on the remote host.

Syntax

fn execute(&self, command : &str) -> Result<String, IPWorksSSHError>

Remarks

This method executes the specified Command on the remote host.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_execute_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_execute_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSExec or cstSShell.

interrupt method (SSHPlex Struct)

This method interrupts the current method.

Syntax

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

Remarks

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

list_directory method (SSHPlex Struct)

Lists the current directory specified by RemotePath on a server using secure file transfer protocol (SFTP).

Syntax

fn list_directory(&self) -> Result<String, IPWorksSSHError>

Remarks

This method lists the directory specified by remote_path. remote_file may also be set to a filemask to list associated files. The file listing is received through the on_dir_list event.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_list_directory_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_list_directory_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

The directory entries are provided through the on_dir_list event and also through the dir_list property. SSHPlexControl.RemoteFile = ""; //Clear filemask SSHPlexControl.RemotePath = "MyFolder"; string opId = SSHPlexControl.ListDirectory(); // ListDirectory operates async so we must wait for it to finish while (SSHPlexControl.Operations.Keys.Contains(opId)) { SSHPlexControl.DoEvents(); } for (int i = 0; i < SSHPlexControl.DirList.Count; i++) { Console.WriteLine(SSHPlexControl.DirList[i].FileName); Console.WriteLine(SSHPlexControl.DirList[i].FileSize); Console.WriteLine(SSHPlexControl.DirList[i].FileTime); Console.WriteLine(SSHPlexControl.DirList[i].IsDir); }

The remote_file property may also be used as a filemask when listing files. For instance: SSHPlexControl.RemoteFile = "*.txt"; SSHPlexControl.ListDirectory();

NOTE: Because remote_file is used as a filemask, ensure that you clear or reset this value before calling list_directory

make_directory method (SSHPlex Struct)

Creates a directory on the remote server using secure file transfer protocol (SFTP).

Syntax

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

Remarks

This method creates an empty directory on the server with the name specified by the NewDir parameter. NewDir is either an absolute path on the server or a path relative to remote_path.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_make_directory_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_make_directory_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

query_file_attributes method (SSHPlex Struct)

Queries the server for the attributes of RemoteFile .

Syntax

fn query_file_attributes(&self) -> Result<(), IPWorksSSHError>

Remarks

This method queries the server for attributes of remote_file. After calling this method, file_attributes will be populated with the values returned by the server.

To update attributes, modify the desired values in file_attributes and call update_file_attributes.

query_remote_path method (SSHPlex Struct)

This queries the server for the current path.

Syntax

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

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 (SSHPlex Struct)

Removes a directory on the remote server using secure file transfer protocol (SFTP).

Syntax

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

Remarks

This method deletes a directory on the server with the name specified by the DirName parameter. DirName is either an absolute path on the server or a path relative to remote_path.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_remove_directory_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_remove_directory_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

rename_file method (SSHPlex Struct)

Changes the name of a file on the remote server using secure file transfer protocol (SFTP).

Syntax

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

Remarks

This method renames the file on the server specified by remote_file to the name specified by the NewName parameter. remote_file and NewName are either absolute paths on the server or a path relative to remote_path.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_rename_file_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_rename_file_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

send_command method (SSHPlex Struct)

Sends the specified command to the remote host.

Syntax

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

Remarks

This method sends the Command to the ssh_host. The command is executed in the user's shell.

You do not need to append an end-of-line character to the command. All output from the remote execution will be returned through the on_stdout event.

send_stdin_bytes method (SSHPlex Struct)

Sends binary data to the remote host.

Syntax

fn send_stdin_bytes(&self, data : &[u8]) -> Result<(), IPWorksSSHError>

Remarks

This method sends the specified binary data to the remote host. The data provided are used as input for the process on the remote host. To send text, use the send_stdin_text method instead.

If you are sending data to the remote host faster than it can process it, or faster than the network bandwidth allows, the outgoing queue might fill up. When this happens, the struct fails with error 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. .

send_stdin_text method (SSHPlex Struct)

Sends text to the remote host.

Syntax

fn send_stdin_text(&self, text : &str) -> Result<(), IPWorksSSHError>

Remarks

This method sends the specified text to the remote host. The text provided is used as an input for the process on the remote host. To send binary data, use the send_stdin_bytes method instead.

If you are sending data to the remote host faster than it can process it, or faster than the network bandwidth allows, the outgoing queue might fill up. When this happens, the struct fails with error 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. .

ssh_logoff method (SSHPlex Struct)

Logs off from the Secure Shell (SSH) server.

Syntax

fn ssh_logoff(&self) -> Result<(), IPWorksSSHError>

Remarks

Logs off from the SSH server. If that fails, the connection is terminated by the local host.

ssh_logon method (SSHPlex Struct)

Logs on to the SSHHost using the current SSHUser and SSHPassword .

Syntax

fn ssh_logon(&self, ssh_host : &str, ssh_port : i32) -> Result<(), IPWorksSSHError>

Remarks

Logs on to the Secure Shell (SSH) server using the current ssh_user and ssh_password. This will perform the SSH handshake and authentication.

Example. Logging On:

SSHPlexControl.SSHUser = "username" SSHPlexControl.SSHPassword = "password" SSHPlexControl.SSHLogon("sshHost", sshPort)

update_file_attributes method (SSHPlex Struct)

Instructs the struct to send the FileAttributes to the server using secure file transfer protocol (SFTP).

Syntax

fn update_file_attributes(&self) -> Result<String, IPWorksSSHError>

Remarks

When update_file_attributes is called, the struct will send the values of the following properties to the server:

• sftp_file_access_time
• sftp_file_acl
• sftp_file_allocation_size
• sftp_file_attribute_bits
• sftp_file_attribute_bits_valid
• sftp_file_creation_time
• sftp_file_type
• sftp_file_group_id
• sftp_file_is_dir
• sftp_file_modified_time
• sftp_file_owner_id
• sftp_file_permissions
• sftp_file_size

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_update_file_attributes_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_update_file_attributes_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp.

upload method (SSHPlex Struct)

Uploads a file specified by LocalFile using secure copy protocol (SCP) or secure file transfer protocol (SFTP).

Syntax

fn upload(&self) -> Result<String, IPWorksSSHError>

Remarks

This method uploads the local file specified by local_file to the remote file specified by remote_file. The on_start_transfer, on_transfer, and on_end_transfer events provide details about the individual file transfers. If the local_file property is "" (empty string), then the file data will be available through the on_transfer event.

This method returns an Operation Id that identifies the operation in progress. A corresponding SSHPlexOperation will also be added to the operations collection. The operation can be canceled by passing the Operation Id to the cancel_operation method.

When the operation completes, the on_upload_complete event will fire, and the SSHPlexOperation associated with the completed operation will be removed from the operations collection. Inspect the parameters of the on_upload_complete event to determine the result.

If a Secure Shell (SSH) session is not in place, one is automatically created by the component first.

This method is applicable only when channel_type is set to cstSftp or cstScp.

Set local_file to the name of the file to upload before calling this method.

remote_file should be set to either a relative or absolute path. If remote_file is not an absolute path, it will be uploaded relative to remote_path.

Code Example

SSHPlexControl.Localfile = "C:\localfile.txt"; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Upload(); // Use Path in RemoteFile SSHPlexControl.Localfile = "C:\localfile2.txt"; SSHPlexControl.RemoteFile = "folder/remotefile2.txt"; string operationId = SSHPlexControl.Upload();

Resuming Uploads

The struct also supports resuming failed uploads by using the start_byte property. If an upload is interrupted or canceled, set start_byte to the appropriate offset before calling this method to resume the upload.

string localFile = "C:\localfile.txt"; SSHPlexControl.Localfile = localFile; SSHPlexControl.RemoteFile = "remotefile.txt"; string operationId = SSHPlexControl.Upload(); // Cancel Upload using the CancelOperation method SSHPlexControl.CancelOperation(operationId); // Get the size of the partially uploaded temp file and set StartByte SSHPlexControl.StartByte = SSHPlexControl.FileAttributes.Size; // Resume upload string operationId = SSHPlexControl.Upload();

on_append_complete event (SSHPlex Struct)

Fired when an append operation completes.

Syntax

// SSHPlexAppendCompleteEventArgs carries the SSHPlex AppendComplete event's parameters.
pub struct SSHPlexAppendCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn local_file(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexAppendCompleteEvent defines the signature of the SSHPlex AppendComplete event's handler function.
pub trait SSHPlexAppendCompleteEvent {
  fn on_append_complete(&self, sender : SSHPlex, e : &mut SSHPlexAppendCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_append_complete(&self) -> &'a dyn SSHPlexAppendCompleteEvent;
  pub fn set_on_append_complete(&mut self, value : &'a dyn SSHPlexAppendCompleteEvent);
  ...
}

Remarks

This event fires when an append operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

LocalFile is the local file that was specified when the operation was initiated.

RemoteFile is the remote file that was specified when the operation was initiated.

RemotePath is the remote path that was specified when the operation was initiated.

on_connected event (SSHPlex Struct)

Fired immediately after a connection completes (or fails).

Syntax

// SSHPlexConnectedEventArgs carries the SSHPlex Connected event's parameters.
pub struct SSHPlexConnectedEventArgs {
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// SSHPlexConnectedEvent defines the signature of the SSHPlex Connected event's handler function.
pub trait SSHPlexConnectedEvent {
  fn on_connected(&self, sender : SSHPlex, e : &mut SSHPlexConnectedEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_connected(&self) -> &'a dyn SSHPlexConnectedEvent;
  pub fn set_on_connected(&mut self, value : &'a dyn SSHPlexConnectedEvent);
  ...
}

Remarks

If the connection is made normally, status_code is 0 and description is "OK".

If the connection fails, status_code has the error code returned by the Transmission Control Protocol (TCP)/IP stack. description contains a description of this code. The value of status_code is equal to the value of the error.

Please refer to the Error Codes section for more information.

on_connection_status event (SSHPlex Struct)

Fired to indicate changes in the connection state.

Syntax

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

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

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

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_create_file_complete event (SSHPlex Struct)

Fired when a CreateFile operation completes (or fails).

Syntax

// SSHPlexCreateFileCompleteEventArgs carries the SSHPlex CreateFileComplete event's parameters.
pub struct SSHPlexCreateFileCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexCreateFileCompleteEvent defines the signature of the SSHPlex CreateFileComplete event's handler function.
pub trait SSHPlexCreateFileCompleteEvent {
  fn on_create_file_complete(&self, sender : SSHPlex, e : &mut SSHPlexCreateFileCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_create_file_complete(&self) -> &'a dyn SSHPlexCreateFileCompleteEvent;
  pub fn set_on_create_file_complete(&mut self, value : &'a dyn SSHPlexCreateFileCompleteEvent);
  ...
}

Remarks

This event fires when a CreateFile operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

RemoteFile is the remote file that was specified when the operation was initiated.

RemotePath is the remote path that was specified when the operation was initiated.

on_delete_file_complete event (SSHPlex Struct)

Fired when a DeleteFile operation completes (or fails).

Syntax

// SSHPlexDeleteFileCompleteEventArgs carries the SSHPlex DeleteFileComplete event's parameters.
pub struct SSHPlexDeleteFileCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexDeleteFileCompleteEvent defines the signature of the SSHPlex DeleteFileComplete event's handler function.
pub trait SSHPlexDeleteFileCompleteEvent {
  fn on_delete_file_complete(&self, sender : SSHPlex, e : &mut SSHPlexDeleteFileCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_delete_file_complete(&self) -> &'a dyn SSHPlexDeleteFileCompleteEvent;
  pub fn set_on_delete_file_complete(&mut self, value : &'a dyn SSHPlexDeleteFileCompleteEvent);
  ...
}

Remarks

This event fires when a DeleteFile operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

RemoteFile is the remote file that was specified when the operation was initiated.

RemotePath is the remote path that was specified when the operation was initiated.

on_dir_list event (SSHPlex Struct)

Fired when a directory entry is received.

Syntax

// SSHPlexDirListEventArgs carries the SSHPlex DirList event's parameters.
pub struct SSHPlexDirListEventArgs {
  fn operation_id(&self) -> &String
  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
  fn is_symlink(&self) -> bool
}

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

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

Remarks

OperationId is associated with the operation that fired this event.

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

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

The DirEntry parameter contains the filename when list_directory is called.

The struct tries to fill out the FileName, IsDir, FileSize, and FileTime parameters when calling the ListDirectory method.

The format of the FileTime parameter returned by the struct can be controlled through the FileTimeFormat configuration setting. If no format is specified, the struct will format the date dependent on the year. If the filetime is in the same year, it will be formatted as "MMM dd HH:mm", otherwise it will be formatted as "MMM dd yyyy".

IsSymlink indicates whether the entry is a symbolic link. When the entry is a symbolic link, the value of IsDir will always be False because this information is not returned in the directory listing. To inspect a symlink to determine if it is a link to a file or folder, set remote_file and query the sftp_file_is_dir property.

on_disconnected event (SSHPlex Struct)

Fired when a connection is closed.

Syntax

// SSHPlexDisconnectedEventArgs carries the SSHPlex Disconnected event's parameters.
pub struct SSHPlexDisconnectedEventArgs {
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// SSHPlexDisconnectedEvent defines the signature of the SSHPlex Disconnected event's handler function.
pub trait SSHPlexDisconnectedEvent {
  fn on_disconnected(&self, sender : SSHPlex, e : &mut SSHPlexDisconnectedEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_disconnected(&self) -> &'a dyn SSHPlexDisconnectedEvent;
  pub fn set_on_disconnected(&mut self, value : &'a dyn SSHPlexDisconnectedEvent);
  ...
}

Remarks

If the connection is broken normally, status_code is 0 and description is "OK".

If the connection is broken for any other reason, status_code has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. description contains a description of this code. The value of status_code is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

on_download_complete event (SSHPlex Struct)

Fired when a download operation completes (or fails).

Syntax

// SSHPlexDownloadCompleteEventArgs carries the SSHPlex DownloadComplete event's parameters.
pub struct SSHPlexDownloadCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn local_file(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexDownloadCompleteEvent defines the signature of the SSHPlex DownloadComplete event's handler function.
pub trait SSHPlexDownloadCompleteEvent {
  fn on_download_complete(&self, sender : SSHPlex, e : &mut SSHPlexDownloadCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_download_complete(&self) -> &'a dyn SSHPlexDownloadCompleteEvent;
  pub fn set_on_download_complete(&mut self, value : &'a dyn SSHPlexDownloadCompleteEvent);
  ...
}

Remarks

This event fires when a download operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

LocalFile is the local file that was specified when the operation was initiated.

RemoteFile is the remote file that was specified when the operation was initiated.

RemotePath is the remote path that was specified when the operation was initiated.

on_end_transfer event (SSHPlex Struct)

Fired when a file completes downloading or uploading.

Syntax

// SSHPlexEndTransferEventArgs carries the SSHPlex EndTransfer event's parameters.
pub struct SSHPlexEndTransferEventArgs {
  fn operation_id(&self) -> &String
  fn direction(&self) -> i32
  fn local_file(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
}

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

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

Remarks

This event is fired once per file when it finishes downloading or uploading.

OperationId is the string associated with operation fired this event.

Direction is 0 for uploads and 1 for downloads.

LocalFile, RemoteFile, and RemotePath are populated with values of local_file, remote_file, and remote_path, respectively, that are associated with the method that triggered this event.

on_error event (SSHPlex Struct)

Fired when errors occur during data delivery.

Syntax

// SSHPlexErrorEventArgs carries the SSHPlex Error event's parameters.
pub struct SSHPlexErrorEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn description(&self) -> &String
  fn local_file(&self) -> &String
  fn remote_file(&self) -> &String
}

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

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

Remarks

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

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

LocalFile identifies the local file. RemoteFile is the remote file.

on_execute_complete event (SSHPlex Struct)

Fired when an execute operation completes (or fails).

Syntax

// SSHPlexExecuteCompleteEventArgs carries the SSHPlex ExecuteComplete event's parameters.
pub struct SSHPlexExecuteCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn exit_status(&self) -> i32
}

// SSHPlexExecuteCompleteEvent defines the signature of the SSHPlex ExecuteComplete event's handler function.
pub trait SSHPlexExecuteCompleteEvent {
  fn on_execute_complete(&self, sender : SSHPlex, e : &mut SSHPlexExecuteCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_execute_complete(&self) -> &'a dyn SSHPlexExecuteCompleteEvent;
  pub fn set_on_execute_complete(&mut self, value : &'a dyn SSHPlexExecuteCompleteEvent);
  ...
}

Remarks

This event fires when an execute operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

ExitStatus is the exit code of the executed command. If an error message is returned, it is present in ErrorDescription.

on_list_directory_complete event (SSHPlex Struct)

Fired when a ListDirectory operation completes (or fails).

Syntax

// SSHPlexListDirectoryCompleteEventArgs carries the SSHPlex ListDirectoryComplete event's parameters.
pub struct SSHPlexListDirectoryCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexListDirectoryCompleteEvent defines the signature of the SSHPlex ListDirectoryComplete event's handler function.
pub trait SSHPlexListDirectoryCompleteEvent {
  fn on_list_directory_complete(&self, sender : SSHPlex, e : &mut SSHPlexListDirectoryCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_list_directory_complete(&self) -> &'a dyn SSHPlexListDirectoryCompleteEvent;
  pub fn set_on_list_directory_complete(&mut self, value : &'a dyn SSHPlexListDirectoryCompleteEvent);
  ...
}

Remarks

This event fires when a ListDirectory operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

RemotePath is the remote path that was specified when the operation was initiated.

on_log event (SSHPlex Struct)

Fired once for each log message.

Syntax

// SSHPlexLogEventArgs carries the SSHPlex Log event's parameters.
pub struct SSHPlexLogEventArgs {
  fn log_level(&self) -> i32
  fn message(&self) -> &String
  fn log_type(&self) -> &String
}

// SSHPlexLogEvent defines the signature of the SSHPlex Log event's handler function.
pub trait SSHPlexLogEvent {
  fn on_log(&self, sender : SSHPlex, e : &mut SSHPlexLogEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_log(&self) -> &'a dyn SSHPlexLogEvent;
  pub fn set_on_log(&mut self, value : &'a dyn SSHPlexLogEvent);
  ...
}

Remarks

Fired once for each log message generated by the struct. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the detail level of the message. Possible values are as follows:

Message is the log message.

LogType is reserved for future use.

on_make_directory_complete event (SSHPlex Struct)

Fired when a MakeDirectory operation completes (or fails).

Syntax

// SSHPlexMakeDirectoryCompleteEventArgs carries the SSHPlex MakeDirectoryComplete event's parameters.
pub struct SSHPlexMakeDirectoryCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexMakeDirectoryCompleteEvent defines the signature of the SSHPlex MakeDirectoryComplete event's handler function.
pub trait SSHPlexMakeDirectoryCompleteEvent {
  fn on_make_directory_complete(&self, sender : SSHPlex, e : &mut SSHPlexMakeDirectoryCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_make_directory_complete(&self) -> &'a dyn SSHPlexMakeDirectoryCompleteEvent;
  pub fn set_on_make_directory_complete(&mut self, value : &'a dyn SSHPlexMakeDirectoryCompleteEvent);
  ...
}

Remarks

This event fires when a MakeDirectory operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

RemotePath is the remote path that was specified when the operation was initiated.

on_remove_directory_complete event (SSHPlex Struct)

Fired when a RemoveDirectory operation completes (or fails).

Syntax

// SSHPlexRemoveDirectoryCompleteEventArgs carries the SSHPlex RemoveDirectoryComplete event's parameters.
pub struct SSHPlexRemoveDirectoryCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn directory_name(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexRemoveDirectoryCompleteEvent defines the signature of the SSHPlex RemoveDirectoryComplete event's handler function.
pub trait SSHPlexRemoveDirectoryCompleteEvent {
  fn on_remove_directory_complete(&self, sender : SSHPlex, e : &mut SSHPlexRemoveDirectoryCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_remove_directory_complete(&self) -> &'a dyn SSHPlexRemoveDirectoryCompleteEvent;
  pub fn set_on_remove_directory_complete(&mut self, value : &'a dyn SSHPlexRemoveDirectoryCompleteEvent);
  ...
}

Remarks

This event fires when a RemoveDirectory operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

DirectoryName is the name of the directory that was removed.

RemotePath is the remote path that was specified when the operation was initiated.

on_rename_file_complete event (SSHPlex Struct)

Fired when a RenameFile operation completes (or fails).

Syntax

// SSHPlexRenameFileCompleteEventArgs carries the SSHPlex RenameFileComplete event's parameters.
pub struct SSHPlexRenameFileCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
  fn new_file_name(&self) -> &String
}

// SSHPlexRenameFileCompleteEvent defines the signature of the SSHPlex RenameFileComplete event's handler function.
pub trait SSHPlexRenameFileCompleteEvent {
  fn on_rename_file_complete(&self, sender : SSHPlex, e : &mut SSHPlexRenameFileCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_rename_file_complete(&self) -> &'a dyn SSHPlexRenameFileCompleteEvent;
  pub fn set_on_rename_file_complete(&mut self, value : &'a dyn SSHPlexRenameFileCompleteEvent);
  ...
}

Remarks

This event fires when a RenameFile operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

RemoteFile is the remote file that was specified when the operation was initiated.

RemotePath is the remote path that was specified when the operation was initiated.

NewFileName is the name to which the file was renamed as provided when rename_file was originally called.

on_ssh_custom_auth event (SSHPlex Struct)

Fired when the struct is doing a custom authentication.

Syntax

// SSHPlexSSHCustomAuthEventArgs carries the SSHPlex SSHCustomAuth event's parameters.
pub struct SSHPlexSSHCustomAuthEventArgs {
  fn packet(&self) -> &String
  fn set_packet(&self, value : &str)
  fn set_packet_ref(&self, value : &String)
}

// SSHPlexSSHCustomAuthEvent defines the signature of the SSHPlex SSHCustomAuth event's handler function.
pub trait SSHPlexSSHCustomAuthEvent {
  fn on_ssh_custom_auth(&self, sender : SSHPlex, e : &mut SSHPlexSSHCustomAuthEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_ssh_custom_auth(&self) -> &'a dyn SSHPlexSSHCustomAuthEvent;
  pub fn set_on_ssh_custom_auth(&mut self, value : &'a dyn SSHPlexSSHCustomAuthEvent);
  ...
}

Remarks

on_ssh_custom_auth is fired during the user authentication stage of the Secure Shell (SSH) logon process if ssh_auth_mode is set to amCustom. Packet contains the last raw SSH packet sent by the server, in HEX-encoded format.

The client should create a new raw SSH packet to send to the server and set Packet to the HEX-encoded representation of the packet to send.

In all cases, Packet will start with the message type field.

To read the incoming packet, call decode_packet and then use the get_ssh_param and get_ssh_param_bytes methods. To create a packet, use the set_ssh_param method and then call encode_packet to obtain a HEX-encoded value and assign this to the Packet parameter.

on_ssh_keyboard_interactive event (SSHPlex Struct)

Fired when the struct receives a request for user input from the server.

Syntax

// SSHPlexSSHKeyboardInteractiveEventArgs carries the SSHPlex SSHKeyboardInteractive event's parameters.
pub struct SSHPlexSSHKeyboardInteractiveEventArgs {
  fn name(&self) -> &String
  fn instructions(&self) -> &String
  fn prompt(&self) -> &String
  fn response(&self) -> &String
  fn set_response(&self, value : &str)
  fn set_response_ref(&self, value : &String)
  fn echo_response(&self) -> bool
}

// SSHPlexSSHKeyboardInteractiveEvent defines the signature of the SSHPlex SSHKeyboardInteractive event's handler function.
pub trait SSHPlexSSHKeyboardInteractiveEvent {
  fn on_ssh_keyboard_interactive(&self, sender : SSHPlex, e : &mut SSHPlexSSHKeyboardInteractiveEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_ssh_keyboard_interactive(&self) -> &'a dyn SSHPlexSSHKeyboardInteractiveEvent;
  pub fn set_on_ssh_keyboard_interactive(&mut self, value : &'a dyn SSHPlexSSHKeyboardInteractiveEvent);
  ...
}

Remarks

on_ssh_keyboard_interactive is fired during the user authentication stage of the Secure Shell (SSH) logon process. During authentication, the struct will request a list of available authentication methods for the ssh_user. For example, if the ssh_host responds with "keyboard-interactive", the struct will fire this event to allow the client application to set the password.

During authentication, the SSH server may respond with a request for the user's authentication information. Name is a server-provided value associated with the authentication method such as "CRYPTOCard Authentication". Instructions will contain specific instructions, also supplied by the server, for how the user should respond.

Along with these values, the server will also send at least one input Prompt to be displayed to and filled out by the user. Response should be set to the user's input, and will be sent back in the user authentication information response. EchoResponse is a server recommendation for whether or not the user's response should be echoed back during input.

NOTE: The server may send several prompts in a single packet. The struct will fire the on_ssh_keyboard_interactive event once for each prompt.

on_ssh_server_authentication event (SSHPlex Struct)

Fired after the server presents its public key to the client.

Syntax

// SSHPlexSSHServerAuthenticationEventArgs carries the SSHPlex SSHServerAuthentication event's parameters.
pub struct SSHPlexSSHServerAuthenticationEventArgs {
  fn host_key(&self) -> &[u8]
  fn fingerprint(&self) -> &String
  fn key_algorithm(&self) -> &String
  fn cert_subject(&self) -> &String
  fn cert_issuer(&self) -> &String
  fn status(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// SSHPlexSSHServerAuthenticationEvent defines the signature of the SSHPlex SSHServerAuthentication event's handler function.
pub trait SSHPlexSSHServerAuthenticationEvent {
  fn on_ssh_server_authentication(&self, sender : SSHPlex, e : &mut SSHPlexSSHServerAuthenticationEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_ssh_server_authentication(&self) -> &'a dyn SSHPlexSSHServerAuthenticationEvent;
  pub fn set_on_ssh_server_authentication(&mut self, value : &'a dyn SSHPlexSSHServerAuthenticationEvent);
  ...
}

Remarks

This event is fired when the client can decide whether or not to continue with the connection process. If the public key is known to be a valid key for the Secure Shell (SSH) server, Accept should be set to True within the event. Otherwise, the server will not be authenticated and the connection will be broken.

Accept will be True only if either HostKey or Fingerprint is identical to the value of ssh_accept_server_host_key.

Accept may be set to True manually to accept the server host key.

NOTE: SSH's security inherently relies on client verification of the host key. Ignoring the host key and always setting Accept to True is strongly discouraged, and could cause potentially serious security vulnerabilities in your application. It is recommended that clients maintain a list of known keys for each server and check HostKey against this list each time a connection is attempted.

Host Key contains the full binary text of the key, in the same format used internally by SSH.

Fingerprint holds the SHA-256 hash of HostKey in the hex-encoded form: 0a:1b:2c:3d. To configure the hash algorithm used to calculate this value, see SSHFingerprintHashAlgorithm. To configure the encoding format used when displaying this value, see SSHFingerprintEncoding.

KeyAlgorithm identifies the host key algorithm. The following values are supported:

• ssh-rsa
• ssh-dss
• rsa-sha2-256
• rsa-sha2-512
• x509v3-sign-rsa
• x509v3-sign-dss
• ecdsa-sha2-nistp256
• ecdsa-sha2-nistp384
• ecdsa-sha2-nistp521

CertSubject is the subject of the certificate. This is applicable only when KeyAlgorithm is "x509v3-sign-rsa" or "x509v3-sign-dss".

CertIssuer is the issuer of the certificate. This is applicable only when KeyAlgorithm is "x509v3-sign-rsa" or "x509v3-sign-dss".

Status is reserved for future use.

on_ssh_status event (SSHPlex Struct)

Fired to track the progress of the secure connection.

Syntax

// SSHPlexSSHStatusEventArgs carries the SSHPlex SSHStatus event's parameters.
pub struct SSHPlexSSHStatusEventArgs {
  fn message(&self) -> &String
}

// SSHPlexSSHStatusEvent defines the signature of the SSHPlex SSHStatus event's handler function.
pub trait SSHPlexSSHStatusEvent {
  fn on_ssh_status(&self, sender : SSHPlex, e : &mut SSHPlexSSHStatusEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_ssh_status(&self) -> &'a dyn SSHPlexSSHStatusEvent;
  pub fn set_on_ssh_status(&mut self, value : &'a dyn SSHPlexSSHStatusEvent);
  ...
}

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

on_start_transfer event (SSHPlex Struct)

Fired when a file starts downloading or uploading.

Syntax

// SSHPlexStartTransferEventArgs carries the SSHPlex StartTransfer event's parameters.
pub struct SSHPlexStartTransferEventArgs {
  fn operation_id(&self) -> &String
  fn direction(&self) -> i32
  fn local_file(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
  fn file_permissions(&self) -> &String
  fn set_file_permissions(&self, value : &str)
  fn set_file_permissions_ref(&self, value : &String)
}

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

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

Remarks

This event is fired once per file when it starts downloading or uploading.

OperationId is the string associated with the operation fired this event.

Direction is 0 for uploads and 1 for downloads.

LocalFile, RemoteFile, and RemotePath are populated with values of local_file, remote_file, and remote_path, respectively, that are associated with the method that triggered this event.

FilePermissions includes information about the file that can be modified before finishing the upload or download.

on_stderr event (SSHPlex Struct)

Fired when data (complete lines) come in through Stderr.

Syntax

// SSHPlexStderrEventArgs carries the SSHPlex Stderr event's parameters.
pub struct SSHPlexStderrEventArgs {
  fn operation_id(&self) -> &String
  fn text(&self) -> &[u8]
}

// SSHPlexStderrEvent defines the signature of the SSHPlex Stderr event's handler function.
pub trait SSHPlexStderrEvent {
  fn on_stderr(&self, sender : SSHPlex, e : &mut SSHPlexStderrEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_stderr(&self) -> &'a dyn SSHPlexStderrEvent;
  pub fn set_on_stderr(&mut self, value : &'a dyn SSHPlexStderrEvent);
  ...
}

Remarks

The Stderr event is fired every time the process on the remote host outputs a line in its error output. The incoming data are provided through the Text parameter.

on_stdout event (SSHPlex Struct)

Fired when data (complete lines) come in through Stdout.

Syntax

// SSHPlexStdoutEventArgs carries the SSHPlex Stdout event's parameters.
pub struct SSHPlexStdoutEventArgs {
  fn operation_id(&self) -> &String
  fn text(&self) -> &[u8]
}

// SSHPlexStdoutEvent defines the signature of the SSHPlex Stdout event's handler function.
pub trait SSHPlexStdoutEvent {
  fn on_stdout(&self, sender : SSHPlex, e : &mut SSHPlexStdoutEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_stdout(&self) -> &'a dyn SSHPlexStdoutEvent;
  pub fn set_on_stdout(&mut self, value : &'a dyn SSHPlexStdoutEvent);
  ...
}

Remarks

The Stdout event is fired every time the process on the remote host outputs a line in its standard output. The incoming data are provided through the Text parameter.

on_transfer event (SSHPlex Struct)

Fired during file download or upload.

Syntax

// SSHPlexTransferEventArgs carries the SSHPlex Transfer event's parameters.
pub struct SSHPlexTransferEventArgs {
  fn operation_id(&self) -> &String
  fn direction(&self) -> i32
  fn local_file(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
  fn bytes_transferred(&self) -> i64
  fn percent_done(&self) -> i32
  fn text(&self) -> &[u8]
  fn cancel(&self) -> bool
  fn set_cancel(&self, value : bool)
}

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

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

Remarks

This event is fired once per file when it starts downloading or uploading.

OperationId is associated with the operation that fired this event. Direction is 0 for uploads and 1 for downloads. LocalFile, RemoteFile, and RemotePath are populated with values of local_file, remote_file, and remote_path, respectively, that are associated with the operation that fired this event.

BytesTransferred shows the number of bytes transferred since the beginning of the transfer, and PercentDone contains the percentage (0-100) of bytes transferred based on the Direction being transferred. If PercentDone cannot be calculated the value will be -1.

Text contains the text of the file being transferred.

Setting Cancel to True will cancel the associated operation without firing a on_download_complete or on_upload_complete event. It is not equivalent to calling cancel_operation with the associated OperationId, which will fire the aforementioned events.

on_update_file_attributes_complete event (SSHPlex Struct)

Fired when a UpdateFileAttributes operation completes (or fails).

Syntax

// SSHPlexUpdateFileAttributesCompleteEventArgs carries the SSHPlex UpdateFileAttributesComplete event's parameters.
pub struct SSHPlexUpdateFileAttributesCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexUpdateFileAttributesCompleteEvent defines the signature of the SSHPlex UpdateFileAttributesComplete event's handler function.
pub trait SSHPlexUpdateFileAttributesCompleteEvent {
  fn on_update_file_attributes_complete(&self, sender : SSHPlex, e : &mut SSHPlexUpdateFileAttributesCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_update_file_attributes_complete(&self) -> &'a dyn SSHPlexUpdateFileAttributesCompleteEvent;
  pub fn set_on_update_file_attributes_complete(&mut self, value : &'a dyn SSHPlexUpdateFileAttributesCompleteEvent);
  ...
}

Remarks

This event fires when an UpdateFileAttributes operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

RemoteFile is the remote file that was specified when the operation was initiated.

RemotePath is the remote path that was specified when the operation was initiated.

on_upload_complete event (SSHPlex Struct)

Fired when an upload operation completes (or fails).

Syntax

// SSHPlexUploadCompleteEventArgs carries the SSHPlex UploadComplete event's parameters.
pub struct SSHPlexUploadCompleteEventArgs {
  fn operation_id(&self) -> &String
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn local_file(&self) -> &String
  fn remote_file(&self) -> &String
  fn remote_path(&self) -> &String
}

// SSHPlexUploadCompleteEvent defines the signature of the SSHPlex UploadComplete event's handler function.
pub trait SSHPlexUploadCompleteEvent {
  fn on_upload_complete(&self, sender : SSHPlex, e : &mut SSHPlexUploadCompleteEventArgs);
}

impl <'a> SSHPlex<'a> {
  pub fn on_upload_complete(&self) -> &'a dyn SSHPlexUploadCompleteEvent;
  pub fn set_on_upload_complete(&mut self, value : &'a dyn SSHPlexUploadCompleteEvent);
  ...
}

Remarks

This event fires when an upload operation completes either successfully or unsuccessfully. If the operation succeeded, ErrorCode will be 0. If the operation failed or was canceled by cancel_operation, ErrorCode will contain a nonzero value and ErrorDescription will contain a description of the error. Please refer to the Error Codes section for possible error codes.

OperationId is the Id of the completed operation. This value will match the Operation Id returned by the method that initiated the operation.

ErrorCode holds the error code (if any). A value of 0 indicates success. A positive value indicates failure.

ErrorDescription is a description of the error.

LocalFile is the local file that was specified when the operation was initiated.

RemoteFile is the remote file that was specified when the operation was initiated.

RemotePath is the remote path that was specified when the operation was initiated.

Config Settings (SSHPlex Struct)

SFTPClient Config Settings

SCP Config Settings

SShell Config Settings

SExec Config Settings

SSHClient Config Settings

*SSH-1.99-*,*SSH-2.0-*,*SSH-2.99-*

TCPClient Config Settings

Socket Config Settings

Base Config Settings

Trappable Errors (SSHPlex Struct)

SSHPlex Errors

SFTPClient Errors

SCP Errors

SExec Errors

SShell Errors

SSHClient Errors

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

TCPClient Errors

TCP/IP Errors