SFtp Zig Reference Documentation
SFtp
Current Version: 11.6.1
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
// Add the package once:
// zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz
// and in build.zig:
// const chilkat = b.dependency("chilkat", .{ .target = target, .optimize = optimize });
// exe.root_module.addImport("chilkat", chilkat.module("chilkat"));
const chilkat = @import("chilkat");
// Once per process, before any other Chilkat call:
try chilkat.unlockBundle("Anything for 30-day trial");
const s_ftp = try chilkat.SFtp.init();
defer s_ftp.deinit();Creates the underlying native Chilkat object. SFtp is a one-pointer struct passed by value; copying it copies the handle (two names for one object). Returns error.OutOfMemory if the library could not allocate the object. Use an object from one thread at a time; it may be handed from one thread to another.
Releases the native object. Call it exactly once per object (usually with defer); the handle is invalid afterwards. Objects returned by methods are owned by the caller too and are released the same way.
Wraps a handle obtained from the C API (chilkat.c.CkSFtp), taking ownership of it. The struct's handle field goes the other way, for anything the Zig API does not cover.
Errors and memory
Methods that can fail return an error union: a method whose only outcome is success or failure returns Error!void; a method producing a string returns (Error || Allocator.Error)![:0]u8; a method producing an object returns Error!T. chilkat.Error is error{ChilkatFailed}; the reason for a failure is in getLastErrorText, and the object remains usable. Properties never fail, and methods that answer a question (hasMember, isUnlocked, ...) return a plain bool.
String arguments are [:0]const u8 (UTF-8; string literals can be passed as is). String results are copies allocated with the allocator argument and owned by the caller, so they stay valid across later calls on the same object.
const text = s_ftp.someMethod(allocator, ...) catch |err| {
const why = try s_ftp.getLastErrorText(allocator);
defer allocator.free(why);
std.debug.print("{s}\n", .{why});
return err;
};
defer allocator.free(text);Properties
AbortCurrent
pub fn getAbortCurrent(self: SFtp) bool
pub fn setAbortCurrent(self: SFtp, value: bool) void
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
pub fn getAuthFailReason(self: SFtp) i32
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
pub fn getBandwidthThrottleDown(self: SFtp) i32
pub fn setBandwidthThrottleDown(self: SFtp, value: i32) void
Specifies the approximate maximum download rate, in bytes per second. The default is 0, which disables download throttling.
BandwidthThrottleUp
pub fn getBandwidthThrottleUp(self: SFtp) i32
pub fn setBandwidthThrottleUp(self: SFtp, value: i32) void
Specifies the approximate maximum upload rate, in bytes per second. The default is 0, which disables upload throttling.
ClientIdentifier
pub fn getClientIdentifier(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setClientIdentifier(self: SFtp, value: [:0]const u8) void
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
pub fn getClientIpAddress(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setClientIpAddress(self: SFtp, value: [:0]const u8) void
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
pub fn getConnectTimeoutMs(self: SFtp) i32
pub fn setConnectTimeoutMs(self: SFtp, value: i32) void
Specifies the maximum number of milliseconds allowed for the remote endpoint to accept the TCP connection.
IdleTimeoutMs and method-specific timeouts.DebugLogFilePath
pub fn getDebugLogFilePath(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setDebugLogFilePath(self: SFtp, value: [:0]const u8) void
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
pub fn getDisconnectCode(self: SFtp) i32
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
pub fn getDisconnectReason(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getEnableCache(self: SFtp) bool
pub fn setEnableCache(self: SFtp, value: bool) void
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
pub fn getEnableCompression(self: SFtp) bool
pub fn setEnableCompression(self: SFtp, value: bool) void
Controls whether SSH compression may be negotiated. The default is false.
false.EnableSecrets
pub fn getEnableSecrets(self: SFtp) bool
pub fn setEnableSecrets(self: SFtp, value: bool) void
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
pub fn getFilenameCharset(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setFilenameCharset(self: SFtp, value: [:0]const u8) void
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
pub fn getForceCipher(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setForceCipher(self: SFtp, value: [:0]const u8) void
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
pub fn getForceV3(self: SFtp) bool
pub fn setForceV3(self: SFtp, value: bool) void
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
pub fn getHeartbeatMs(self: SFtp) i32
pub fn setHeartbeatMs(self: SFtp, value: i32) void
Specifies the interval, in milliseconds, between AbortCheck event callbacks during operations that support progress events. The default is 0, which disables periodic callbacks.
HostKeyAlg
pub fn getHostKeyAlg(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setHostKeyAlg(self: SFtp, value: [:0]const u8) void
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
pub fn getHostKeyFingerprint(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getHttpProxyAuthMethod(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setHttpProxyAuthMethod(self: SFtp, value: [:0]const u8) void
Specifies the authentication method used by an HTTP proxy. Matching is case-insensitive.
topHttpProxyDomain
pub fn getHttpProxyDomain(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setHttpProxyDomain(self: SFtp, value: [:0]const u8) void
Specifies the optional Windows domain used for NTLM authentication with an HTTP proxy. This property is ignored for Basic authentication.
topHttpProxyHostname
pub fn getHttpProxyHostname(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setHttpProxyHostname(self: SFtp, value: [:0]const u8) void
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
pub fn getHttpProxyPassword(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setHttpProxyPassword(self: SFtp, value: [:0]const u8) void
Specifies the password used to authenticate with an HTTP proxy.
topHttpProxyPort
pub fn getHttpProxyPort(self: SFtp) i32
pub fn setHttpProxyPort(self: SFtp, value: i32) void
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
pub fn getHttpProxyUsername(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setHttpProxyUsername(self: SFtp, value: [:0]const u8) void
Specifies the username used to authenticate with an HTTP proxy.
topIdleTimeoutMs
pub fn getIdleTimeoutMs(self: SFtp) i32
pub fn setIdleTimeoutMs(self: SFtp, value: i32) void
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
pub fn getIncludeDotDirs(self: SFtp) bool
pub fn setIncludeDotDirs(self: SFtp, value: bool) void
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
pub fn getInitializeFailCode(self: SFtp) i32
Contains the RFC 4254 channel-open failure code when InitializeSftp cannot open the SFTP session channel. The initial value is 0.
InitializeFailReason
pub fn getInitializeFailReason(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getIsConnected(self: SFtp) bool
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
pub fn getKeepSessionLog(self: SFtp) bool
pub fn setKeepSessionLog(self: SFtp, value: bool) void
Controls whether SSH and SFTP protocol traffic is accumulated in SessionLog. The default is false.
LastErrorHtml
pub fn getLastErrorHtml(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getLastErrorText(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getLastErrorXml(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getLastMethodSuccess(self: SFtp) bool
pub fn setLastMethodSuccess(self: SFtp, value: bool) void
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
pub fn getLastStatusCode(self: SFtp) i32
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
pub fn getLastStatusMessage(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getMaxPacketSize(self: SFtp) i32
pub fn setMaxPacketSize(self: SFtp, value: i32) void
Specifies the maximum packet length used by the underlying SSH transport. The default is 32768 bytes.
PasswordChangeRequested
pub fn getPasswordChangeRequested(self: SFtp) bool
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
pub fn getPercentDoneScale(self: SFtp) i32
pub fn setPercentDoneScale(self: SFtp, value: i32) void
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
pub fn getPreferIpv6(self: SFtp) bool
pub fn setPreferIpv6(self: SFtp, value: bool) void
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
pub fn getPreserveDate(self: SFtp) bool
pub fn setPreserveDate(self: SFtp, value: bool) void
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
pub fn getProtocolVersion(self: SFtp) i32
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
pub fn getReadDirMustMatch(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setReadDirMustMatch(self: SFtp, value: [:0]const u8) void
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
pub fn getReadDirMustNotMatch(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setReadDirMustNotMatch(self: SFtp, value: [:0]const u8) void
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
pub fn getServerIdentifier(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
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
pub fn getSessionLog(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
Contains the in-memory SSH/SFTP protocol log. Enable logging by setting KeepSessionLog to true.
ClearSessionLog to clear it.SocksHostname
pub fn getSocksHostname(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSocksHostname(self: SFtp, value: [:0]const u8) void
Specifies the SOCKS proxy hostname or IPv4 address. This property is used only when SocksVersion is 4 or 5.
SocksPassword
pub fn getSocksPassword(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSocksPassword(self: SFtp, value: [:0]const u8) void
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
pub fn getSocksPort(self: SFtp) i32
pub fn setSocksPort(self: SFtp, value: i32) void
Specifies the SOCKS proxy port. The default is 1080. This property is used only when SocksVersion is 4 or 5.
SocksUsername
pub fn getSocksUsername(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSocksUsername(self: SFtp, value: [:0]const u8) void
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
pub fn getSocksVersion(self: SFtp) i32
pub fn setSocksVersion(self: SFtp, value: i32) void
Selects whether and how a SOCKS proxy is used.
topSoRcvBuf
pub fn getSoRcvBuf(self: SFtp) i32
pub fn setSoRcvBuf(self: SFtp, value: i32) void
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
pub fn getSoSndBuf(self: SFtp) i32
pub fn setSoSndBuf(self: SFtp, value: i32) void
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
pub fn getSyncCreateAllLocalDirs(self: SFtp) bool
pub fn setSyncCreateAllLocalDirs(self: SFtp, value: bool) void
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
pub fn getSyncDirectives(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSyncDirectives(self: SFtp, value: [:0]const u8) void
Specifies comma-separated directives that modify SyncTreeUpload or SyncTreeDownload. The default is an empty string.
SyncMustMatch
pub fn getSyncMustMatch(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSyncMustMatch(self: SFtp, value: [:0]const u8) void
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
pub fn getSyncMustMatchDir(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSyncMustMatchDir(self: SFtp, value: [:0]const u8) void
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
pub fn getSyncMustNotMatch(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSyncMustNotMatch(self: SFtp, value: [:0]const u8) void
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
pub fn getSyncMustNotMatchDir(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setSyncMustNotMatchDir(self: SFtp, value: [:0]const u8) void
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
pub fn getTcpNoDelay(self: SFtp) bool
pub fn setTcpNoDelay(self: SFtp, value: bool) void
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
pub fn getUncommonOptions(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setUncommonOptions(self: SFtp, value: [:0]const u8) void
Provides comma-separated compatibility, security, and synchronization options for uncommon scenarios. The default is an empty string and is appropriate for most applications.
topUploadChunkSize
pub fn getUploadChunkSize(self: SFtp) i32
pub fn setUploadChunkSize(self: SFtp, value: i32) void
Specifies the chunk size, in bytes, used by UploadFile and UploadFileByName. The default is 32000.
4096. Smaller chunks can reduce throughput.UserAuthBanner
pub fn getUserAuthBanner(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setUserAuthBanner(self: SFtp, value: [:0]const u8) void
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
pub fn getUtcMode(self: SFtp) bool
pub fn setUtcMode(self: SFtp, value: bool) void
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
VerboseLogging
pub fn getVerboseLogging(self: SFtp) bool
pub fn setVerboseLogging(self: SFtp, value: bool) void
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
pub fn getVersion(self: SFtp, allocator: Allocator) Allocator.Error![:0]u8
XferByteCount
pub fn getXferByteCount(self: SFtp) u32
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
pub fn getXferByteCount64(self: SFtp) i64
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
AuthenticateSecPw
Works like AuthenticatePw, but receives login and password in SecureString objects.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
AuthenticateSecPwPk
Works like AuthenticatePwPk, but receives username and password in SecureString objects. privateKey supplies the private key.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
ContinueKeyboardAuth
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
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 error.ChilkatFailed on failure; getLastErrorText explains why.
CreateDir
Creates the remote directory specified by path. Parent directories are not necessarily created automatically.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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.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 error.ChilkatFailed on failure; getLastErrorText explains why.
GetFileCreateTimeStr
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
GetFileGroup
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
GetFileLastAccessStr
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
GetFileLastModifiedStr
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
GetFileOwner
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
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.
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.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.
GetFileSizeStr
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
GetHostKeyFP
Returns the connected server's host-key fingerprint using hashAlg. Common choices include SHA256, SHA384, SHA512, SHA1, and MD5.
Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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.
OpenDir
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
OpenFile
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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.Returns error.ChilkatFailed on failure; getLastErrorText explains why.
ReadFileText
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
ReadFileText32
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
ReadFileText64
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
ReadFileText64s
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
ReadLink
Returns the target path stored in the symbolic link at remote path.
Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
RealPath
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
RemoveDir
Deletes the remote directory specified by path.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
RemoveFile
Deletes the remote file specified by filename.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
RenameFileOrDir
Renames or moves a remote file or directory from oldPath to newPath.
oldPath: someDirA/filename newPath: someDirB/abc/xyz/filename
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
StartKeyboardAuth
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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).
SymLink
Creates a symbolic link on the server. oldPath identifies the link target and newPath identifies the new symbolic-link path.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
UploadBd
Uploads all bytes in binData to the remote file at remoteFilePath.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
WriteFileBd
Appends all bytes in bd to the remote file identified by handle. The handle must have been returned by OpenFile.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
WriteFileText64
Encodes textData using charset and writes the resulting bytes to handle at the 64-bit byte offset offset64.
See Supported Charsets.
Returns error.ChilkatFailed on failure; getLastErrorText explains why.
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 error.ChilkatFailed on failure; getLastErrorText explains why.
Events
All Chilkat methods are synchronous: the call returns when the work is done. During a call, SFtp raises three events so your program can show progress and offer a way out. Declare any subset of abortCheck, percentDone and progressInfo in a struct of your own and install a pointer to it with setEventHandler:
const Progress = struct {
pub fn percentDone(_: *Progress, pct: i32) bool {
std.debug.print("{d}%\n", .{pct});
return false; // return true to abort the method in progress
}
pub fn progressInfo(_: *Progress, name: [:0]const u8, value: [:0]const u8) void {
std.debug.print("{s}: {s}\n", .{ name, value });
}
};
var progress = Progress{};
s_ftp.setEventHandler(&progress); // progress must outlive the installation
defer s_ftp.clearEventHandler();
s_ftp.setHeartbeatMs(250); // abortCheck 4 times per second during Chilkat callsInstalls handler, a pointer to any struct, as the receiver of this object's events, replacing any handler installed earlier. The dispatch is resolved at compile time: only the methods the struct declares are called, and a struct declaring none of the three is a compile error. The struct must stay alive, at the same address, until clearEventHandler or deinit.
Removes the handler; events are no longer delivered.
AbortCheck fires at regular intervals controlled by the HeartbeatMs property (0, the default, disables it); PercentDone fires when an operation's completion percentage is known; ProgressInfo delivers named progress values. Returning true from abortCheck or percentDone aborts the running method, which then returns error.ChilkatFailed.
Events fire on the thread that called the method, before that method returns. To abort a long operation from another thread, have abortCheck read a std.atomic.Value(bool), or set the object's AbortCurrent property.
AbortCheck
pub fn abortCheck(self: *T) bool
Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.
Example
const Abort = struct {
stop: std.atomic.Value(bool) = .init(false),
pub fn abortCheck(self: *Abort) bool {
return self.stop.load(.acquire); // another thread may call abort.stop.store(true, .release)
}
};
var abort = Abort{};
s_ftp.setHeartbeatMs(250); // call abortCheck 4 times per second
s_ftp.setEventHandler(&abort);
defer s_ftp.clearEventHandler();PercentDone
pub fn percentDone(self: *T, pct: i32) bool
This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pctDone argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pctDone equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).
The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.
To abort the operation, set the abort output argument to true. This will cause the method to terminate and return a failure status or corresponding failure value.
Example
const Progress = struct {
pub fn percentDone(_: *Progress, pct: i32) bool {
// pct ranges from 1 to 100.
std.debug.print("Percent done: {d}\n", .{pct});
return false; // return true to abort the method in progress
}
};
var progress = Progress{};
s_ftp.setEventHandler(&progress);
defer s_ftp.clearEventHandler();ProgressInfo
pub fn progressInfo(self: *T, name: [:0]const u8, value: [:0]const u8) void
This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.
Note: Some Chilkat methods don't fire any ProgressInfo events.
Example
const Info = struct {
pub fn progressInfo(_: *Info, name: [:0]const u8, value: [:0]const u8) void {
std.debug.print("{s}: {s}\n", .{ name, value });
}
};
var info = Info{};
s_ftp.setEventHandler(&info);
defer s_ftp.clearEventHandler();