SFtp C++ Reference Documentation
CkSFtp
Current Version: 11.5.0
Chilkat.SFtp
Connect to an SSH server, authenticate with password or key-based
credentials, then initialize the SFTP subsystem before file operations.
Transfer files using simple path-based APIs, in-memory data, streams,
or handle-based methods when lower-level control is needed.
List directories, create and remove folders, rename files, delete files,
inspect attributes, and work with remote paths.
Upload or download directory trees and synchronize local and remote
folder structures.
Verify host keys, control accepted SSH algorithms, use private keys,
and configure proxy or network settings when required.
Use detailed error text, session logs, progress callbacks, bandwidth
limits, and timeout settings to troubleshoot real-world server behavior.
For an extended overview, see
SFtp Class Overview.
Transfer, list, manage, and synchronize files over SFTP.
Chilkat.SFtp is Chilkat's main class for secure file transfer
over SSH. It provides SSH connection and authentication, SFTP subsystem
initialization, uploads, downloads, directory listings, remote file
management, file attributes, handle-based file access, recursive
synchronization, bandwidth throttling, proxy support, host key
fingerprinting, SSH algorithm controls, and detailed diagnostics.
SSH + SFTP setup
Upload and download
Directory and file management
Sync-tree operations
Security controls
Diagnostics and reliability
Object Creation
// Local variable on the stack CkSFtp obj; // Dynamically allocate/delete CkSFtp *pObj = new CkSFtp(); // ... delete pObj;
Properties
AbortCurrent
void put_AbortCurrent(bool newVal);
Set to true to request that the currently running Chilkat operation abort. Both synchronous and asynchronous operations can be canceled; a synchronous call may be interrupted by setting this property from another thread.
When the abort is observed, the current method returns failure and Chilkat resets this property to false. If no method is running, it is reset when the next method begins.
AuthFailReason
Contains the result code from the most recent call to AuthenticatePw, AuthenticatePk, AuthenticatePwPk, or a corresponding secure-string authentication method.
LastErrorText for detailed diagnostics.false; do not use an older value to describe the current session.BandwidthThrottleDown
void put_BandwidthThrottleDown(int newVal);
Specifies the approximate maximum download rate, in bytes per second. The default is 0, which disables download throttling.
BandwidthThrottleUp
void put_BandwidthThrottleUp(int newVal);
Specifies the approximate maximum upload rate, in bytes per second. The default is 0, which disables upload throttling.
ClientIdentifier
const char *clientIdentifier(void);
void put_ClientIdentifier(const char *newVal);
Specifies the SSH client-identification string sent when a connection is established. The default begins with SSH-2.0-Chilkat_ followed by the Chilkat version, for example SSH-2.0-Chilkat_11.6.0.
SSH-2.0-. A server may disconnect if the identification string is invalid.ClientIpAddress
const char *clientIpAddress(void);
void put_ClientIpAddress(const char *newVal);
This property is normally left unset. Set it only on a multihomed computer when the application must bind the outgoing connection to a specific local network interface.
Specify a numeric IPv4 or IPv6 address, not a hostname. When the property is empty, the operating system automatically chooses the local address.
topConnectTimeoutMs
void put_ConnectTimeoutMs(int newVal);
Specifies the maximum number of milliseconds allowed for the remote endpoint to accept the TCP connection.
IdleTimeoutMs and method-specific timeouts.DebugLogFilePath
const char *debugLogFilePath(void);
void put_DebugLogFilePath(const char *newVal);
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.
DisconnectCode
Contains the RFC 4253 reason code from the most recent SSH DISCONNECT message received from the server. A value of 0 means no server-provided disconnect code is available.
See DisconnectReason for the server-provided descriptive text.
DisconnectReason
Contains the descriptive text sent with the most recent server SSH DISCONNECT message. See DisconnectCode for the corresponding RFC 4253 reason code.
The text is supplied by the server and can be empty or generic. An ordinary TCP loss or a local disconnect does not necessarily produce an SSH disconnect reason.
topEnableCache
void put_EnableCache(bool newVal);
Controls whether Chilkat caches remote file sizes and attributes requested by GetFileSize32, GetFileSize64, GetFileSizeStr, GetFileCreateTimeStr, GetFileLastAccessStr, GetFileLastModifiedStr, GetFileOwner, GetFileGroup, GetFilePermissions. The default is false.
When enabled, requesting one attribute by filename causes the complete attribute set for that file to be cached. Later attribute requests for the same filename can be satisfied without another server round trip.
ClearCache when remote metadata may have changed.EnableCompression
void put_EnableCompression(bool newVal);
Controls whether SSH compression may be negotiated. The default is false.
false.EnableSecrets
void put_EnableSecrets(bool newVal);
Enables automatic resolution of secret specification strings from secure operating-system storage. The default is false.
When true, supported password properties and authentication methods may receive a value beginning with !! instead of a literal credential. Chilkat resolves the secret from Windows Credential Manager on Windows or Apple Keychain on macOS.
Secret specification format:
!![appName|]service[|domain]|username
This feature applies to HttpProxyPassword, SocksPassword, AuthenticatePw, and AuthenticatePwPk.
FilenameCharset
const char *filenameCharset(void);
void put_FilenameCharset(const char *newVal);
Specifies the character encoding used for SFTP filenames. During InitializeSftp, Chilkat automatically sets this property when the server supplies a filename-charset extension.
When the property is empty, incoming and outgoing filenames use UTF-8. Otherwise, Chilkat uses the specified charset, such as utf-8, iso-8859-1, or windows-1252.
ForceCipher
const char *forceCipher(void);
void put_ForceCipher(const char *newVal);
Restricts SSH cipher negotiation to a single cipher. Leave this property empty to use Chilkat's normal preference order. For broader algorithm control, use SetAllowedAlgorithms.
Connect fails.ForceV3
void put_ForceV3(bool newVal);
Controls SFTP protocol-version negotiation. The default is true, which forces use of SFTP v3 even when the server supports a newer version.
Set this property to false before InitializeSftp when the application needs features introduced in SFTP v4, v5, or v6. After initialization, read ProtocolVersion to determine the negotiated version.
HeartbeatMs
void put_HeartbeatMs(int newVal);
Specifies the interval, in milliseconds, between AbortCheck event callbacks during operations that support progress events. The default is 0, which disables periodic callbacks.
HostKeyAlg
const char *hostKeyAlg(void);
void put_HostKeyAlg(const char *newVal);
Specifies the preferred host-key algorithm used during SSH connection establishment. The default is DSS; set it to RSA only when required for compatibility with a particular server.
HostKeyFingerprint
Contains the connected server's host-key fingerprint in Chilkat's legacy MD5 format. The value is set after a successful SSH connection.
ssh-rsa 2048 68:ff:d1:4e:6c:ff:d7:b0:d6:58:73:85:07:bc:2e:d5 ssh-ed25519 256 c8:73:22:c7:82:aa:09:f1:1c:4e:99:8a:a0:62:a7:87
GetHostKeyFP with SHA256. Compare the fingerprint with a value obtained from a trusted source before sending credentials.Disconnect. Obtain and validate it while the SSH connection is active.HttpProxyAuthMethod
const char *httpProxyAuthMethod(void);
void put_HttpProxyAuthMethod(const char *newVal);
Specifies the authentication method used by an HTTP proxy. Matching is case-insensitive.
topHttpProxyDomain
const char *httpProxyDomain(void);
void put_HttpProxyDomain(const char *newVal);
Specifies the optional Windows domain used for NTLM authentication with an HTTP proxy. This property is ignored for Basic authentication.
topHttpProxyHostname
const char *httpProxyHostname(void);
void put_HttpProxyHostname(const char *newVal);
Specifies the hostname or numeric IP address of an HTTP proxy used to establish the SSH connection.
Set this property together with HttpProxyPort. A configured SOCKS proxy takes precedence when SocksVersion is 4 or 5.
HttpProxyPassword
const char *httpProxyPassword(void);
void put_HttpProxyPassword(const char *newVal);
Specifies the password used to authenticate with an HTTP proxy.
topHttpProxyPort
void put_HttpProxyPort(int newVal);
Specifies the HTTP proxy port. Common values include 8080 and 3128.
The proxy is used when HttpProxyHostname is nonempty, this property is nonzero, and SocksVersion is 0.
HttpProxyUsername
const char *httpProxyUsername(void);
void put_HttpProxyUsername(const char *newVal);
Specifies the username used to authenticate with an HTTP proxy.
topIdleTimeoutMs
void put_IdleTimeoutMs(int newVal);
Specifies the maximum period, in milliseconds, during which an SFTP operation may make no progress while sending or receiving data. The default is 30000 (30 seconds).
Set this property to 0 to allow an operation to wait indefinitely.
IncludeDotDirs
void put_IncludeDotDirs(bool newVal);
Controls whether ReadDir and ReadDirListing include the special . and .. directory entries. The default is false.
. and ... It does not exclude ordinary hidden filenames such as .gitignore or .profile.InitializeFailCode
Contains the RFC 4254 channel-open failure code when InitializeSftp cannot open the SFTP session channel. The initial value is 0.
InitializeFailReason
Contains the descriptive text associated with InitializeFailCode when InitializeSftp cannot open the SFTP session channel. The text is supplied by the server and may be empty or generic.
IsConnected
Returns true when Chilkat's last known state indicates that the underlying SSH transport is connected. This means Connect succeeded; it does not mean authentication or InitializeSftp has completed.
This property is passive and does not perform network I/O. A silent network failure or a peer close may remain undetected until an operation reads from or writes to the socket.
SendIgnore and check its return value. The server does not reply to an SSH IGNORE message.KeepSessionLog
void put_KeepSessionLog(bool newVal);
Controls whether SSH and SFTP protocol traffic is accumulated in SessionLog. The default is false.
LastErrorHtml
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.
topLastErrorText
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.
LastErrorXml
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.
topLastMethodSuccess
void put_LastMethodSuccess(bool newVal);
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.
LastStatusCode
Contains the numeric code from the most recently received SFTP SSH_FXP_STATUS response. This is not necessarily the status of the most recently called method. Methods that return a handle, attributes, or data can complete without receiving a new status response, leaving an older value unchanged. A successful method can therefore leave a previous nonzero status code in this property.
See LastStatusMessage for the server-provided message text.
LastStatusMessage
Contains the message text from the most recently received SFTP SSH_FXP_STATUS response. The wording is server-dependent.
This property can remain unchanged across later successful methods that do not receive a new status response. See LastStatusCode for the numeric code.
MaxPacketSize
void put_MaxPacketSize(int newVal);
Specifies the maximum packet length used by the underlying SSH transport. The default is 32768 bytes.
PasswordChangeRequested
Indicates that the server rejected password authentication because the account password must be changed. This property is set by AuthenticatePw and AuthenticatePwPk.
When true, call the authentication method again and pass the old and new passwords in this form:
|oldPassword|newPassword|top
PercentDoneScale
void put_PercentDoneScale(int newVal);
Specifies the value representing 100% completion in PercentDone event callbacks. The default is 100.
For example, a scale of 1000 provides 0.1% granularity, so a callback value of 453 represents 45.3% complete. Values are clamped to the range 10 through 100000.
PreferIpv6
void put_PreferIpv6(bool newVal);
Controls the preferred address family when DNS resolution returns both IPv4 and IPv6 addresses. The default is false, which prefers IPv4. Set it to true to prefer IPv6.
PreserveDate
void put_PreserveDate(bool newVal);
Controls whether path-based upload and download methods preserve source timestamps on the destination. The default is false.
Last-modified time is preserved when supported by the negotiated SFTP version and destination filesystem. SFTP v3 represents these times with whole-second precision and does not provide a creation-time attribute; creation-time preservation requires a later protocol version and server support.
ProtocolVersion
Contains the SFTP protocol version negotiated by InitializeSftp, normally a value from 3 through 6.
Chilkat and the server exchange their highest supported versions, and the session uses the lower compatible version. Features unavailable in older versions are identified throughout this reference documentation.
0. After a successful initialization, the negotiated value can remain populated after Disconnect and during a later connection before SFTP is initialized again. Do not use this property alone to determine whether an SFTP channel is currently open.ReadDirMustMatch
const char *readDirMustMatch(void);
void put_ReadDirMustMatch(const char *newVal);
Specifies a semicolon-separated list of filename patterns. When nonempty, ReadDir and ReadDirListing include only entries matching at least one pattern.
*matches zero or more characters.- Matching is case-insensitive.
?and bracket expressions such as[0-9]are not wildcard operators.- Surrounding whitespace and empty entries between semicolons are ignored.
*.xml; *.txt; *.csvtop
ReadDirMustNotMatch
const char *readDirMustNotMatch(void);
void put_ReadDirMustNotMatch(const char *newVal);
Specifies a semicolon-separated list of filename patterns. When nonempty, ReadDir and ReadDirListing exclude entries matching any pattern. Exclusion is applied after ReadDirMustMatch.
*matches zero or more characters.- Matching is case-insensitive.
?and bracket expressions such as[0-9]are not wildcard operators.- Surrounding whitespace and empty entries between semicolons are ignored.
*.tmp; *.bak; *.logtop
ServerIdentifier
Contains the SSH server-identification string received during connection establishment. For example:
SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.16
Disconnect. Use IsConnected to determine whether the SSH transport is currently connected.SessionLog
Contains the in-memory SSH/SFTP protocol log. Enable logging by setting KeepSessionLog to true.
ClearSessionLog to clear it.SocksHostname
const char *socksHostname(void);
void put_SocksHostname(const char *newVal);
Specifies the SOCKS proxy hostname or IPv4 address. This property is used only when SocksVersion is 4 or 5.
SocksPassword
const char *socksPassword(void);
void put_SocksPassword(const char *newVal);
Specifies the SOCKS5 password when username/password authentication is required. SOCKS4 does not use a password, so this property is ignored when SocksVersion is 4.
SocksPort
void put_SocksPort(int newVal);
Specifies the SOCKS proxy port. The default is 1080. This property is used only when SocksVersion is 4 or 5.
SocksUsername
const char *socksUsername(void);
void put_SocksUsername(const char *newVal);
Specifies the SOCKS proxy username. For SOCKS4 it is sent as the user ID; for SOCKS5 it is used with SocksPassword for username/password authentication.
SocksVersion
void put_SocksVersion(int newVal);
Selects whether and how a SOCKS proxy is used.
topSoRcvBuf
void put_SoRcvBuf(int newVal);
Specifies the socket receive-buffer size. The default is 4194304 bytes. Normally this property should remain unchanged.
When download throughput is unexpectedly low, testing a larger value may help. Values should generally be multiples of 4096.
SoSndBuf
void put_SoSndBuf(int newVal);
Specifies the socket send-buffer size. The default is 262144 bytes. Normally this property should remain unchanged.
When upload throughput is unexpectedly low, testing values such as 524288 or 1048576 may help. Values should generally be multiples of 4096.
SyncCreateAllLocalDirs
void put_SyncCreateAllLocalDirs(bool newVal);
Controls whether SyncTreeDownload creates empty remote directories locally. The default is true.
When false, a local directory is created only when it is needed to contain a downloaded file.
true, an empty remote directory is created locally even when no file beneath it is downloaded.SyncDirectives
const char *syncDirectives(void);
void put_SyncDirectives(const char *newVal);
Specifies comma-separated directives that modify SyncTreeUpload or SyncTreeDownload. The default is an empty string.
SyncMustMatch
const char *syncMustMatch(void);
void put_SyncMustMatch(const char *newVal);
Specifies a semicolon-separated list of wildcard filename patterns. SyncTreeUpload and SyncTreeDownload transfer only files matching at least one pattern.
This filter applies to filenames, not directory names encountered while recursively traversing a tree.
*.xml;*.txt;*.csv
* to match zero or more characters. Separate multiple patterns with semicolons.SyncMustMatchDir
const char *syncMustMatchDir(void);
void put_SyncMustMatchDir(const char *newVal);
Specifies a semicolon-separated list of wildcard directory-name patterns. SyncTreeUpload and SyncTreeDownload enter only directories matching at least one pattern.
xml;txt;data_*
* to match zero or more characters. Separate multiple patterns with semicolons.SyncMustNotMatch
const char *syncMustNotMatch(void);
void put_SyncMustNotMatch(const char *newVal);
Specifies a semicolon-separated list of wildcard filename patterns. SyncTreeUpload and SyncTreeDownload skip files matching any pattern.
This filter applies to filenames, not directory names encountered while recursively traversing a tree.
*.tmp;*.bak;*.log
* to match zero or more characters. Separate multiple patterns with semicolons.SyncMustNotMatchDir
const char *syncMustNotMatchDir(void);
void put_SyncMustNotMatchDir(const char *newVal);
Specifies a semicolon-separated list of wildcard directory-name patterns. SyncTreeUpload and SyncTreeDownload skip directories matching any pattern.
temp;cache;archive_*
* to match zero or more characters. Separate multiple patterns with semicolons.TcpNoDelay
void put_TcpNoDelay(bool newVal);
Controls the TCP_NODELAY socket option. The default is false. Set it to true to disable the Nagle algorithm and reduce delays when many small packets are sent.
UncommonOptions
const char *uncommonOptions(void);
void put_UncommonOptions(const char *newVal);
Provides comma-separated compatibility, security, and synchronization options for uncommon scenarios. The default is an empty string and is appropriate for most applications.
topUploadChunkSize
void put_UploadChunkSize(int newVal);
Specifies the chunk size, in bytes, used by UploadFile and UploadFileByName. The default is 32000.
4096. Smaller chunks can reduce throughput.UserAuthBanner
const char *userAuthBanner(void);
void put_UserAuthBanner(const char *newVal);
Contains a user-authentication banner received from the server. Check this property after StartKeyboardAuth or another authentication attempt and display it to the user when appropriate.
When no banner is available, the property returns an empty string.
topUtcMode
void put_UtcMode(bool newVal);
Controls the time zone used by date/time getters. When true, returned values are expressed in UTC. When false (the default), returned values are converted to the local time zone.
UtcMode =topfalse: Fri, 21 Nov 1997 09:55:06 -0600 UtcMode =true: Fri, 21 Nov 1997 15:55:06 GMT
Utf8
void put_Utf8(bool newVal);
When set to true, all const char * arguments and return values are interpreted as UTF-8 strings. When set to false, they are interpreted as ANSI strings.
In Chilkat v11.0.0 and later, the default value is true. Before v11.0.0, it was false.
VerboseLogging
void put_VerboseLogging(bool newVal);
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
XferByteCount
Contains the current transfer byte count for an upload or download in progress. An application can read this property while an asynchronous transfer is running.
For SyncTreeUpload and SyncTreeDownload, the value is cumulative across all files processed by the operation. Use XferByteCount64 when a 64-bit count is required.
XferByteCount64
Contains the current 64-bit transfer byte count for an upload or download in progress. An application can read this property while an asynchronous transfer is running.
For SyncTreeUpload and SyncTreeDownload, the value is cumulative across all files processed by the operation.
Methods
AuthenticatePk
Authenticates the connected SSH session using public-key authentication. username identifies the server account, and privateKey must contain the corresponding private key. The matching public key must already be authorized for that account on the server.
Returns true for success, false for failure.
AuthenticatePkAsync (1)
Creates an asynchronous task to call the AuthenticatePk method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
AuthenticatePw
Authenticates the connected SSH session using login and password.
1. Connect 2. AuthenticatePw or AuthenticatePk 3. InitializeSftp
If the server requests a password change, see PasswordChangeRequested. After a failure, inspect AuthFailReason and LastErrorText.
AuthFailReason value can remain populated.Returns true for success, false for failure.
AuthenticatePwAsync (1)
Creates an asynchronous task to call the AuthenticatePw method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
AuthenticatePwPk
Authenticates with a server that requires both a password and a private key. username identifies the account, password supplies the password, and privateKey supplies the private key.
AuthFailReason and LastErrorText.Returns true for success, false for failure.
AuthenticatePwPkAsync (1)
Creates an asynchronous task to call the AuthenticatePwPk method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
AuthenticateSecPw
Works like AuthenticatePw, but receives login and password in SecureString objects.
Returns true for success, false for failure.
AuthenticateSecPwAsync (1)
Creates an asynchronous task to call the AuthenticateSecPw method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
AuthenticateSecPwPk
Works like AuthenticatePwPk, but receives username and password in SecureString objects. privateKey supplies the private key.
Returns true for success, false for failure.
AuthenticateSecPwPkAsync (1)
Creates an asynchronous task to call the AuthenticateSecPwPk method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ClearCache
Clears the internal remote file-attribute cache used when EnableCache is true.
ClearSessionLog
CloseHandle
Closes the remote file or directory handle specified by handle. The handle must have been returned by OpenFile or OpenDir.
false. A handle must never be reused after disconnecting or replacing the connection.Returns true for success, false for failure.
CloseHandleAsync (1)
Creates an asynchronous task to call the CloseHandle method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
Connect
Establishes an SSH connection to domainName on TCP port port. The host may be a DNS name or numeric IPv4 or IPv6 address; SSH servers commonly listen on port 22.
InitializeSftp.1. Connect 2. AuthenticatePw, AuthenticatePk, or another authentication method 3. InitializeSftp 4. Perform SFTP operations
Supported negotiation algorithms include:
Connect replaces the existing SSH connection. The previous SFTP subsystem and all handles from it are no longer usable. Authenticate and call InitializeSftp for the new connection.Returns true for success, false for failure.
ConnectAsync (1)
Creates an asynchronous task to call the Connect method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ConnectThroughSsh
Connects to hostname on port through the already connected and authenticated Ssh object in sshConn.
application → first SSH server → destination SSH/SFTP server
After this method succeeds, authenticate separately with the destination server and call InitializeSftp. All destination traffic is carried through the first SSH connection.
Returns true for success, false for failure.
ConnectThroughSshAsync (1)
Creates an asynchronous task to call the ConnectThroughSsh method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ContinueKeyboardAuth
const char *continueKeyboardAuth(const char *response);
Continues keyboard-interactive authentication by submitting response for the prompts returned by StartKeyboardAuth.
For a single prompt, pass the response text directly. For multiple prompts, pass XML in this form:
<response> <response1>response to first prompt</response1> <response2>response to second prompt</response2> ... </response>
The returned XML indicates authentication success, authentication failure, or another infoRequest containing additional prompts.
<success>success message</success> <error>error message</error>
Returns true for success, false for failure.
ContinueKeyboardAuthAsync (1)
Creates an asynchronous task to call the ContinueKeyboardAuth method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
CopyFileAttr
Copies supported timestamps and attributes from the local file at localFilename to the remote item identified by remoteFilename.
Set isHandle to true when remoteFilename contains an open SFTP handle; otherwise set it to false for a remote path.
Returns true for success, false for failure.
CopyFileAttrAsync (1)
Creates an asynchronous task to call the CopyFileAttr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
CreateDir
Creates the remote directory specified by path. Parent directories are not necessarily created automatically.
Returns true for success, false for failure.
CreateDirAsync (1)
Creates an asynchronous task to call the CreateDir method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
Disconnect
Closes the current SSH/SFTP connection. All remote file and directory handles from that session become invalid and must not be reused.
The object remains reusable. A later session must call Connect, authenticate again, and call InitializeSftp before performing SFTP operations.
DownloadBd
Downloads the remote file at remoteFilePath and appends its bytes to binData.
binData is preserved. Clear it first when replacement rather than append behavior is required.Returns true for success, false for failure.
DownloadBdAsync (1)
Creates an asynchronous task to call the DownloadBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
DownloadFile
Streams the remote file identified by handle to the local filesystem path toFilename. The handle must have been returned by OpenFile.
The transfer is streamed and is not limited by available memory. Close the remote handle when the download is complete.
0. It does not begin at the handle's current sequential read position.Returns true for success, false for failure.
DownloadFileAsync (1)
Creates an asynchronous task to call the DownloadFile method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
DownloadFileByName
Downloads the remote file at remoteFilePath to the local filesystem path localFilePath.
When PreserveDate is true, Chilkat preserves the remote file's last-modified time.
/ and is relative to the server filesystem root. A relative path is interpreted relative to the authenticated user's home directory.Returns true for success, false for failure.
DownloadFileByNameAsync (1)
Creates an asynchronous task to call the DownloadFileByName method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
DownloadSb
Downloads the remote file at remoteFilePath, decodes it using charset, and appends the text to sb.
sb is preserved. Clear it first when replacement rather than append behavior is required.Returns true for success, false for failure.
DownloadSbAsync (1)
Creates an asynchronous task to call the DownloadSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
Eof
Returns true when the most recent read for handle received the SFTP end-of-file status.
Reading exactly through the final byte does not set EOF immediately. The next read returns successfully with zero bytes, sets LastStatusCode to SSH_FX_EOF, and causes this method to return true.
true. Use LastReadFailed and the read method's result to distinguish a normal EOF from a handle or read failure.FileExists
Checks the remote item at remotePath. When followLinks is true, a symbolic link is followed and the target type is returned.
followLinks = false returns 3 for the link itself, while followLinks = true returns 0 because the target does not exist.FileExistsAsync (1)
Creates an asynchronous task to call the FileExists method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
Fsync
Requests that the server flush pending data for the open file identified by handle to stable storage.
fsync@openssh.com extension and succeeds only when the server supports that extension.Returns true for success, false for failure.
FsyncAsync (1)
Creates an asynchronous task to call the Fsync method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileCreateTimeStr
const char *getFileCreateTimeStr(const char *pathOrHandle, bool bFollowLinks, bool bIsHandle);
Returns the remote file's creation date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
The result is an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.
Returns true for success, false for failure.
GetFileCreateTimeStrAsync (1)
Creates an asynchronous task to call the GetFileCreateTimeStr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileGroup
const char *getFileGroup(const char *pathOrHandle, bool bFollowLinks, bool bIsHandle);
Returns the remote file's group ownership. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
Returns true for success, false for failure.
GetFileGroupAsync (1)
Creates an asynchronous task to call the GetFileGroup method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileLastAccessStr
const char *getFileLastAccessStr(const char *pathOrHandle, bool bFollowLinks, bool bIsHandle);
Returns the remote file's last-access date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
The result is an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.
Returns true for success, false for failure.
GetFileLastAccessStrAsync (1)
Creates an asynchronous task to call the GetFileLastAccessStr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileLastModifiedStr
const char *getFileLastModifiedStr(const char *pathOrHandle, bool bFollowLinks, bool bIsHandle);
Returns the remote file's last-modified date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
The result is an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.
Returns true for success, false for failure.
GetFileLastModifiedStrAsync (1)
Creates an asynchronous task to call the GetFileLastModifiedStr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileOwner
const char *getFileOwner(const char *pathOrHandle, bool bFollowLinks, bool bIsHandle);
Returns the remote file's owner. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
Returns true for success, false for failure.
GetFileOwnerAsync (1)
Creates an asynchronous task to call the GetFileOwner method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFilePermissions
Returns the remote item's complete POSIX mode value. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path. When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
The returned integer includes both the file-type bits and permission bits. For example:
Regular file, mode 0664: octal 0100664, decimal 33204 Regular file, mode 0600: octal 0100600, decimal 33152 Regular file, mode 0644: octal 0100644, decimal 33188
Mask with octal 07777 to obtain permission and special bits, or 0777 for only the traditional owner/group/other read, write, and execute bits. See SetPermissions to change the permissions.
GetFilePermissionsAsync (1)
Creates an asynchronous task to call the GetFilePermissions method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileSize32
Returns the remote file's size in bytes as a 32-bit integer. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
-1 when the size cannot be represented as a 32-bit integer. Use GetFileSize64 or GetFileSizeStr for large files.GetFileSize32Async (1)
Creates an asynchronous task to call the GetFileSize32 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileSize64
Returns the remote file's size in bytes as a 64-bit integer. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
GetFileSize64Async (1)
Creates an asynchronous task to call the GetFileSize64 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileSizeStr
const char *getFileSizeStr(const char *pathOrHandle, bool bFollowLinks, bool bIsHandle);
Returns the remote file's size in bytes as a decimal string. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
Returns true for success, false for failure.
GetFileSizeStrAsync (1)
Creates an asynchronous task to call the GetFileSizeStr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetHostKeyFP
const char *getHostKeyFP(const char *hashAlg, bool includeKeyType, bool includeHashName);
Returns the connected server's host-key fingerprint using hashAlg. Common choices include SHA256, SHA384, SHA512, SHA1, and MD5.
Returns true for success, false for failure.
GetLastJsonData
Populates json with supplemental details produced by the most recent method when such details are available. Many methods do not produce additional JSON information.
GetSyncedFiles
Appends to strTab the relative paths processed by the most recent SyncTreeUpload or SyncTreeDownload operation.
For downloads, entries can include local directories that were created. Directory paths end with / so they can be distinguished from file paths.
strTab are preserved.strTab first when only the latest synchronization results are wanted. Downloaded directory entries are reported with a trailing /; uploaded directory entries are reported without one.HardLink
Creates a hard link from newPath to the existing remote file at oldPath.
hardlink@openssh.com extension and succeeds only when the server supports that extension.Returns true for success, false for failure.
HardLinkAsync (1)
Creates an asynchronous task to call the HardLink method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
InitializeSftp
Opens the SFTP subsystem and negotiates the SFTP protocol version. Call this method after connecting and authenticating.
1. Connect 2. AuthenticatePw, AuthenticatePk, or another authentication method 3. InitializeSftp
After success, read ProtocolVersion to determine the negotiated SFTP version.
InitializeFailCode, InitializeFailReason, and LastErrorText.false. After disconnecting or replacing the connection, authenticate the new connection and call this method again.Returns true for success, false for failure.
InitializeSftpAsync (1)
Creates an asynchronous task to call the InitializeSftp method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
LastReadFailed
Returns true if the most recent read associated with handle failed; otherwise returns false.
A normal end-of-file is not a read failure: the EOF read succeeds, returns zero bytes, and this method returns false. For an empty, malformed, or already-closed handle, this method returns true.
LastReadNumBytes
Returns the number of bytes received by the most recent read associated with handle.
The initial value for a newly opened handle is 0. A normal EOF read and a failed read report 0.
LoadTaskCaller
Loads this object from the caller state associated with the completed asynchronous task.
Returns true for success, false for failure.
topOpenDir
Opens the remote directory specified by path and returns a handle for reading its entries.
handle = OpenDir(path) ReadDirListing(handle, dirObj) CloseHandle(handle)
Remote paths use / as the separator. A path beginning with / is absolute; a relative path is interpreted relative to the authenticated user's home directory. An empty path refers to that default directory.
Returns true for success, false for failure.
OpenDirAsync (1)
Creates an asynchronous task to call the OpenDir method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
OpenFile
const char *openFile(const char *remotePath, const char *access, const char *createDisposition);
Opens or creates the remote file at remotePath and returns a handle for subsequent read or write operations. Close the handle with CloseHandle when finished.
access must be readOnly, writeOnly, or readWrite.
createDisposition is a comma-separated list. It must contain exactly one primary disposition:
Additional optional keywords are:
ForceV3 to be false and a negotiated ProtocolVersion of at least 5./. A relative path is interpreted from the authenticated user's home directory. Some servers require a filename in the home directory to be written as ./filename.appendData forces writes to the end of the file, including explicit-offset writes. By itself it opens an existing file but does not create a missing file; combine it with an appropriate primary disposition when creation is required. Options defined for SFTP v5 or later must not be assumed to take effect when an older version is negotiated, even if the open request succeeds.Returns true for success, false for failure.
OpenFileAsync (1)
Creates an asynchronous task to call the OpenFile method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadDirListing
Reads all remaining directory entries from handle, which must have been returned by OpenDir, and stores them in dirObj. Entries are returned in server order; Chilkat does not sort the listing.
After end-of-directory has been reached, another call on the same handle returns true, adds no entries, and sets LastStatusCode to SSH_FX_EOF.
dirObj. Use a new or cleared SFtpDir object when an empty result must replace an earlier listing. Close the directory handle when finished.Returns true for success, false for failure.
ReadDirListingAsync (1)
Creates an asynchronous task to call the ReadDirListing method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileBd
Reads up to numBytes bytes from the current position of the remote file identified by handle and appends them to bd. The handle must have been returned by OpenFile.
Fewer bytes can be read when end-of-file is reached. Repeat the call until Eof(handle) returns true to read the entire file incrementally.
ReadFileBytes and ReadFileText. Existing bytes in bd are preserved.ReadFileBdAsync (1)
Creates an asynchronous task to call the ReadFileBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileText
const char *readFileText(const char *handle, int numBytes, const char *charset);
Reads up to numBytes bytes from the current position of handle, decodes the bytes using charset, and returns the resulting text.
See Supported Charsets.
numBytes ends in the middle of a UTF-8 sequence, the first returned string ends with the incomplete bytes and the next call begins with the remaining bytes. Choose byte counts that end on character boundaries, or read bytes and perform streaming decoding in the application.Returns true for success, false for failure.
ReadFileTextAsync (1)
Creates an asynchronous task to call the ReadFileText method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileText32
const char *readFileText32(const char *handle, int offset, int numBytes, const char *charset);
Reads up to numBytes bytes from handle at the 32-bit byte offset, decodes the bytes using charset, and returns the resulting text.
See Supported Charsets.
Returns true for success, false for failure.
ReadFileText32Async (1)
Creates an asynchronous task to call the ReadFileText32 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileText64
const char *readFileText64(const char *handle, __int64 offset, int numBytes, const char *charset);
Reads up to numBytes bytes from handle at the 64-bit byte offset, decodes the bytes using charset, and returns the resulting text.
See Supported Charsets.
Returns true for success, false for failure.
ReadFileText64Async (1)
Creates an asynchronous task to call the ReadFileText64 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileText64s
const char *readFileText64s(const char *handle, const char *offset, int numBytes, const char *charset);
Reads up to numBytes bytes from handle at the byte offset supplied as decimal string offset, decodes the bytes using charset, and returns the resulting text.
See Supported Charsets.
Returns true for success, false for failure.
ReadFileText64sAsync (1)
Creates an asynchronous task to call the ReadFileText64s method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadLink
Returns the target path stored in the symbolic link at remote path.
Returns true for success, false for failure.
ReadLinkAsync (1)
Creates an asynchronous task to call the ReadLink method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
RealPath
const char *realPath(const char *originalPath, const char *composePath);
Asks the server to canonicalize originalPath and returns the resulting absolute remote path.
For SFTP v5 or later, composePath may optionally modify or extend the original path; pass an empty string when no composition is needed. If composePath is absolute, it replaces originalPath.
composePath is ignored and the method canonicalizes only originalPath.Returns true for success, false for failure.
RealPathAsync (1)
Creates an asynchronous task to call the RealPath method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
RemoveDir
Deletes the remote directory specified by path.
Returns true for success, false for failure.
RemoveDirAsync (1)
Creates an asynchronous task to call the RemoveDir method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
RemoveFile
Deletes the remote file specified by filename.
Returns true for success, false for failure.
RemoveFileAsync (1)
Creates an asynchronous task to call the RemoveFile method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
RenameFileOrDir
Renames or moves a remote file or directory from oldPath to newPath.
oldPath: someDirA/filename newPath: someDirB/abc/xyz/filename
Returns true for success, false for failure.
RenameFileOrDirAsync (1)
Creates an asynchronous task to call the RenameFileOrDir method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ResumeDownloadFileByName
Resumes downloading remoteFilePath to the local filesystem path localFilePath. Chilkat uses only the existing local file size as the remote starting offset.
- If the local file is missing or empty, a normal download is performed.
- If it is smaller, the remaining remote bytes are appended after the existing local length.
- If it is the same size or larger, the method treats the download as complete and does not truncate or verify the local content.
Returns true for success, false for failure.
ResumeDownloadFileByNameAsync (1)
Creates an asynchronous task to call the ResumeDownloadFileByName method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ResumeUploadFileByName
Resumes uploading the local file at localFilePath to remoteFilePath. Chilkat uses only the existing remote file size as the local starting offset.
- If the remote file is missing or empty, a normal upload is performed.
- If it is smaller, the remaining local bytes are appended after the existing remote length.
- If it is the same size or larger, the method treats the upload as complete and does not truncate or verify the remote content.
Returns true for success, false for failure.
ResumeUploadFileByNameAsync (1)
Creates an asynchronous task to call the ResumeUploadFileByName method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SendIgnore
Sends an SSH IGNORE message. No SFTP file handle or channel is required.
The server does not send a reply, but a successful send helps verify that the SSH connection is still writable.
Returns true for success, false for failure.
SendIgnoreAsync (1)
Creates an asynchronous task to call the SendIgnore method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetAllowedAlgorithms
Configures the exact set of SSH algorithms permitted for subsequent connections using the settings in json.
Connect. The connection fails when no mutually supported algorithm remains in a required category.Returns true for success, false for failure.
SetCreateDt
Sets the remote file's creation date and time. pathOrHandle may contain a remote path or an open handle. Set isHandle to true for a handle and false for a path.
createDateTime supplies the new value.
Returns true for success, false for failure.
topSetCreateDtAsync (1)
Creates an asynchronous task to call the SetCreateDt method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetCreateTimeStr
Sets the remote file's creation date and time. pathOrHandle may contain a remote path or an open handle. Set bIsHandle to true for a handle and false for a path.
Pass the value in dateTimeStr as an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.
Returns true for success, false for failure.
SetCreateTimeStrAsync (1)
Creates an asynchronous task to call the SetCreateTimeStr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetLastAccessDt
Sets the remote file's last-access date and time. pathOrHandle may contain a remote path or an open handle. Set isHandle to true for a handle and false for a path.
accessDateTime supplies the new value.
Returns true for success, false for failure.
topSetLastAccessDtAsync (1)
Creates an asynchronous task to call the SetLastAccessDt method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetLastAccessTimeStr
Sets the remote file's last-access date and time. pathOrHandle may contain a remote path or an open handle. Set bIsHandle to true for a handle and false for a path.
Pass the value in dateTimeStr as an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.
Returns true for success, false for failure.
SetLastAccessTimeStrAsync (1)
Creates an asynchronous task to call the SetLastAccessTimeStr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetLastModifiedDt
Sets the remote file's last-modified date and time. pathOrHandle may contain a remote path or an open handle. Set isHandle to true for a handle and false for a path.
modifiedDateTime supplies the new value.
Returns true for success, false for failure.
topSetLastModifiedDtAsync (1)
Creates an asynchronous task to call the SetLastModifiedDt method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetLastModifiedTimeStr
Sets the remote file's last-modified date and time. pathOrHandle may contain a remote path or an open handle. Set bIsHandle to true for a handle and false for a path.
Pass the value in dateTimeStr as an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.
Returns true for success, false for failure.
SetLastModifiedTimeStrAsync (1)
Creates an asynchronous task to call the SetLastModifiedTimeStr method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetOwnerAndGroup
Sets the owner and group of the remote item identified by pathOrHandle. Set isHandle to true for an open handle and false for a remote path.
owner and group supply the new textual owner and group values.
Returns true for success, false for failure.
SetOwnerAndGroupAsync (1)
Creates an asynchronous task to call the SetOwnerAndGroup method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SetPermissions
Sets the POSIX permission bits for the remote item identified by pathOrHandle. Set isHandle to true for an open handle and false for a remote path.
Pass the permission bits, not the file-type bits. In languages supporting octal integer literals, common values include 0600, 0644, and 0755. Their decimal equivalents are 384, 420, and 493.
GetFilePermissions returns the complete mode, including the file-type bits. For example, setting 0644 on a regular file can subsequently return 0100644.Returns true for success, false for failure.
SetPermissionsAsync (1)
Creates an asynchronous task to call the SetPermissions method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
StartKeyboardAuth
const char *startKeyboardAuth(const char *login);
Begins keyboard-interactive authentication for login and returns XML describing the server's prompts.
<infoRequest numPrompts="N"> <name>name_string</name> <instruction>instruction_string</instruction> <prompt1 echo="1_or_0">prompt_string</prompt1> ... <promptN echo="1_or_0">prompt_string</promptN> </infoRequest>
The echo attribute indicates whether the response may be displayed while entered. A value of 0 normally identifies secret input such as a password.
If authentication immediately succeeds or fails, the result has one of these forms:
<success>success message</success> <error>error message</error>
Returns true for success, false for failure.
StartKeyboardAuthAsync (1)
Creates an asynchronous task to call the StartKeyboardAuth method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SymLink
Creates a symbolic link on the server. oldPath identifies the link target and newPath identifies the new symbolic-link path.
Returns true for success, false for failure.
SymLinkAsync (1)
Creates an asynchronous task to call the SymLink method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SyncTreeDownload
Synchronizes files from the remote directory remoteRoot to the local filesystem directory localRoot.
Set recurse to true to descend into subdirectories. An absolute remote path begins with /; a relative path is interpreted from the authenticated user's home directory.
Use GetSyncedFiles after the operation to retrieve the relative paths that were downloaded or created.
SyncCreateAllLocalDirs set to true, mode 0 creates empty remote directories locally. Mode 1 downloads only missing local files and preserves existing local files. Mode 99 deletes files from the remote tree that are absent locally; it does not delete extra local files.Returns true for success, false for failure.
SyncTreeDownloadAsync (1)
Creates an asynchronous task to call the SyncTreeDownload method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
SyncTreeUpload
Synchronizes files from the local filesystem directory localBaseDir to the remote directory remoteBaseDir.
Set bRecurse to true to descend into subdirectories. An absolute remote path begins with /; a relative path is interpreted from the authenticated user's home directory.
Use GetSyncedFiles after the operation to retrieve the relative paths that were uploaded.
0 also creates empty remote directories. Mode 1 uploads only missing files and does not replace an existing remote file merely because the local file is newer; use mode 2 for missing-or-newer behavior. The filename and directory filters are applied during recursive traversal.Returns true for success, false for failure.
SyncTreeUploadAsync (1)
Creates an asynchronous task to call the SyncTreeUpload method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
UploadBd
Uploads all bytes in binData to the remote file at remoteFilePath.
Returns true for success, false for failure.
UploadBdAsync (1)
Creates an asynchronous task to call the UploadBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
UploadFile
Streams the local filesystem file at fromLocalFilePath to the remote file identified by handle. The handle must have been returned by OpenFile.
Close the remote handle when the upload is complete.
Returns true for success, false for failure.
UploadFileAsync (1)
Creates an asynchronous task to call the UploadFile method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
UploadFileByName
Uploads the local filesystem file at localFilePath to remoteFilePath.
When PreserveDate is true, Chilkat preserves the local file's last-modified time on the remote file.
/ and is relative to the server filesystem root. A relative path is interpreted relative to the authenticated user's home directory.Returns true for success, false for failure.
UploadFileByNameAsync (1)
Creates an asynchronous task to call the UploadFileByName method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
UploadSb
Encodes the text in sb using charset and uploads it to remoteFilePath.
Set includeBom to true to prepend a byte-order mark when the selected encoding supports one.
utf-8, setting includeBom to true prepends the three bytes EF BB BF; setting it to false omits them.Returns true for success, false for failure.
UploadSbAsync (1)
Creates an asynchronous task to call the UploadSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileBd
Appends all bytes in bd to the remote file identified by handle. The handle must have been returned by OpenFile.
Returns true for success, false for failure.
WriteFileBdAsync (1)
Creates an asynchronous task to call the WriteFileBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileText
Encodes textData using charset and writes the resulting bytes at the current sequential write position for handle.
The position is maintained by Chilkat for the handle. Opening an existing file with openOrCreate positions sequential writes at the current end of the file. An explicit-offset write can change the position used by the next sequential write. When the file was opened with appendData, writes are forced to the end.
See Supported Charsets.
Returns true for success, false for failure.
WriteFileTextAsync (1)
Creates an asynchronous task to call the WriteFileText method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileText32
Encodes textData using charset and writes the resulting bytes to handle at the 32-bit byte offset offset32.
After a successful explicit-offset write, the next sequential write begins immediately after the bytes written by this call. If the file was opened with appendData, the server appends and the explicit offset does not control placement.
See Supported Charsets.
offset32 must be nonnegative. A negative value can be interpreted as a very large unsigned offset. Writing beyond end-of-file can create a sparse file; whether the gap is sparse is determined by the server filesystem.Returns true for success, false for failure.
WriteFileText32Async (1)
Creates an asynchronous task to call the WriteFileText32 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileText64
Encodes textData using charset and writes the resulting bytes to handle at the 64-bit byte offset offset64.
See Supported Charsets.
Returns true for success, false for failure.
WriteFileText64Async (1)
Creates an asynchronous task to call the WriteFileText64 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileText64s
Encodes textData using charset and writes the resulting bytes to handle at the byte offset supplied as decimal string offset64.
See Supported Charsets.
Returns true for success, false for failure.
WriteFileText64sAsync (1)
Creates an asynchronous task to call the WriteFileText64s method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
Events
To implement an event callback, your application would define and implement a class that inherits from CkSFtpProgress. Your application can implement methods to override some or all of the default/empty method implementations of the CkSFtpProgress base class.
For example:
CkSFtp sftp; MySFtpProgress callbackObj; sftp.put_EventCallbackObject(&callbackObj);
MySFtpProgress example:
#include "CkSFtpProgress.h"
class MySFtpProgress : public CkSFtpProgress {
public:
MySFtpProgress();
virtual ~MySFtpProgress();
void AbortCheck(bool *abort);
void DownloadRate(__int64 byteCount, unsigned long bytesPerSec);
void PercentDone(int pctDone, bool *abort);
void ProgressInfo(const char *name, const char *value);
void TaskCompleted(CkTask &task);
void UploadRate(__int64 byteCount, unsigned long bytesPerSec);
};AbortCheck
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.
PercentDone
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.
ProgressInfo
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.
TaskCompleted
Called from the background thread when an asynchronous task completes.
Deprecated
AccumulateBytes
Reads up to maxBytes bytes from the remote file identified by handle and appends them to AccumulateBuffer. The handle must have been returned by OpenFile.
Returns the number of bytes appended. Fewer bytes can be returned when end-of-file is reached. Returns -1 if an error occurs.
AccumulateBytesAsync (1)
Creates an asynchronous task to call the AccumulateBytes method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
Add64
const char *add64(const char *n1, const char *n2);
Adds two 64-bit integers supplied as decimal strings and returns the sum as a decimal string.
n1 and n2 are useful in environments that cannot represent 64-bit integer values directly.
Returns true for success, false for failure.
topClearAccumulateBuffer
Removes all bytes from AccumulateBuffer. Call this before starting a new sequence of AccumulateBytes operations.
GetFileCreateDt
GetFileCreateTimeStr instead.Returns the remote file's creation date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileCreateDtAsync (1) (2)
Creates an asynchronous task to call the GetFileCreateDt method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileLastAccessDt
GetFileLastAccessStr instead.Returns the remote file's last-access date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileLastAccessDtAsync (1) (2)
Creates an asynchronous task to call the GetFileLastAccessDt method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileLastModifiedDt
GetFileLastModifiedStr instead.Returns the remote file's last-modified date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to true for a handle and false for a path.
When bFollowLinks is true, the server follows a symbolic link and returns metadata for its target.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
GetFileLastModifiedDtAsync (1) (2)
Creates an asynchronous task to call the GetFileLastModifiedDt method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
LastJsonData
GetLastJsonData instead.Returns a JsonObject containing supplemental details produced by the most recent method when such details are available. Many methods do not produce additional JSON information.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadDir
ReadDirListing instead.Reads directory entries from the handle returned by OpenDir and returns an SFtpDir object containing the listing.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadDirAsync (1) (2)
Creates an asynchronous task to call the ReadDir method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileBytes Deprecated
Reads up to numBytes bytes from the current position of the remote file identified by handle. The handle must have been returned by OpenFile.
Fewer bytes can be returned when end-of-file is reached. To read the entire file incrementally, repeat the call until Eof(handle) returns true.
Returns true for success, false for failure.
topReadFileBytesAsync Deprecated (1)
Creates an asynchronous task to call the ReadFileBytes method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileBytes32 Deprecated
Reads up to numBytes bytes from handle, beginning at the 32-bit byte offset from the start of the file.
The offset is ignored when the file was opened with textMode. Use ReadFileBytes64 or ReadFileBytes64s for offsets outside the 32-bit range.
Returns true for success, false for failure.
topReadFileBytes32Async Deprecated (1)
Creates an asynchronous task to call the ReadFileBytes32 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileBytes64 Deprecated
Reads up to numBytes bytes from handle, beginning at the 64-bit byte offset from the start of the file.
The offset is ignored when the file was opened with textMode. Fewer bytes can be returned when end-of-file is reached.
Returns true for success, false for failure.
topReadFileBytes64Async Deprecated (1)
Creates an asynchronous task to call the ReadFileBytes64 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
ReadFileBytes64s Deprecated
Reads up to numBytes bytes from handle, beginning at the byte offset supplied as the decimal string offset.
This form is intended for environments without native 64-bit integer support. The offset is ignored when the file was opened with textMode.
Returns true for success, false for failure.
topReadFileBytes64sAsync Deprecated (1)
Creates an asynchronous task to call the ReadFileBytes64s method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileBytes Deprecated
Appends the exact bytes in byteData to the remote file identified by handle. The handle must have been returned by OpenFile.
Returns true for success, false for failure.
topWriteFileBytesAsync Deprecated (1)
Creates an asynchronous task to call the WriteFileBytes method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileBytes32 Deprecated
Writes the exact bytes in data to handle at the 32-bit byte offset from the beginning of the remote file.
Returns true for success, false for failure.
topWriteFileBytes32Async Deprecated (1)
Creates an asynchronous task to call the WriteFileBytes32 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileBytes64 Deprecated
Writes the exact bytes in data to handle at the 64-bit byte offset64 from the beginning of the remote file.
Returns true for success, false for failure.
topWriteFileBytes64Async Deprecated (1)
Creates an asynchronous task to call the WriteFileBytes64 method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure
WriteFileBytes64s Deprecated
Writes the exact bytes in data to handle at the byte offset supplied as the decimal string offset64.
Returns true for success, false for failure.
topWriteFileBytes64sAsync Deprecated (1)
Creates an asynchronous task to call the WriteFileBytes64s method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.
Returns NULL on failure