What the Class Is Used For

Use Chilkat.Scp when an application already has an authenticated Ssh connection and needs to transfer files with SCP. The SCP object does not create the SSH connection itself; instead, it uses an existing Ssh object supplied by UseSsh. Connection settings, socket settings, proxy settings, timeouts, and session logging configured on the SSH object apply to SCP transfers.

Upload Files and Data Upload local files, strings, binary arrays, encoded binary strings, or BinData to the SSH server.

Download Files and Data Download remote files to local files, strings, binary arrays, encoded strings, or BinData.

Synchronize Directory Trees Upload or download directory trees using modes for all files, missing files, newer files, and size differences.

Filter Sync Operations Include or exclude files and directories with wildcard patterns.

Typical SCP Workflow

Create and connect a Ssh object.
Authenticate the SSH session using the appropriate SSH authentication method.
Create a Scp object.
Call UseSsh, passing the connected and authenticated Ssh object.
Optionally configure SCP-specific properties such as UnixPermOverride, SendEnv, sync filters, progress behavior, or uncommon options.
Call an upload, download, or sync method.
Check LastErrorText after failures or unexpected behavior.

Key requirement: Call UseSsh before SCP transfers. The SCP object uses the SSH connection internally for all file transfer work.

Core Concepts

Concept	Meaning	Important Members
Existing SSH Connection	SCP transfers run over a connected and authenticated Ssh object.	UseSsh
Remote Path	The path of the file on the remote SSH server.	UploadFile, DownloadFile, UploadString, DownloadString
Local Path	The path of a file on the local filesystem for upload or download.	UploadFile, DownloadFile, SyncedFiles
Binary Transfer	Transfers raw file bytes using byte arrays, encoded strings, or BinData.	UploadBinary, DownloadBinary, UploadBd, DownloadBd
Text Transfer	Transfers string content using a specified character set.	UploadString, DownloadString
Tree Synchronization	Uploads or downloads directory trees according to mode and recursion settings.	SyncTreeUpload, SyncTreeDownload, SyncedFiles

Connection Setup

Method	Purpose	Important Details
UseSsh	Associates the SCP object with an existing SSH connection.	All connection, socket, proxy, timeout, and session-log settings on the Ssh object apply to SCP transfers because the SSH object performs the underlying work.
LoadTaskCaller	Loads the caller of an async method’s task.	Used with asynchronous task workflows.

Upload Methods

Method	Input	Use Case
UploadFile	Local file path and remote file path.	Upload a file from the local filesystem to the remote SSH server.
UploadString	Remote path, text string, and charset.	Upload text content directly to a remote file.
UploadBinary	Remote path and byte array.	Upload binary data held in memory.
UploadBinaryEncoded	Remote path, encoded data string, and encoding name.	Upload binary data supplied as an encoded string, such as base64 or hex.
UploadBd	Remote path and BinData.	Upload the contents of a BinData object to a remote file.
SyncTreeUpload	Local base directory, remote base directory, sync mode, and recurse flag.	Upload a directory tree to the SSH server according to synchronization rules.

Download Methods

Method	Output	Use Case
DownloadFile	Local filesystem file.	Download a remote file from the SSH server to a local path.
DownloadString	Text string decoded with the supplied charset.	Download a remote text file directly into a string.
DownloadBinary	Byte array.	Download a remote binary file into memory.
DownloadBinaryEncoded	Encoded string.	Download a remote file and return the bytes encoded as base64, hex, or another supported encoding.
DownloadBd	Appends to a BinData object.	Download a binary file and append its bytes to existing BinData content.
SyncTreeDownload	Local directory tree.	Download a remote directory tree according to synchronization rules.

Append behavior: DownloadBd appends downloaded bytes to the existing contents of the supplied BinData object.

Tree Synchronization

SyncTreeUpload and SyncTreeDownload transfer directory trees using a mode argument and a recurse flag. After a sync operation, SyncedFiles contains the full local paths of files uploaded or downloaded, one path per line.

Direction	Method	Root Arguments	Recursion
Upload	SyncTreeUpload	localBaseDir to remoteBaseDir.	Controlled by bRecurse.
Download	SyncTreeDownload	remoteRoot to localRoot.	Controlled by bRecurse.

Sync Upload Modes

Mode	Upload Behavior
0	Upload all files.
1	Upload all files that do not exist on the remote server.
2	Upload newer or non-existent files.
3	Upload only newer files. If a file does not already exist on the remote server, it is not uploaded.
4	Transfer missing files or files with size differences.
5	Same as mode 4, but also transfers newer files.

Sync Download Modes

Mode	Download Behavior
0	Download all files.
1	Download all files that do not exist on the local filesystem.
2	Download newer or non-existent files.
3	Download only newer files. If a file does not already exist locally, it is not downloaded.
5	Download only missing files or files with size differences.
6	Same as mode 5, but also downloads newer files.

Sync Filtering Properties

Property	Applies To	Behavior	Example
SyncMustMatch	Filenames	Only transfer files whose filename matches one of the wildcard patterns.	.xml;.txt;*.csv
SyncMustNotMatch	Filenames	Do not transfer files whose filename matches any listed wildcard pattern.	.tmp;.bak
SyncMustMatchDir	Directory names	Only traverse into directories whose names match one of the wildcard patterns.	a;b;c*
SyncMustNotMatchDir	Directory names	Do not traverse into directories whose names match any listed wildcard pattern.	temp;cache
SyncedFiles	Last sync operation	Contains one full local file path per line for files uploaded or downloaded in the last sync operation.	Local paths only, not remote paths.

Pattern format: Sync include/exclude lists are wildcarded filename or directory-name patterns separated by semicolons.

Transfer Behavior Properties

Property	Purpose	Guidance
SendEnv	JSON string specifying environment variables to set for each SCP upload or download.	Use JSON name/value pairs, such as {"LCS_PASSWORD":"myPassword"}.
UnixPermOverride	Forces remote file permissions for uploaded files.	Set to an octal permissions string such as 0644. Leave empty to mirror local file permissions.
UncommonOptions	Enables uncommon SCP behaviors with comma-separated keywords.	Defaults to empty. Supported documented keywords include FilenameOnly and ProtectFromVpn.

Uncommon Options

Keyword	Introduced	Behavior	Typical Use
FilenameOnly	v9.5.0.77	Uses only the filename in the scp -t command.	Compatibility with systems such as LANCOM routers that require this behavior.
ProtectFromVpn	v9.5.0.80	On Android systems, bypasses any VPN that may be installed or active.	Android environments where SCP traffic must avoid the active VPN path.

Format: Set UncommonOptions to a comma-separated list of keywords when more than one option is needed.

Method Summary by Category

Category	Methods	Purpose
SSH association	UseSsh	Attach the SCP object to an existing SSH connection.
File upload	UploadFile	Upload a local file to a remote path.
File download	DownloadFile	Download a remote file to a local path.
String transfer	UploadString, DownloadString	Transfer text data using an explicit charset.
Binary transfer	UploadBinary, DownloadBinary, UploadBinaryEncoded, DownloadBinaryEncoded	Transfer binary data as byte arrays or encoded strings.
BinData transfer	UploadBd, DownloadBd	Transfer binary content using BinData.
Directory tree sync	SyncTreeUpload, SyncTreeDownload	Upload or download directory trees according to sync modes, recursion, and filters.
Async support	LoadTaskCaller	Loads the caller associated with an async task.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
SCP transfer fails immediately	UseSsh, LastErrorText	Confirm a connected and authenticated Ssh object was passed to UseSsh.
Remote permissions are not what is expected	UnixPermOverride	Set an explicit octal permission string such as 0644 when remote permissions should not mirror the local file permissions.
Sync transfers too many files	SyncMustMatch, SyncMustNotMatch	Add include or exclude filename patterns to restrict which files are transferred.
Sync enters unwanted directories	SyncMustMatchDir, SyncMustNotMatchDir	Use directory include/exclude wildcard patterns to control traversal.
Need to know which files were synced	SyncedFiles	Read SyncedFiles after SyncTreeUpload or SyncTreeDownload. It contains full local paths, one per line.
Compatibility problem with remote SCP target	UncommonOptions	Try documented compatibility keywords such as FilenameOnly when the remote system requires special SCP command behavior.
Transfer needs cancellation	AbortCurrent, HeartbeatMs	Use abort support for long-running network or file operations. Configure heartbeat callbacks when the environment supports them.
Need progress callbacks with finer granularity	PercentDoneScale	Increase the scale, such as 1000, for 0.1% granularity in event-enabled environments.

Common Pitfalls

Pitfall	Better Approach
Trying to use SCP without first associating an SSH connection.	Connect and authenticate an Ssh object, then call UseSsh.
Expecting SCP to use connection settings configured on the SCP object.	Configure connection, proxy, timeout, and logging settings on the Ssh object before calling UseSsh.
Using text methods for arbitrary binary content.	Use UploadBinary, UploadBinaryEncoded, UploadBd, DownloadBinary, DownloadBinaryEncoded, or DownloadBd for binary data.
Forgetting that DownloadBd appends data.	Clear or create a new BinData object first when replacement behavior is desired.
Assuming sync filters apply to full paths.	Filename filters match filenames, and directory filters match directory names.
Confusing upload and download sync mode numbers.	Review the upload and download mode tables separately because their mode sets differ.
Expecting SyncedFiles to contain remote paths.	SyncedFiles contains full local file paths for both upload and download sync operations.

Best Practices

Recommendation	Reason
Set up and test the Ssh connection first.	SCP depends on the existing SSH connection for authentication, transport, proxy behavior, timeouts, and logging.
Use BinData or binary methods for non-text files.	This avoids accidental character-set conversion of binary content.
Specify charsets when using string transfer methods.	UploadString and DownloadString need a charset to encode or decode text correctly.
Set UnixPermOverride when remote permissions must be predictable.	Otherwise, uploaded remote file permissions are based on the local file’s permissions.
Use sync filters before large sync operations.	Include and exclude patterns reduce unnecessary traversal and transfers.
Read SyncedFiles after sync operations.	It provides an audit list of files uploaded or downloaded during the last sync.
Use uncommon options only for documented compatibility cases.	FilenameOnly and ProtectFromVpn are specialized options and should not normally be needed.
Check LastErrorText after failures.	It provides the most useful diagnostic detail for SSH association, upload, download, sync, path, permission, filtering, and network problems.

Summary

Chilkat.Scp is the Chilkat class for SCP file transfer over an existing SSH connection. It supports local-file upload/download, in-memory binary transfer, encoded binary transfer, text transfer with charsets, BinData transfer, directory-tree synchronization, sync filtering, remote UNIX permission overrides, environment variables, progress scaling, abort support, and async task integration.

The most important practical guidance is to configure and authenticate the Ssh object first, call UseSsh, choose text or binary methods based on the data type, use sync modes and filters deliberately, and inspect LastErrorText when a transfer fails.

Chilkat.Scp Class Overview