Scp

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

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.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

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.

Example

const Abort = struct {
    stop: std.atomic.Value(bool) = .init(false),
    pub fn abortCheck(self: *Abort) bool {
        return self.stop.load(.acquire); // another thread may call abort.stop.store(true, .release)
    }
};

var abort = Abort{};
scp.setHeartbeatMs(250); // call abortCheck 4 times per second
scp.setEventHandler(&abort);
defer scp.clearEventHandler();

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

Example

const Progress = struct {
    pub fn percentDone(_: *Progress, pct: i32) bool {
        // pct ranges from 1 to 100.
        std.debug.print("Percent done: {d}\n", .{pct});
        return false; // return true to abort the method in progress
    }
};

var progress = Progress{};
scp.setEventHandler(&progress);
defer scp.clearEventHandler();

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.

Example

const Info = struct {
    pub fn progressInfo(_: *Info, name: [:0]const u8, value: [:0]const u8) void {
        std.debug.print("{s}: {s}\n", .{ name, value });
    }
};

var info = Info{};
scp.setEventHandler(&info);
defer scp.clearEventHandler();