Chilkat2::Scp

Set to 1 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 0 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: 1 means success, 0 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 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. 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 $remotePath 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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Downloads the file at $remotePath 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 undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Downloads the file at $remotePath from the SSH server and writes its bytes to the local filesystem path in $localPath.

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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Downloads the file at $remotePath, 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 undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Synchronizes files from the remote directory tree rooted at $remoteRoot to the local directory rooted at $localRoot. $bRecurse controls recursion: set it to 1 to descend into subdirectories, or 0 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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Synchronizes files from the local directory tree rooted at $localBaseDir to the remote directory rooted at $remoteBaseDir. $bRecurse controls recursion: set it to 1 to descend into subdirectories, or 0 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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Uploads all bytes currently contained in the BinData object in $bd to the remote file at $remotePath. 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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Decodes the text in $encodedData using the binary encoding named by $encoding, then uploads the resulting bytes to the remote file at $remotePath. 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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Uploads the local filesystem file at $localPath to the remote path in $remotePath. 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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

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

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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

Associates this Scp object with the connected and authenticated Ssh object in $sshConnection. 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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.

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

my $deadline = time() + 30;                          # give up after 30 seconds
$scp->HeartbeatMs(250);                      # call the handler 4 times per second
$scp->on(AbortCheck => sub { return time() > $deadline });

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 1. This will cause the method to terminate and return a failure status or corresponding failure value.

Example

$scp->on(PercentDone => sub {
    my ($pctDone) = @_;     # 0 to 100
    print "Percent done: $pctDone\n";
    return 0;               # return a true value to abort the method in progress
});

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

$scp->on(ProgressInfo => sub {
    my ($name, $value) = @_;
    print "$name: $value\n";
});