CkSFtp

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.

Contains the result code from the most recent call to AuthenticatePw, AuthenticatePk, AuthenticatePwPk, or a corresponding secure-string authentication method.

Specifies the approximate maximum download rate, in bytes per second. The default is 0, which disables download throttling.

Specifies the approximate maximum upload rate, in bytes per second. The default is 0, which disables upload throttling.

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.

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.

Specifies the maximum number of milliseconds allowed for the remote endpoint to accept the TCP connection.

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.

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.

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.

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.

Controls whether SSH compression may be negotiated. The default is false.

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.

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.

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.

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.

Specifies the interval, in milliseconds, between AbortCheck event callbacks during operations that support progress events. The default is 0, which disables periodic callbacks.

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.

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

Specifies the authentication method used by an HTTP proxy. Matching is case-insensitive.

Specifies the optional Windows domain used for NTLM authentication with an HTTP proxy. This property is ignored for Basic authentication.

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.

Specifies the password used to authenticate with an HTTP proxy.

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.

Specifies the username used to authenticate with an HTTP proxy.

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.

Controls whether ReadDir and ReadDirListing include the special . and .. directory entries. The default is false.

Contains the RFC 4254 channel-open failure code when InitializeSftp cannot open the SFTP session channel. The initial value is 0.

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.

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.

Controls whether SSH and SFTP protocol traffic is accumulated in SessionLog. The default is false.

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

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.

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.

Specifies the maximum packet length used by the underlying SSH transport. The default is 32768 bytes.

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|

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.

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.

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.

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.

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; *.csv

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; *.log

Contains the SSH server-identification string received during connection establishment. For example:

SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.16

Contains the in-memory SSH/SFTP protocol log. Enable logging by setting KeepSessionLog to true.

Specifies the SOCKS proxy hostname or IPv4 address. This property is used only when SocksVersion is 4 or 5.

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.

Specifies the SOCKS proxy port. The default is 1080. This property is used only when SocksVersion is 4 or 5.

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.

Selects whether and how a SOCKS proxy is used.

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.

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.

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.

Specifies comma-separated directives that modify SyncTreeUpload or SyncTreeDownload. The default is an empty string.

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

Specifies a semicolon-separated list of wildcard directory-name patterns. SyncTreeUpload and SyncTreeDownload enter only directories matching at least one pattern.

xml;txt;data_*

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

Specifies a semicolon-separated list of wildcard directory-name patterns. SyncTreeUpload and SyncTreeDownload skip directories matching any pattern.

temp;cache;archive_*

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.

Provides comma-separated compatibility, security, and synchronization options for uncommon scenarios. The default is an empty string and is appropriate for most applications.

Specifies the chunk size, in bytes, used by UploadFile and UploadFileByName. The default is 32000.

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.

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 = false: Fri, 21 Nov 1997 09:55:06 -0600
UtcMode = true:  Fri, 21 Nov 1997 15:55:06 GMT

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

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

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.

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.

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.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

Works like AuthenticatePw, but receives login and password in SecureString objects.

Returns true for success, false for failure.

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.

Returns nil on failure

Works like AuthenticatePwPk, but receives username and password in SecureString objects. privateKey supplies the private key.

Returns true for success, false for failure.

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.

Returns nil on failure

Clears the internal remote file-attribute cache used when EnableCache is true.

Clears the in-memory text stored in SessionLog.

Closes the remote file or directory handle specified by handle. The handle must have been returned by OpenFile or OpenDir.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

1. Connect
2. AuthenticatePw, AuthenticatePk, or another authentication method
3. InitializeSftp
4. Perform SFTP operations

Supported negotiation algorithms include:

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

Creates the remote directory specified by path. Parent directories are not necessarily created automatically.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Downloads the remote file at remoteFilePath and appends its bytes to binData.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

Downloads the remote file at remoteFilePath, decodes it using charset, and appends the text to sb.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Checks the remote item at remotePath. When followLinks is true, a symbolic link is followed and the target type is returned.

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.

Returns nil on failure

Requests that the server flush pending data for the open file identified by handle to stable storage.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

Populates json with supplemental details produced by the most recent method when such details are available. Many methods do not produce additional JSON information.

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.

Creates a hard link from newPath to the existing remote file at oldPath.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Loads this object from the caller state associated with the completed asynchronous task.

Returns true for success, false for failure.

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.

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.

Returns nil on failure

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:

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

Reads up to numBytes bytes from the current position of handle, decodes the bytes using charset, and returns the resulting text.

See Supported Charsets.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

Returns the target path stored in the symbolic link at remote path.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

Deletes the remote directory specified by path.

Returns true for success, false for failure.

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.

Returns nil on failure

Deletes the remote file specified by filename.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

Configures the exact set of SSH algorithms permitted for subsequent connections using the settings in json.

Returns true for success, false for failure.

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

Uploads all bytes in binData to the remote file at remoteFilePath.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

Returns true for success, false for failure.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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. Return true to abort; return false to continue (not abort)

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.

Return true to abort; return false to continue (not abort)

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.

Called from the background thread when an asynchronous task completes.

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.

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.

Returns nil on failure

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.

Removes all bytes from AccumulateBuffer. Call this before starting a new sequence of AccumulateBytes operations.

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.

Returns nil on failure

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.

Returns nil on failure

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.

Returns nil on failure

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.

Returns nil on failure

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.

Returns nil on failure

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.

Returns nil on failure

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.

Returns nil on failure

Reads directory entries from the handle returned by OpenDir and returns an SFtpDir object containing the listing.

Returns nil on failure

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure

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.

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.

Returns nil on failure