Scp Rust Reference Documentation

Scp

Current Version: 11.6.1
Requires Chilkat Bundle License

Chilkat.Scp

Transfer files, text, and binary data over SCP using an existing SSH connection.

Chilkat.Scp is the Chilkat class for SCP file transfer over an already-established Chilkat.Ssh connection. It supports local-file upload and download, in-memory binary transfer, encoded binary transfer, text transfer with explicit character sets, BinData transfer, directory-tree synchronization, sync filtering, remote UNIX permission overrides, environment variables, progress scaling, abort support, and asynchronous task integration.

Uses an SSH connection

Attach Scp to an authenticated Chilkat.Ssh session rather than opening a separate network connection.

Upload and download files

Transfer local files to remote paths or download remote files to the local filesystem using SCP.

Memory-based transfers

Upload or download binary data, encoded data, text, or Chilkat.BinData without requiring temporary files.

Directory synchronization

Synchronize directory trees and use filtering options to include or exclude selected files.

Remote file options

Set remote UNIX permissions, pass environment variables, and control transfer-related behavior required by the remote server.

Progress and async support

Monitor progress, scale progress percentages, abort active transfers, and run supported operations as asynchronous tasks.

Common pattern: Connect and authenticate with Chilkat.Ssh, initialize Chilkat.Scp with that SSH connection, then upload, download, or synchronize the desired files or in-memory data. Use Scp for SCP-style transfers over SSH; use Chilkat.SFtp when the remote server expects the SFTP protocol instead.

For an extended overview, see Scp Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::Scp;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let scp = Scp::new();
// ... the native object is freed when `scp` goes out of scope.
pub fn new() -> Scp

Creates the underlying native Chilkat object (Scp also implements Default). Every method takes &self, so the object never needs to be declared mut. A Scp is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for Scp

The native object is freed when the Scp is dropped — when it goes out of scope, or explicitly with drop(scp). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<Scp>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match scp.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

AbortCurrent
// read/write
pub fn abort_current(&self) -> bool
pub fn set_abort_current(&self, value: bool)
Introduced in version 9.5.0.58

Set to true to request cancellation of the method currently executing on this object. Long-running network and file-transfer operations check this property periodically; a method that completes quickly may finish before the request is observed.

Both synchronous and asynchronous operations can be cancelled. To cancel a synchronous call, set this property from another thread on the same Scp object. Chilkat resets the property to false after the cancellation is processed. If no method is running, a previously set value is cleared when the next method begins.

Cooperative cancellation: This property requests an abort; it does not forcibly terminate a thread. Use the method return value, LastMethodSuccess where applicable, and LastErrorText to determine the final outcome.

top
DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
HeartbeatMs
// read/write
pub fn heartbeat_ms(&self) -> i32
pub fn set_heartbeat_ms(&self, value: i32)

Specifies the interval, in milliseconds, between AbortCheck event callbacks during supported long-running operations. The callback allows the application to report activity or request cancellation before the operation completes.

The default value is 0, which disables periodic AbortCheck callbacks.

Event-callback setting: This property is useful only in programming environments that support Chilkat event callbacks. It is not an SSH keep-alive interval and does not change connection or read timeouts.

More Information and Examples
Event Callback Examples
top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
PercentDoneScale
// read/write
pub fn percent_done_scale(&self) -> i32
pub fn set_percent_done_scale(&self, value: i32)
Introduced in version 9.5.0.51

Specifies the value that represents 100% completion in PercentDone event callbacks. The default is 100, which reports progress in whole-percent units. For example, when the scale is 1000, a callback value of 453 represents 45.3% completion.

The value is limited to the range 10 through 100000. Increasing the scale provides finer numeric granularity for operations whose progress can be measured.

Event-callback setting: This property applies only in programming environments that support Chilkat event callbacks. A larger scale changes the meaning and possible granularity of callback values; it does not guarantee that every intermediate value will be reported.

top
SendEnv
// read/write
pub fn send_env(&self) -> String
pub fn set_send_env(&self, value: &str)
Introduced in version 9.5.0.79

Specifies environment variables to send for each SCP upload or download. Set the property to a JSON object whose member names are environment-variable names and whose values are strings.

{
  "LCS_PASSWORD": "myPassword",
  "SOME_ENV_VAR": "some_value"
}
Server policy controls acceptance: SCP transfers run through SSH channels. The SSH server may accept, reject, or ignore requested environment variables according to its configuration. Do not assume that setting this property guarantees that the remote SCP process receives every variable.
Sensitive values: Environment variables can contain secrets, but they are not a substitute for SSH authentication. Avoid exposing sensitive values in application logs or diagnostic output.

More Information and Examples
Setting Environment Variables for SCP Transfers
top
SyncedFiles
// read/write
pub fn synced_files(&self) -> String
pub fn set_synced_files(&self, value: &str)
Introduced in version 9.5.0.51

Contains the local paths of the files transferred by the most recent call to SyncTreeUpload or SyncTreeDownload. Paths are listed one per line.

  • After an upload, each line is the full local path of a source file that was uploaded.
  • After a download, each line is the full local path of a destination file that was downloaded.
Local paths only: This property reports local filesystem paths, not remote paths. It lists files actually transferred by the last synchronization operation, rather than every file examined during comparison.

More Information and Examples
SCP Sync Tree DownloadSCP Sync Tree Upload
top
SyncMustMatch
// read/write
pub fn sync_must_match(&self) -> String
pub fn set_sync_must_match(&self, value: &str)
Introduced in version 9.5.0.51

Specifies a semicolon-separated list of wildcard patterns for filenames that are eligible for transfer by SyncTreeUpload and SyncTreeDownload. A file is considered only when its filename matches at least one pattern.

For example, *.xml;*.txt;*.csv limits synchronization to XML, text, and CSV files. The default empty string imposes no include restriction.

Pattern scope: Patterns are matched against the final filename, not the full local or remote path. Directory traversal is controlled separately by SyncMustMatchDir and SyncMustNotMatchDir.

More Information and Examples
SCP Sync Tree DownloadSCP Sync Tree UploadSCP Download Files Matching a Pattern, such as *.txt
top
SyncMustMatchDir
// read/write
pub fn sync_must_match_dir(&self) -> String
pub fn set_sync_must_match_dir(&self, value: &str)
Introduced in version 9.5.0.58

Specifies a semicolon-separated list of wildcard patterns for directory names that may be traversed by SyncTreeUpload and SyncTreeDownload. When this property is nonempty, synchronization descends only into directories whose names match at least one pattern.

For example, a*;b*;c* permits traversal into directories whose names begin with a, b, or c. The default empty string permits traversal into all directories, subject to SyncMustNotMatchDir.

Pattern scope: Each pattern is matched against the directory name itself, not its complete path. This property affects traversal; it does not directly select individual files.

top
SyncMustNotMatch
// read/write
pub fn sync_must_not_match(&self) -> String
pub fn set_sync_must_not_match(&self, value: &str)
Introduced in version 9.5.0.51

Specifies a semicolon-separated list of wildcard patterns for filenames that must be skipped by SyncTreeUpload and SyncTreeDownload.

For example, *.tmp;*.bak;*.log excludes temporary, backup, and log files. The default empty string excludes no files.

Pattern scope: Patterns are matched against the final filename, not the full path. Use SyncMustNotMatchDir to prevent synchronization from entering selected directories and their subtrees.

More Information and Examples
SCP Sync Tree DownloadSCP Sync Tree Upload
top
SyncMustNotMatchDir
// read/write
pub fn sync_must_not_match_dir(&self) -> String
pub fn set_sync_must_not_match_dir(&self, value: &str)
Introduced in version 9.5.0.58

Specifies a semicolon-separated list of wildcard patterns for directory names that must not be traversed by SyncTreeUpload and SyncTreeDownload. A matching directory and everything below it are skipped.

For example, temp*;cache*;.git prevents traversal into temporary, cache, and Git metadata directories. The default empty string excludes no directories.

Pattern scope: Each pattern is matched against the directory name itself, not its complete path. This setting is especially useful during recursive synchronization because excluding a directory avoids scanning its entire subtree.

top
UncommonOptions
// read/write
pub fn uncommon_options(&self) -> String
pub fn set_uncommon_options(&self, value: &str)
Introduced in version 9.5.0.77

Provides a comma-separated list of specialized compatibility options. The default is the empty string, which is appropriate for normal SCP transfers.

KeywordBehavior
FilenameOnlyUses only the filename, rather than the complete target path, in the remote scp -t command. This option exists for compatibility with systems such as certain LANCOM routers.
ProtectFromVpnOn Android, attempts to route the SCP connection outside an installed or active VPN.
Leave empty unless needed: These options alter uncommon platform or server compatibility behavior. Enable a keyword only when a Chilkat example, release note, or support response identifies it as necessary for the target environment.

top
UnixPermOverride
// read/write
pub fn unix_perm_override(&self) -> String
pub fn set_unix_perm_override(&self, value: &str)
Introduced in version 9.5.0.77

Specifies an octal UNIX permission mode to apply to files uploaded by SCP, overriding the permissions derived from the local source file. For example, set this property to 0644 to grant read/write permission to the owner and read-only permission to the group and others.

The default is the empty string, which causes the uploaded file's remote permissions to be based on the local file's permissions.

UNIX permission notation: Supply the mode as a string containing octal digits, such as 0600, 0644, or 0755. The remote SSH account must still have permission to create or replace the file, and server-side policy may restrict the final mode.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
// read-only
pub fn version(&self) -> String

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

DownloadBd
pub fn download_bd(&self, remote_path: &str, bd: &BinData) -> Result<()>
Introduced in version 9.5.0.77

Downloads the file at remote_path and appends its exact bytes to the existing contents of the BinData object in bd.

An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory.

Append behavior: This method does not clear bd before downloading. Clear the BinData object first when the downloaded file should replace, rather than follow, its current contents.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
DownloadBinaryEncoded
pub fn download_binary_encoded(&self, remote_path: &str, encoding: &str) -> Result<String>
Introduced in version 9.5.0.51

Downloads the file at remote_path and returns its bytes encoded as text using the binary encoding named by encoding, such as base64 or hex.

An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory.

Binary encoding versus charset: encoding selects a text representation of arbitrary bytes; it is not a character set and does not decode the remote file as text. Use DownloadString when the remote file contains text that must be decoded with a charset.
Memory use: The complete file and its encoded representation are held in memory. Encodings such as Base64 also increase the amount of data returned.

Returns Err(chilkat::Error) on failure.

More Information and Examples
List of Supported Encodings (Base64, Hex, etc.)SCP Download/Upload Binary Files as Encoded Strings
top
DownloadFile
pub fn download_file(&self, remote_path: &str, local_path: &str) -> Result<()>
Introduced in version 9.5.0.51

Downloads the file at remote_path from the SSH server and writes its bytes to the local filesystem path in local_path.

An absolute remote path begins with /. A relative remote path is interpreted relative to the authenticated SSH user's home directory. The application must have permission to create or replace the local destination file.

Streaming transfer: This method is the preferred download method for large files because the data is written to disk rather than returned as one in-memory byte array or string.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
SCP Download FileSCP Download from a Specific Directory
top
DownloadString
pub fn download_string(&self, remote_path: &str, charset: &str) -> Result<String>
Introduced in version 9.5.0.51

Downloads the file at remote_path, decodes its bytes using the character encoding named by charset, and returns the resulting text.

An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory.

Charset matters: charset describes how the remote file’s bytes represent characters, for example utf-8, windows-1252, or iso-8859-1. Using the wrong charset can produce incorrect characters. Use a binary download method for files that are not text.

Returns Err(chilkat::Error) on failure.

More Information and Examples
SCP Download Text File to String Variable
top
SyncTreeDownload
pub fn sync_tree_download(&self, remote_root: &str, local_root: &str, mode: i32, b_recurse: bool) -> Result<()>
Introduced in version 9.5.0.51

Synchronizes files from the remote directory tree rooted at remote_root to the local directory rooted at local_root. b_recurse controls recursion: set it to true to descend into subdirectories, or false to process only files directly in the root directory.

An absolute remote root begins with /; a relative remote root is interpreted relative to the authenticated SSH user's home directory. A relative local root is interpreted relative to the application's current working directory.

ModeFiles transferred
0Download every eligible file.
1Download files that do not already exist locally.
2Download files that are missing locally or whose remote last-modified time is newer than the local file.
3Download only files whose remote last-modified time is newer. A remote file that has no local counterpart is not downloaded.
5Download files that are missing locally or whose size differs from the local file.
6Download files that are missing locally, differ in size, or have a newer remote last-modified time.

The filename and directory filters in SyncMustMatch, SyncMustNotMatch, SyncMustMatchDir, and SyncMustNotMatchDir are applied during traversal. After completion, SyncedFiles lists the full local paths of files actually downloaded.

Timestamp-based modes: Modes 2, 3, and 6 compare last-modified times. Incorrect server timestamps or clock differences between systems can affect which file is considered newer.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
SCP Sync Tree Download
top
SyncTreeUpload
pub fn sync_tree_upload(&self, local_base_dir: &str, remote_base_dir: &str, mode: i32, b_recurse: bool) -> Result<()>
Introduced in version 9.5.0.51

Synchronizes files from the local directory tree rooted at local_base_dir to the remote directory rooted at remote_base_dir. b_recurse controls recursion: set it to true to descend into subdirectories, or false to process only files directly in the local base directory.

A relative local base directory is interpreted relative to the application's current working directory. An absolute remote base directory begins with /; a relative remote base directory is interpreted relative to the authenticated SSH user's home directory.

ModeFiles transferred
0Upload every eligible file.
1Upload files that do not already exist on the remote server.
2Upload files that are missing remotely or whose local last-modified time is newer than the remote file.
3Upload only files whose local last-modified time is newer. A local file that has no remote counterpart is not uploaded.
4Upload files that are missing remotely or whose size differs from the remote file.
5Upload files that are missing remotely, differ in size, or have a newer local last-modified time.

The filename and directory filters in SyncMustMatch, SyncMustNotMatch, SyncMustMatchDir, and SyncMustNotMatchDir are applied during traversal. After completion, SyncedFiles lists the full local paths of files actually uploaded.

Timestamp-based modes: Modes 2, 3, and 5 compare last-modified times. Incorrect server timestamps or clock differences between systems can affect which file is considered newer.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
UploadBd
pub fn upload_bd(&self, remote_path: &str, bd: &BinData) -> Result<()>
Introduced in version 9.5.0.77

Uploads all bytes currently contained in the BinData object in bd to the remote file at remote_path. The data is transferred without character decoding or other transformation.

An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist.

Source object: The upload reads the current contents of bd and does not remove or modify those bytes.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
UploadBinaryEncoded
pub fn upload_binary_encoded(&self, remote_path: &str, encoded_data: &str, encoding: &str) -> Result<()>
Introduced in version 9.5.0.51

Decodes the text in encoded_data using the binary encoding named by encoding, then uploads the resulting bytes to the remote file at remote_path. Typical encoding names include base64 and hex.

An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist.

The encoded text is not uploaded literally: For example, when encoding is base64, Chilkat Base64-decodes encoded_data and transfers the decoded binary bytes. This method is for encoded binary representations, not character-set conversion.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
List of Supported Encodings (Base64, Hex, etc.)SCP Download/Upload Binary Files as Encoded Strings
top
UploadFile
pub fn upload_file(&self, local_path: &str, remote_path: &str) -> Result<()>
Introduced in version 9.5.0.51

Uploads the local filesystem file at local_path to the remote path in remote_path. The file is transferred as raw bytes.

An absolute remote path begins with /. A relative remote path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist, and the SSH account must have permission to create or replace the destination file.

Remote permissions are normally derived from the local file. Set UnixPermOverride when a specific remote UNIX mode is required.

SCP is not FTP: There is no ASCII or binary transfer mode. UploadFile copies the file bytes without line-ending or character-set conversion.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
SCP Upload FileSCP Upload to a Specific Remote Directory
top
UploadString
pub fn upload_string(&self, remote_path: &str, text_data: &str, charset: &str) -> Result<()>
Introduced in version 9.5.0.51

Encodes the text in text_data using the character encoding named by charset, then uploads the resulting bytes to the remote file at remote_path.

An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist.

Text encoding: charset controls how characters are converted to bytes, for example utf-8, windows-1252, or iso-8859-1. SCP itself has no text mode; any line-ending characters already present in text_data are encoded and transferred as part of the text.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
SCP Upload Contents of String to Remote File
top
UseSsh
pub fn use_ssh(&self, ssh_connection: &Ssh) -> Result<()>
Introduced in version 9.5.0.51

Associates this Scp object with the connected and authenticated Ssh object in ssh_connection. Subsequent SCP operations use that existing SSH session rather than opening a separate network connection.

Connection, proxy, timeout, host-key verification, algorithm, logging, and other transport-related settings belong to the Ssh object and therefore apply to the SCP operations performed through it. Keep the SSH object connected and available for as long as the Scp object is using it.

SCP and SFTP are different protocols: Scp performs SCP-style transfers over SSH and requires compatible SCP support on the remote system. Use Chilkat.SFtp when the server expects the SSH File Transfer Protocol subsystem or when directory listing and remote file-management features are needed.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top

Events

All Chilkat methods are synchronous: the call returns when the work is done. During a call, Scp raises three events so your application can show progress and offer a way out. Implement the chilkat::EventHandler trait (every method has a do-nothing default, so implement only the events you need) and install it with set_event_handler:

use chilkat::{Scp, EventHandler};

struct Progress;

impl EventHandler for Progress {
    fn percent_done(&mut self, pct: i32) -> bool {
        println!("{pct}%");
        false   // return true to abort the method in progress
    }
    fn progress_info(&mut self, name: &str, value: &str) {
        println!("{name}: {value}");
    }
}

let scp = Scp::new();
scp.set_event_handler(Progress);
scp.set_heartbeat_ms(250);   // raise abort_check 4 times per second during Chilkat calls

For a one-off handler the closure methods avoid writing a type; they may be combined, and each replaces the previously set closure for that one event (installing a closure removes a trait handler set earlier, and vice versa):

scp.on_percent_done(|pct| { println!("{pct}%"); false });
scp.on_progress_info(|name, value| println!("{name}: {value}"));
pub fn set_event_handler<H: EventHandler>(&self, handler: H)

Installs handler as the receiver of this object's events, replacing any handler or closures set earlier. The object owns the handler, which must be Send + 'static.

pub fn clear_event_handler(&self)

Removes the handler and any closures; events are no longer delivered.

AbortCheck fires at regular intervals controlled by the HeartbeatMs property (0, the default, disables it); PercentDone fires when an operation's completion percentage is known; ProgressInfo delivers named progress values. Returning true from abort_check or percent_done aborts the running method, which then returns Err.

Events fire on the thread that called the method, before that method returns. A panic inside a handler aborts the running method and is re-raised to the caller once the native library has returned, so it never unwinds through C frames. To abort a long operation from another thread, share an Arc<AtomicBool> with an abort_check handler, or set the object's AbortCurrent property to true.

AbortCheck
// EventHandler trait method; closure form: on_abort_check(FnMut() -> bool)
fn abort_check(&mut self) -> bool

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

scp.set_heartbeat_ms(250);   // call abort_check 4 times per second

let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let flag = stop.clone();
scp.on_abort_check(move || flag.load(std::sync::atomic::Ordering::Relaxed));
// ... another thread may now abort the method in progress with stop.store(true, Ordering::Relaxed)
top
PercentDone
// EventHandler trait method; closure form: on_percent_done(FnMut(i32) -> bool)
fn percent_done(&mut self, pct: i32) -> bool

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pct_done argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pct_done equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to true. This will cause the method to terminate and return a failure status or corresponding failure value.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

scp.on_percent_done(|pct| {
    // pct ranges from 1 to 100.
    println!("Percent done: {pct}");
    false   // return true to abort the method in progress
});
top
ProgressInfo
// EventHandler trait method; closure form: on_progress_info(FnMut(&str, &str))
fn progress_info(&mut self, name: &str, value: &str)

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

scp.on_progress_info(|name, value| println!("{name}: {value}"));
top