Package com.chilkatsoft.chilkat2

Class SFtp

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.SFtp
All Implemented Interfaces:
AutoCloseable
public class SFtp extends ChilkatObject
<section class="sftp-summary">

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

Connect to an SSH server, authenticate with password or key-based credentials, then initialize the SFTP subsystem before file operations.

Upload and download

Transfer files using simple path-based APIs, in-memory data, streams, or handle-based methods when lower-level control is needed.

Directory and file management

List directories, create and remove folders, rename files, delete files, inspect attributes, and work with remote paths.

Sync-tree operations

Upload or download directory trees and synchronize local and remote folder structures.

Security controls

Verify host keys, control accepted SSH algorithms, use private keys, and configure proxy or network settings when required.

Diagnostics and reliability

Use detailed error text, session logs, progress callbacks, bandwidth limits, and timeout settings to troubleshoot real-world server behavior.

Common pattern: Connect, authenticate, initialize SFTP, perform file operations using remote paths or handles, close any open handles, and disconnect. Use handle-based APIs for precise control, and synchronization methods for recursive folder transfers.

For an extended overview, see SFtp Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • SFtp

      public SFtp()
      Creates a new SFtp object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      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.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

      public void setAbortCurrent​(boolean value)
      Sets the AbortCurrent property; see getAbortCurrent().
      Parameters:
      value - the new value

    • getAuthFailReason

      public int getAuthFailReason()
      Contains the result code from the most recent call to authenticatePw(String, String), authenticatePk(String, SshKey), authenticatePwPk(String, String, SshKey), or a corresponding secure-string authentication method.

      Value Meaning

      1 Transport failure: communication was lost, or a network read or write failed or timed out.

      2 Invalid private key: the key format, key type, or key contents are not suitable for public-key authentication.

      3 No mutually supported authentication method is available.

      4 SSH authentication protocol error: an unexpected or invalid message was received.

      5 The server rejected the supplied password or private key.

      6 The SSH session is already authenticated.

      7 The server requires a password change. See getPasswordChangeRequested().

      Read this property immediately after an authentication method fails. Also inspect LastErrorText for detailed diagnostics.Lifetime: A later successful authentication does not necessarily reset this value. Consult it only immediately after an authentication method returns false; do not use an older value to describe the current session.

      Returns:
      the value of the AuthFailReason property (read-only)

    • getBandwidthThrottleDown

      public int getBandwidthThrottleDown()
      Specifies the approximate maximum download rate, in bytes per second. The default is 0, which disables download throttling.

      Bandwidth throttling is approximate. Actual throughput can vary because of network latency, SSH framing, buffering, and server behavior.

      Returns:
      the value of the BandwidthThrottleDown property

    • setBandwidthThrottleDown

      public void setBandwidthThrottleDown​(int value)
      Sets the BandwidthThrottleDown property; see getBandwidthThrottleDown().
      Parameters:
      value - the new value

    • getBandwidthThrottleUp

      public int getBandwidthThrottleUp()
      Specifies the approximate maximum upload rate, in bytes per second. The default is 0, which disables upload throttling.

      Bandwidth throttling is approximate. Actual throughput can vary because of network latency, SSH framing, buffering, and server behavior.

      Returns:
      the value of the BandwidthThrottleUp property

    • setBandwidthThrottleUp

      public void setBandwidthThrottleUp​(int value)
      Sets the BandwidthThrottleUp property; see getBandwidthThrottleUp().
      Parameters:
      value - the new value

    • getClientIdentifier

      public String getClientIdentifier()
      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.

      The value should begin with SSH-2.0-. A server may disconnect if the identification string is invalid.

      Returns:
      the value of the ClientIdentifier property

    • setClientIdentifier

      public void setClientIdentifier​(String value)
      Sets the ClientIdentifier property; see getClientIdentifier().
      Parameters:
      value - the new value (not null)

    • getClientIpAddress

      public String getClientIpAddress()
      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.

      Returns:
      the value of the ClientIpAddress property

    • setClientIpAddress

      public void setClientIpAddress​(String value)
      Sets the ClientIpAddress property; see getClientIpAddress().
      Parameters:
      value - the new value (not null)

    • getConnectTimeoutMs

      public int getConnectTimeoutMs()
      Specifies the maximum number of milliseconds allowed for the remote endpoint to accept the TCP connection.

      This setting covers TCP connection establishment. After the socket is connected, receive and transfer inactivity are governed by getIdleTimeoutMs() and method-specific timeouts.

      Returns:
      the value of the ConnectTimeoutMs property

    • setConnectTimeoutMs

      public void setConnectTimeoutMs​(int value)
      Sets the ConnectTimeoutMs property; see getConnectTimeoutMs().
      Parameters:
      value - the new value

    • getDisconnectCode

      public int getDisconnectCode()
      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.

      Code Symbolic name

      1 SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT

      2 SSH_DISCONNECT_PROTOCOL_ERROR

      3 SSH_DISCONNECT_KEY_EXCHANGE_FAILED

      4 SSH_DISCONNECT_RESERVED

      5 SSH_DISCONNECT_MAC_ERROR

      6 SSH_DISCONNECT_COMPRESSION_ERROR

      7 SSH_DISCONNECT_SERVICE_NOT_AVAILABLE

      8 SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED

      9 SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE

      10 SSH_DISCONNECT_CONNECTION_LOST

      11 SSH_DISCONNECT_BY_APPLICATION

      12 SSH_DISCONNECT_TOO_MANY_CONNECTIONS

      13 SSH_DISCONNECT_AUTH_CANCELLED_BY_USER

      14 SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE

      15 SSH_DISCONNECT_ILLEGAL_USER_NAME

      See getDisconnectReason() for the server-provided descriptive text.

      Returns:
      the value of the DisconnectCode property (read-only)

    • getDisconnectReason

      public String getDisconnectReason()
      Contains the descriptive text sent with the most recent server SSH DISCONNECT message. See getDisconnectCode() 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.

      Returns:
      the value of the DisconnectReason property (read-only)

    • getEnableCache

      public boolean getEnableCache()
      Controls whether Chilkat caches remote file sizes and attributes requested by getFileSize32(String, boolean, boolean), getFileSize64(String, boolean, boolean), getFileSizeStr(String, boolean, boolean), getFileCreateTimeStr(String, boolean, boolean), getFileLastAccessStr(String, boolean, boolean), getFileLastModifiedStr(String, boolean, boolean), getFileOwner(String, boolean, boolean), getFileGroup(String, boolean, boolean), getFilePermissions(String, boolean, boolean). 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.

      Caching applies only when a remote path is used, not when an open handle is used. Call clearCache() when remote metadata may have changed.

      Returns:
      the value of the EnableCache property

    • setEnableCache

      public void setEnableCache​(boolean value)
      Sets the EnableCache property; see getEnableCache().
      Parameters:
      value - the new value

    • getEnableCompression

      public boolean getEnableCompression()
      Controls whether SSH compression may be negotiated. The default is false.

      Some older servers advertise compression but fail when it is enabled. If the server disconnects during or immediately after connection or authentication, try leaving this property false.

      Returns:
      the value of the EnableCompression property

    • setEnableCompression

      public void setEnableCompression​(boolean value)
      Sets the EnableCompression property; see getEnableCompression().
      Parameters:
      value - the new value

    • getEnableSecrets

      public boolean getEnableSecrets()
      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 getHttpProxyPassword(), getSocksPassword(), authenticatePw(String, String), and authenticatePwPk(String, String, SshKey).

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

      public void setEnableSecrets​(boolean value)
      Sets the EnableSecrets property; see getEnableSecrets().
      Parameters:
      value - the new value

    • getFilenameCharset

      public String getFilenameCharset()
      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.

      Use an explicit charset only when required by the server. UTF-8 is the normal SFTP filename encoding.

      Returns:
      the value of the FilenameCharset property

    • setFilenameCharset

      public void setFilenameCharset​(String value)
      Sets the FilenameCharset property; see getFilenameCharset().
      Parameters:
      value - the new value (not null)

    • getForceCipher

      public String getForceCipher()
      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(JsonObject).

      Cipher name Family

      chacha20-poly1305@openssh.com ChaCha20-Poly1305 authenticated encryption

      aes128-ctr, aes192-ctr, aes256-ctr AES in CTR mode

      aes128-cbc, aes192-cbc, aes256-cbc AES in CBC mode

      aes128-gcm@openssh.com, aes256-gcm@openssh.com AES-GCM authenticated encryption

      twofish128-cbc, twofish256-cbc Twofish in CBC mode

      blowfish-cbc Blowfish in CBC mode

      If the server does not support the selected cipher, connect(String, int) fails.

      Returns:
      the value of the ForceCipher property

    • setForceCipher

      public void setForceCipher​(String value)
      Sets the ForceCipher property; see getForceCipher().
      Parameters:
      value - the new value (not null)

    • getForceV3

      public boolean getForceV3()
      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 getProtocolVersion() to determine the negotiated version.

      Returns:
      the value of the ForceV3 property

    • setForceV3

      public void setForceV3​(boolean value)
      Sets the ForceV3 property; see getForceV3().
      Parameters:
      value - the new value

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck event callbacks during operations that support progress events. The default is 0, which disables periodic callbacks.
      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getHostKeyAlg

      public String getHostKeyAlg()
      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.

      Normally this property should be left unchanged.

      Returns:
      the value of the HostKeyAlg property

    • setHostKeyAlg

      public void setHostKeyAlg​(String value)
      Sets the HostKeyAlg property; see getHostKeyAlg().
      Parameters:
      value - the new value (not null)

    • getHostKeyFingerprint

      public String getHostKeyFingerprint()
      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

      For new applications, use getHostKeyFP(String, boolean, boolean) with SHA256. Compare the fingerprint with a value obtained from a trusted source before sending credentials.The value is cleared by disconnect(). Obtain and validate it while the SSH connection is active.

      Returns:
      the value of the HostKeyFingerprint property (read-only)

    • getHttpProxyAuthMethod

      public String getHttpProxyAuthMethod()
      Specifies the authentication method used by an HTTP proxy. Matching is case-insensitive.

      Value Behavior

      empty Automatically negotiate a supported method.

      Basic Use HTTP Basic authentication.

      NTLM Use NTLM authentication.

      Returns:
      the value of the HttpProxyAuthMethod property

    • setHttpProxyAuthMethod

      public void setHttpProxyAuthMethod​(String value)
      Sets the HttpProxyAuthMethod property; see getHttpProxyAuthMethod().
      Parameters:
      value - the new value (not null)

    • getHttpProxyDomain

      public String getHttpProxyDomain()
      Specifies the optional Windows domain used for NTLM authentication with an HTTP proxy. This property is ignored for Basic authentication.
      Returns:
      the value of the HttpProxyDomain property

    • setHttpProxyDomain

      public void setHttpProxyDomain​(String value)
      Sets the HttpProxyDomain property; see getHttpProxyDomain().
      Parameters:
      value - the new value (not null)

    • getHttpProxyHostname

      public String getHttpProxyHostname()
      Specifies the hostname or numeric IP address of an HTTP proxy used to establish the SSH connection.

      Set this property together with getHttpProxyPort(). A configured SOCKS proxy takes precedence when getSocksVersion() is 4 or 5.

      Returns:
      the value of the HttpProxyHostname property

    • setHttpProxyHostname

      public void setHttpProxyHostname​(String value)
      Sets the HttpProxyHostname property; see getHttpProxyHostname().
      Parameters:
      value - the new value (not null)

    • getHttpProxyPassword

      public String getHttpProxyPassword()
      Specifies the password used to authenticate with an HTTP proxy.
      Returns:
      the value of the HttpProxyPassword property

    • setHttpProxyPassword

      public void setHttpProxyPassword​(String value)
      Sets the HttpProxyPassword property; see getHttpProxyPassword().
      Parameters:
      value - the new value (not null)

    • getHttpProxyPort

      public int getHttpProxyPort()
      Specifies the HTTP proxy port. Common values include 8080 and 3128.

      The proxy is used when getHttpProxyHostname() is nonempty, this property is nonzero, and getSocksVersion() is 0.

      Returns:
      the value of the HttpProxyPort property

    • setHttpProxyPort

      public void setHttpProxyPort​(int value)
      Sets the HttpProxyPort property; see getHttpProxyPort().
      Parameters:
      value - the new value

    • getHttpProxyUsername

      public String getHttpProxyUsername()
      Specifies the username used to authenticate with an HTTP proxy.
      Returns:
      the value of the HttpProxyUsername property

    • setHttpProxyUsername

      public void setHttpProxyUsername​(String value)
      Sets the HttpProxyUsername property; see getHttpProxyUsername().
      Parameters:
      value - the new value (not null)

    • getIdleTimeoutMs

      public int getIdleTimeoutMs()
      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.

      Returns:
      the value of the IdleTimeoutMs property

    • setIdleTimeoutMs

      public void setIdleTimeoutMs​(int value)
      Sets the IdleTimeoutMs property; see getIdleTimeoutMs().
      Parameters:
      value - the new value

    • getIncludeDotDirs

      public boolean getIncludeDotDirs()
      Controls whether ReadDir and readDirListing(String, SFtpDir) include the special . and .. directory entries. The default is false.

      This property controls only the special directory entries . and ... It does not exclude ordinary hidden filenames such as .gitignore or .profile.

      Returns:
      the value of the IncludeDotDirs property

    • setIncludeDotDirs

      public void setIncludeDotDirs​(boolean value)
      Sets the IncludeDotDirs property; see getIncludeDotDirs().
      Parameters:
      value - the new value

    • getInitializeFailCode

      public int getInitializeFailCode()
      Contains the RFC 4254 channel-open failure code when initializeSftp() cannot open the SFTP session channel. The initial value is 0.

      Code Symbolic name

      1 SSH_OPEN_ADMINISTRATIVELY_PROHIBITED

      2 SSH_OPEN_CONNECT_FAILED

      3 SSH_OPEN_UNKNOWN_CHANNEL_TYPE

      4 SSH_OPEN_RESOURCE_SHORTAGE

      Returns:
      the value of the InitializeFailCode property (read-only)

    • getInitializeFailReason

      public String getInitializeFailReason()
      Contains the descriptive text associated with getInitializeFailCode() when initializeSftp() cannot open the SFTP session channel. The text is supplied by the server and may be empty or generic.
      Returns:
      the value of the InitializeFailReason property (read-only)

    • getIsConnected

      public boolean getIsConnected()
      Returns true when Chilkat's last known state indicates that the underlying SSH transport is connected. This means connect(String, int) 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.

      To actively test whether the connection is still writable, call sendIgnore() and check its return value. The server does not reply to an SSH IGNORE message.

      Returns:
      the value of the IsConnected property (read-only)

    • getKeepSessionLog

      public boolean getKeepSessionLog()
      Controls whether SSH and SFTP protocol traffic is accumulated in getSessionLog(). The default is false.

      Session logging is intended for diagnostics and grows as activity continues. Disable it when no longer needed and treat the resulting log as potentially sensitive.

      Returns:
      the value of the KeepSessionLog property

    • setKeepSessionLog

      public void setKeepSessionLog​(boolean value)
      Sets the KeepSessionLog property; see getKeepSessionLog().
      Parameters:
      value - the new value

    • getLastStatusCode

      public int getLastStatusCode()
      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.

      Code Symbolic name

      0 SSH_FX_OK

      1 SSH_FX_EOF

      2 SSH_FX_NO_SUCH_FILE

      3 SSH_FX_PERMISSION_DENIED

      4 SSH_FX_FAILURE

      5 SSH_FX_BAD_MESSAGE

      6 SSH_FX_NO_CONNECTION

      7 SSH_FX_CONNECTION_LOST

      8 SSH_FX_OP_UNSUPPORTED

      9 SSH_FX_INVALID_HANDLE

      10 SSH_FX_NO_SUCH_PATH

      11 SSH_FX_FILE_ALREADY_EXISTS

      12 SSH_FX_WRITE_PROTECT

      13 SSH_FX_NO_MEDIA

      14 SSH_FX_NO_SPACE_ON_FILESYSTEM

      15 SSH_FX_QUOTA_EXCEEDED

      16 SSH_FX_UNKNOWN_PRINCIPAL

      17 SSH_FX_LOCK_CONFLICT

      18 SSH_FX_DIR_NOT_EMPTY

      19 SSH_FX_NOT_A_DIRECTORY

      20 SSH_FX_INVALID_FILENAME

      21 SSH_FX_LINK_LOOP

      22 SSH_FX_CANNOT_DELETE

      23 SSH_FX_INVALID_PARAMETER

      24 SSH_FX_FILE_IS_A_DIRECTORY

      25 SSH_FX_BYTE_RANGE_LOCK_CONFLICT

      26 SSH_FX_BYTE_RANGE_LOCK_REFUSED

      27 SSH_FX_DELETE_PENDING

      28 SSH_FX_FILE_CORRUPT

      29 SSH_FX_OWNER_INVALID

      30 SSH_FX_GROUP_INVALID

      31 SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK

      See getLastStatusMessage() for the server-provided message text.

      Use each method's documented return value as the primary success test. Read this property immediately after a relevant SFTP failure when the server status provides additional detail.

      Returns:
      the value of the LastStatusCode property (read-only)

    • getLastStatusMessage

      public String getLastStatusMessage()
      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 getLastStatusCode() for the numeric code.

      Returns:
      the value of the LastStatusMessage property (read-only)

    • getMaxPacketSize

      public int getMaxPacketSize()
      Specifies the maximum packet length used by the underlying SSH transport. The default is 32768 bytes.

      Normally this property should remain unchanged.

      Returns:
      the value of the MaxPacketSize property

    • setMaxPacketSize

      public void setMaxPacketSize​(int value)
      Sets the MaxPacketSize property; see getMaxPacketSize().
      Parameters:
      value - the new value

    • getPasswordChangeRequested

      public boolean getPasswordChangeRequested()
      Indicates that the server rejected password authentication because the account password must be changed. This property is set by authenticatePw(String, String) and authenticatePwPk(String, String, SshKey).

      When true, call the authentication method again and pass the old and new passwords in this form: 

      |oldPassword|newPassword|
      Returns:
      the value of the PasswordChangeRequested property (read-only)

    • getPercentDoneScale

      public int getPercentDoneScale()
      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.

      This property applies only in environments that support event callbacks and only to operations for which progress can be measured.

      Returns:
      the value of the PercentDoneScale property

    • setPercentDoneScale

      public void setPercentDoneScale​(int value)
      Sets the PercentDoneScale property; see getPercentDoneScale().
      Parameters:
      value - the new value

    • getPreferIpv6

      public boolean getPreferIpv6()
      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.
      Returns:
      the value of the PreferIpv6 property

    • setPreferIpv6

      public void setPreferIpv6​(boolean value)
      Sets the PreferIpv6 property; see getPreferIpv6().
      Parameters:
      value - the new value

    • getPreserveDate

      public boolean getPreserveDate()
      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.

      This property does not apply to low-level transfers performed by opening a remote handle, reading or writing the data, and then closing the handle.

      Returns:
      the value of the PreserveDate property

    • setPreserveDate

      public void setPreserveDate​(boolean value)
      Sets the PreserveDate property; see getPreserveDate().
      Parameters:
      value - the new value

    • getProtocolVersion

      public int getProtocolVersion()
      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.

      The initial value is 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.

      Returns:
      the value of the ProtocolVersion property (read-only)

    • getReadDirMustMatch

      public String getReadDirMustMatch()
      Specifies a semicolon-separated list of filename patterns. When nonempty, ReadDir and readDirListing(String, SFtpDir) 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
      Returns:
      the value of the ReadDirMustMatch property

    • setReadDirMustMatch

      public void setReadDirMustMatch​(String value)
      Sets the ReadDirMustMatch property; see getReadDirMustMatch().
      Parameters:
      value - the new value (not null)

    • getReadDirMustNotMatch

      public String getReadDirMustNotMatch()
      Specifies a semicolon-separated list of filename patterns. When nonempty, ReadDir and readDirListing(String, SFtpDir) exclude entries matching any pattern. Exclusion is applied after getReadDirMustMatch().
      • * 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
      Returns:
      the value of the ReadDirMustNotMatch property

    • setReadDirMustNotMatch

      public void setReadDirMustNotMatch​(String value)
      Sets the ReadDirMustNotMatch property; see getReadDirMustNotMatch().
      Parameters:
      value - the new value (not null)

    • getServerIdentifier

      public String getServerIdentifier()
      Contains the SSH server-identification string received during connection establishment. For example: 
      SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.16

      The last received identifier can remain populated after disconnect(). Use getIsConnected() to determine whether the SSH transport is currently connected.

      Returns:
      the value of the ServerIdentifier property (read-only)

    • getSessionLog

      public String getSessionLog()
      Contains the in-memory SSH/SFTP protocol log. Enable logging by setting getKeepSessionLog() to true.

      This property contains log text, not a file path. Call clearSessionLog() to clear it.

      Returns:
      the value of the SessionLog property (read-only)

    • getSoRcvBuf

      public int getSoRcvBuf()
      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.

      Returns:
      the value of the SoRcvBuf property

    • setSoRcvBuf

      public void setSoRcvBuf​(int value)
      Sets the SoRcvBuf property; see getSoRcvBuf().
      Parameters:
      value - the new value

    • getSoSndBuf

      public int getSoSndBuf()
      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.

      Returns:
      the value of the SoSndBuf property

    • setSoSndBuf

      public void setSoSndBuf​(int value)
      Sets the SoSndBuf property; see getSoSndBuf().
      Parameters:
      value - the new value

    • getSocksHostname

      public String getSocksHostname()
      Specifies the SOCKS proxy hostname or IPv4 address. This property is used only when getSocksVersion() is 4 or 5.
      Returns:
      the value of the SocksHostname property

    • setSocksHostname

      public void setSocksHostname​(String value)
      Sets the SocksHostname property; see getSocksHostname().
      Parameters:
      value - the new value (not null)

    • getSocksPassword

      public String getSocksPassword()
      Specifies the SOCKS5 password when username/password authentication is required. SOCKS4 does not use a password, so this property is ignored when getSocksVersion() is 4.
      Returns:
      the value of the SocksPassword property

    • setSocksPassword

      public void setSocksPassword​(String value)
      Sets the SocksPassword property; see getSocksPassword().
      Parameters:
      value - the new value (not null)

    • getSocksPort

      public int getSocksPort()
      Specifies the SOCKS proxy port. The default is 1080. This property is used only when getSocksVersion() is 4 or 5.
      Returns:
      the value of the SocksPort property

    • setSocksPort

      public void setSocksPort​(int value)
      Sets the SocksPort property; see getSocksPort().
      Parameters:
      value - the new value

    • getSocksUsername

      public String getSocksUsername()
      Specifies the SOCKS proxy username. For SOCKS4 it is sent as the user ID; for SOCKS5 it is used with getSocksPassword() for username/password authentication.
      Returns:
      the value of the SocksUsername property

    • setSocksUsername

      public void setSocksUsername​(String value)
      Sets the SocksUsername property; see getSocksUsername().
      Parameters:
      value - the new value (not null)

    • getSocksVersion

      public int getSocksVersion()
      Selects whether and how a SOCKS proxy is used.

      Value Behavior

      0 Do not use a SOCKS proxy. This is the default.

      4 Connect through a SOCKS4 proxy.

      5 Connect through a SOCKS5 proxy.

      Returns:
      the value of the SocksVersion property

    • setSocksVersion

      public void setSocksVersion​(int value)
      Sets the SocksVersion property; see getSocksVersion().
      Parameters:
      value - the new value

    • getSyncCreateAllLocalDirs

      public boolean getSyncCreateAllLocalDirs()
      Controls whether syncTreeDownload(String, String, int, boolean) 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.

      When true, an empty remote directory is created locally even when no file beneath it is downloaded.

      Returns:
      the value of the SyncCreateAllLocalDirs property

    • setSyncCreateAllLocalDirs

      public void setSyncCreateAllLocalDirs​(boolean value)
      Sets the SyncCreateAllLocalDirs property; see getSyncCreateAllLocalDirs().
      Parameters:
      value - the new value

    • getSyncDirectives

      public String getSyncDirectives()
      Specifies comma-separated directives that modify syncTreeUpload(String, String, int, boolean) or syncTreeDownload(String, String, int, boolean). The default is an empty string.

      Directive Effect

      UploadIgnoreLocalOpenFailures During upload synchronization, skip local files that cannot be opened, such as files held with exclusive access by another process.

      Returns:
      the value of the SyncDirectives property

    • setSyncDirectives

      public void setSyncDirectives​(String value)
      Sets the SyncDirectives property; see getSyncDirectives().
      Parameters:
      value - the new value (not null)

    • getSyncMustMatch

      public String getSyncMustMatch()
      Specifies a semicolon-separated list of wildcard filename patterns. syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean) 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

      Use * to match zero or more characters. Separate multiple patterns with semicolons.

      Returns:
      the value of the SyncMustMatch property

    • setSyncMustMatch

      public void setSyncMustMatch​(String value)
      Sets the SyncMustMatch property; see getSyncMustMatch().
      Parameters:
      value - the new value (not null)

    • getSyncMustMatchDir

      public String getSyncMustMatchDir()
      Specifies a semicolon-separated list of wildcard directory-name patterns. syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean) enter only directories matching at least one pattern. 
      xml;txt;data_*

      Use * to match zero or more characters. Separate multiple patterns with semicolons.

      Returns:
      the value of the SyncMustMatchDir property

    • setSyncMustMatchDir

      public void setSyncMustMatchDir​(String value)
      Sets the SyncMustMatchDir property; see getSyncMustMatchDir().
      Parameters:
      value - the new value (not null)

    • getSyncMustNotMatch

      public String getSyncMustNotMatch()
      Specifies a semicolon-separated list of wildcard filename patterns. syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean) skip files matching any pattern.

      This filter applies to filenames, not directory names encountered while recursively traversing a tree. 

      *.tmp;*.bak;*.log

      Use * to match zero or more characters. Separate multiple patterns with semicolons.

      Returns:
      the value of the SyncMustNotMatch property

    • setSyncMustNotMatch

      public void setSyncMustNotMatch​(String value)
      Sets the SyncMustNotMatch property; see getSyncMustNotMatch().
      Parameters:
      value - the new value (not null)

    • getSyncMustNotMatchDir

      public String getSyncMustNotMatchDir()
      Specifies a semicolon-separated list of wildcard directory-name patterns. syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean) skip directories matching any pattern. 
      temp;cache;archive_*

      Use * to match zero or more characters. Separate multiple patterns with semicolons.

      Returns:
      the value of the SyncMustNotMatchDir property

    • setSyncMustNotMatchDir

      public void setSyncMustNotMatchDir​(String value)
      Sets the SyncMustNotMatchDir property; see getSyncMustNotMatchDir().
      Parameters:
      value - the new value (not null)

    • getTcpNoDelay

      public boolean getTcpNoDelay()
      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.
      Returns:
      the value of the TcpNoDelay property

    • setTcpNoDelay

      public void setTcpNoDelay​(boolean value)
      Sets the TcpNoDelay property; see getTcpNoDelay().
      Parameters:
      value - the new value

    • getUncommonOptions

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

      Keyword Effect

      ForceUserAuthRsaSha1 Force legacy ssh-rsa/SHA-1 signatures for RSA user authentication. Set before connecting.

      ProtectFromVpn On Android, bypass an installed or active VPN.

      NoSyncDownloadEmptyFiles Prevent empty files from being downloaded by SyncTreeDownload.

      no-weak-mac-algs Remove weaker SHA-1, MD5, and RIPEMD-160 MAC algorithms from the offered list.

      +ssh-hmac-etm Re-enable OpenSSH Encrypt-then-MAC algorithms disabled by default as a Terrapin mitigation.

      +chacha20-poly1305@openssh.com Re-enable chacha20-poly1305@openssh.com, disabled by default as a Terrapin mitigation.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • getUploadChunkSize

      public int getUploadChunkSize()
      Specifies the chunk size, in bytes, used by uploadFile(String, String) and uploadFileByName(String, String). The default is 32000.

      If an upload fails because the local operating system aborts the connection, try a smaller value such as 4096. Smaller chunks can reduce throughput.

      Returns:
      the value of the UploadChunkSize property

    • setUploadChunkSize

      public void setUploadChunkSize​(int value)
      Sets the UploadChunkSize property; see getUploadChunkSize().
      Parameters:
      value - the new value

    • getUserAuthBanner

      public String getUserAuthBanner()
      Contains a user-authentication banner received from the server. Check this property after startKeyboardAuth(String) or another authentication attempt and display it to the user when appropriate.

      When no banner is available, the property returns an empty string.

      Returns:
      the value of the UserAuthBanner property

    • setUserAuthBanner

      public void setUserAuthBanner​(String value)
      Sets the UserAuthBanner property; see getUserAuthBanner().
      Parameters:
      value - the new value (not null)

    • getUtcMode

      public boolean getUtcMode()
      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
      Returns:
      the value of the UtcMode property

    • setUtcMode

      public void setUtcMode​(boolean value)
      Sets the UtcMode property; see getUtcMode().
      Parameters:
      value - the new value

    • getXferByteCount

      public long getXferByteCount()
      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(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean), the value is cumulative across all files processed by the operation. Use getXferByteCount64() when a 64-bit count is required.

      Returns:
      the value of the XferByteCount property (read-only)

    • getXferByteCount64

      public long getXferByteCount64()
      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(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean), the value is cumulative across all files processed by the operation.

      Returns:
      the value of the XferByteCount64 property (read-only)

    • authenticatePk

      public void authenticatePk​(String username, SshKey privateKey)
      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.

      Call connect(String, int) first. After a failure, inspect getAuthFailReason() and LastErrorText.

      Parameters:
      username - the username argument (not null)
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticatePw

      public void authenticatePw​(String login, String password)
      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 getPasswordChangeRequested(). After a failure, inspect getAuthFailReason() and LastErrorText.

      A rejected password does not necessarily close the SSH connection. The application may retry authentication on the same connected session. After a later success, an older getAuthFailReason() value can remain populated.

      Parameters:
      login - the login argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticatePwPk

      public void authenticatePwPk​(String username, String password, SshKey privateKey)
      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.

      Most servers require either password or public-key authentication rather than both. After a failure, inspect getAuthFailReason() and LastErrorText.

      Parameters:
      username - the username argument (not null)
      password - the password argument (not null)
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticateSecPw

      public void authenticateSecPw​(SecureString login, SecureString password)
      Works like authenticatePw(String, String), but receives login and password in SecureString objects.
      Parameters:
      login - the login argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticateSecPwPk

      public void authenticateSecPwPk​(SecureString username, SecureString password, SshKey privateKey)
      Works like authenticatePwPk(String, String, SshKey), but receives username and password in SecureString objects. privateKey supplies the private key.
      Parameters:
      username - the username argument (not null)
      password - the password argument (not null)
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearCache

      public void clearCache()
      Clears the internal remote file-attribute cache used when getEnableCache() is true.

    • clearSessionLog

      public void clearSessionLog()
      Clears the in-memory text stored in getSessionLog().

    • closeHandle

      public void closeHandle​(String handle)
      Closes the remote file or directory handle specified by handle. The handle must have been returned by openFile(String, String, String) or openDir(String).

      Handles are specific to one initialized SFTP session. Close each handle exactly once. Closing an empty, invalid, or already-closed handle returns false. A handle must never be reused after disconnecting or replacing the connection.

      Parameters:
      handle - the handle argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • connect

      public void connect​(String domainName, int port)
      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.

      A successful connection establishes the SSH transport only. Next call an authentication method, then call initializeSftp(). 

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

      Supported negotiation algorithms include:

      Category Algorithms

      Host key ssh-ed25519, rsa-sha2-256, rsa-sha2-512, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-rsa, ssh-dss

      Key exchange curve25519-sha256, curve25519-sha256@libssh.org, NIST ECDH, Diffie-Hellman group 1/14/16/18, and group-exchange SHA-1/SHA-256

      Ciphers AES CTR/CBC/GCM, Twofish CBC, Blowfish CBC, and optionally chacha20-poly1305@openssh.com

      MAC SHA-2, SHA-1, RIPEMD-160, MD5, and optionally OpenSSH Encrypt-then-MAC variants

      Compression none, zlib, and zlib@openssh.com

      Connection failures can occur before SSH negotiation because of firewalls, endpoint security, routing, network ACLs, proxy configuration, or server policy.Calling while connected: A new successful 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.

      Parameters:
      domainName - the domainName argument (not null)
      port - the port argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • connectThroughSsh

      public void connectThroughSsh​(Ssh sshConn, String hostname, int port)
      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.

      Parameters:
      sshConn - the sshConn argument (not null)
      hostname - the hostname argument (not null)
      port - the port argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • continueKeyboardAuth

      public String continueKeyboardAuth​(String response)
      Continues keyboard-interactive authentication by submitting response for the prompts returned by startKeyboardAuth(String).

      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>
      Parameters:
      response - the response argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • copyFileAttr

      public void copyFileAttr​(String localFilename, String remoteFilename, boolean isHandle)
      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.

      Negotiated SFTP version Attributes copied

      SFTP v3 and earlier Last-modified time and last-access time

      SFTP v4 and v5 Last-modified time, last-access time, and creation time

      SFTP v6 and later The preceding timestamps plus read-only, hidden, archive, compressed, and encrypted flags

      The remote server and filesystem determine whether all requested attributes can be applied. Last-access time may change when the server accesses the file, and compressed or encrypted flags may not have the same effect on every server.

      Parameters:
      localFilename - the localFilename argument (not null)
      remoteFilename - the remoteFilename argument (not null)
      isHandle - the isHandle argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • createDir

      public void createDir​(String path)
      Creates the remote directory specified by path. Parent directories are not necessarily created automatically.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • disconnect

      public void 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(String, int), authenticate again, and call initializeSftp() before performing SFTP operations.

      Some properties retain values from the previous session after disconnect, including the negotiated protocol version, server identifier, and last SFTP status. Treat these as historical values rather than evidence of a live session.

    • downloadBd

      public void downloadBd​(String remoteFilePath, BinData binData)
      Downloads the remote file at remoteFilePath and appends its bytes to binData.

      Existing data in binData is preserved. Clear it first when replacement rather than append behavior is required.

      Parameters:
      remoteFilePath - the remoteFilePath argument (not null)
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadFile

      public void downloadFile​(String handle, String toFilename)
      Streams the remote file identified by handle to the local filesystem path toFilename. The handle must have been returned by openFile(String, String, String).

      The transfer is streamed and is not limited by available memory. Close the remote handle when the download is complete.

      This method downloads the entire remote file beginning at byte offset 0. It does not begin at the handle's current sequential read position.

      Parameters:
      handle - the handle argument (not null)
      toFilename - the toFilename argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadFileByName

      public void downloadFileByName​(String remoteFilePath, String localFilePath)
      Downloads the remote file at remoteFilePath to the local filesystem path localFilePath.

      When getPreserveDate() is true, Chilkat preserves the remote file's last-modified time.

      An absolute remote path begins with / and is relative to the server filesystem root. A relative path is interpreted relative to the authenticated user's home directory.If the local destination file exists, it is truncated before the download.

      Parameters:
      remoteFilePath - the remoteFilePath argument (not null)
      localFilePath - the localFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadSb

      public void downloadSb​(String remoteFilePath, String charset, StringBuilder sb)
      Downloads the remote file at remoteFilePath, decodes it using charset, and appends the text to sb.

      Existing text in sb is preserved. Clear it first when replacement rather than append behavior is required.

      Parameters:
      remoteFilePath - the remoteFilePath argument (not null)
      charset - the charset argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • eof

      public boolean eof​(String handle)
      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 getLastStatusCode() to SSH_FX_EOF, and causes this method to return true.

      An empty, malformed, or already-closed handle can also cause this method to return true. Use lastReadFailed(String) and the read method's result to distinguish a normal EOF from a handle or read failure.

      Parameters:
      handle - the handle argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • fileExists

      public int fileExists​(String remotePath, boolean followLinks)
      Checks the remote item at remotePath. When followLinks is true, a symbolic link is followed and the target type is returned.

      Return value Meaning

      -1 Unable to determine the result. Inspect LastErrorText.

      0 The path does not exist.

      1 A regular file exists.

      2 A directory exists.

      3 A symbolic link exists. This is possible only when followLinks is false.

      4 A special filesystem entry exists.

      5 An entry of unknown type exists.

      6 A socket exists.

      7 A character device exists.

      8 A block device exists.

      9 A FIFO exists.

      Positive values correspond to SFTP filesystem entry types. Some types are platform-dependent.For a dangling symbolic link, followLinks = false returns 3 for the link itself, while followLinks = true returns 0 because the target does not exist.

      Parameters:
      remotePath - the remotePath argument (not null)
      followLinks - the followLinks argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • fsync

      public void fsync​(String handle)
      Requests that the server flush pending data for the open file identified by handle to stable storage.

      This method uses the OpenSSH fsync@openssh.com extension and succeeds only when the server supports that extension.

      Parameters:
      handle - the handle argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getFileCreateTimeStr

      public String getFileCreateTimeStr​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      Returns the remote file's creation date and time. pathOrHandle may contain a remote path or a handle returned by openFile(String, String, String). 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.

      SFTP v3 and earlier do not provide a file creation time.

      The result is an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getFileGroup

      public String getFileGroup​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      Returns the remote file's group ownership. pathOrHandle may contain a remote path or a handle returned by openFile(String, String, String). 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.

      With SFTP v3 and earlier, the result is the decimal numeric GID because textual group names are not supported.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getFileLastAccessStr

      public String getFileLastAccessStr​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      Returns the remote file's last-access date and time. pathOrHandle may contain a remote path or a handle returned by openFile(String, String, String). 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.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getFileLastModifiedStr

      public String getFileLastModifiedStr​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      Returns the remote file's last-modified date and time. pathOrHandle may contain a remote path or a handle returned by openFile(String, String, String). 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.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getFileOwner

      public String getFileOwner​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      Returns the remote file's owner. pathOrHandle may contain a remote path or a handle returned by openFile(String, String, String). 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.

      With SFTP v3 and earlier, the result is the decimal numeric UID because textual owner names are not supported.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getFilePermissions

      public int getFilePermissions​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      Returns the remote item's complete POSIX mode value. pathOrHandle may contain a remote path or a handle returned by openFile(String, String, String). 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(String, boolean, int) to change the permissions.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getFileSize32

      public int getFileSize32​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      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(String, String, String). 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 -1 when the size cannot be represented as a 32-bit integer. Use GetFileSize64 or GetFileSizeStr for large files.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getFileSize64

      public long getFileSize64​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      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(String, String, String). 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.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getFileSizeStr

      public String getFileSizeStr​(String pathOrHandle, boolean bFollowLinks, boolean bIsHandle)
      Returns the remote file's size in bytes as a decimal string. pathOrHandle may contain a remote path or a handle returned by openFile(String, String, String). 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.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bFollowLinks - the bFollowLinks argument
      bIsHandle - the bIsHandle argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getHostKeyFP

      public String getHostKeyFP​(String hashAlg, boolean includeKeyType, boolean includeHashName)
      Returns the connected server's host-key fingerprint using hashAlg. Common choices include SHA256, SHA384, SHA512, SHA1, and MD5.

      includeKeyType includeHashName Example format

      true true ssh-rsa SHA256:L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...

      true false ssh-rsa L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...

      false true SHA256:L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...

      false false L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...

      For server identity verification, compare a SHA-256 fingerprint with a value obtained from a trusted source before sending credentials.

      Parameters:
      hashAlg - the hashAlg argument (not null)
      includeKeyType - the includeKeyType argument
      includeHashName - the includeHashName argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getLastJsonData

      public void getLastJsonData​(JsonObject json)
      Populates json with supplemental details produced by the most recent method when such details are available. Many methods do not produce additional JSON information.
      Parameters:
      json - the json argument (not null)

    • getSyncedFiles

      public void getSyncedFiles​(StringTable strTab)
      Appends to strTab the relative paths processed by the most recent syncTreeUpload(String, String, int, boolean) or syncTreeDownload(String, String, int, boolean) operation.

      For downloads, entries can include local directories that were created. Directory paths end with / so they can be distinguished from file paths.

      Existing entries in strTab are preserved.Clear 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.

      Parameters:
      strTab - the strTab argument (not null)

    • hardLink

      public void hardLink​(String oldPath, String newPath)
      Creates a hard link from newPath to the existing remote file at oldPath.

      This method uses the OpenSSH hardlink@openssh.com extension and succeeds only when the server supports that extension.A successful hard link refers to the same underlying file. Modifying the existing file through either path changes the content observed through the other path.

      Parameters:
      oldPath - the oldPath argument (not null)
      newPath - the newPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • initializeSftp

      public void 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 getProtocolVersion() to determine the negotiated SFTP version.

      If opening the SFTP channel fails, inspect getInitializeFailCode(), getInitializeFailReason(), and LastErrorText.Call this method only once for a given SSH connection. A second call on the same connection returns false. After disconnecting or replacing the connection, authenticate the new connection and call this method again.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • lastReadFailed

      public boolean lastReadFailed​(String handle)
      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.

      Parameters:
      handle - the handle argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • lastReadNumBytes

      public int lastReadNumBytes​(String handle)
      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.

      Parameters:
      handle - the handle argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • openDir

      public String openDir​(String path)
      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.

      This method does not change a working directory. SFTP is not FTP and has no persistent current-directory command.

      Parameters:
      path - the path argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • openFile

      public String openFile​(String remotePath, String access, String createDisposition)
      Opens or creates the remote file at remotePath and returns a handle for subsequent read or write operations. Close the handle with CloseHandle when finished.

      access must be readOnly, writeOnly, or readWrite.

      createDisposition is a comma-separated list. It must contain exactly one primary disposition:

      Primary disposition Behavior

      createNew Create a new file; fail if it already exists.

      createTruncate Create a new file, or open and truncate an existing file.

      openExisting Open an existing file; fail if it does not exist.

      openOrCreate Open the file if it exists, otherwise create it.

      truncateExisting Open and truncate an existing file; fail if it does not exist.

      Additional optional keywords are:

      Option Behavior

      appendData Write at the end of the file. Appends are not guaranteed to be atomic.

      appendDataAtomic Append atomically so concurrent appenders do not collide. SFTP v5 or later.

      textMode Request server text-mode processing and canonical newline conversion. SFTP v5 or later.

      blockRead Request exclusive read access. SFTP v5 or later.

      blockWrite Request exclusive write access. SFTP v5 or later.

      blockDelete Prevent deletion while the handle is open. SFTP v5 or later.

      blockAdvisory Make the requested block modes advisory. SFTP v5 or later.

      noFollow Fail if the final path component is a symbolic link. SFTP v5 or later.

      deleteOnClose Request deletion when the last handle is closed. SFTP v5 or later.

      accessAuditAlarmInfo Request privileges needed to read or write AUDIT or ALARM ACL entries. SFTP v5 or later.

      accessBackup Request backup/restore privileges that may bypass normal access checks. SFTP v5 or later.

      backupStream Read or write a server-specific backup stream. SFTP v5 or later.

      Options marked SFTP v5 or later require getForceV3() to be false and a negotiated getProtocolVersion() of at least 5.An absolute remote path begins with /. 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.Use only documented values: Some servers or Chilkat versions may tolerate an unknown access value, an unknown option, or conflicting primary dispositions, but the resulting behavior is unspecified. Supply one documented access value and exactly one primary disposition.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.

      Parameters:
      remotePath - the remotePath argument (not null)
      access - the access argument (not null)
      createDisposition - the createDisposition argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readDirListing

      public void readDirListing​(String handle, SFtpDir dirObj)
      Reads all remaining directory entries from handle, which must have been returned by openDir(String), 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 getLastStatusCode() to SSH_FX_EOF.

      This method does not clear dirObj. Use a new or cleared SFtpDir object when an empty result must replace an earlier listing. Close the directory handle when finished.

      Parameters:
      handle - the handle argument (not null)
      dirObj - the dirObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readFileBd

      public void readFileBd​(String handle, int numBytes, BinData bd)
      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(String, String, String).

      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.

      This method shares the handle's sequential read position with ReadFileBytes and readFileText(String, int, String). Existing bytes in bd are preserved.

      Parameters:
      handle - the handle argument (not null)
      numBytes - the numBytes argument
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readFileText

      public String readFileText​(String handle, int numBytes, String charset)
      Reads up to numBytes bytes from the current position of handle, decodes the bytes using charset, and returns the resulting text.

      See Supported Charsets.

      The requested size is measured in bytes, not characters. With a multibyte encoding such as UTF-8 or Shift_JIS, the final character can be split across calls. For robust streaming, read raw bytes and decode with application-maintained state.Multibyte boundaries: Chilkat does not retain an incomplete multibyte character between calls. If 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.

      Parameters:
      handle - the handle argument (not null)
      numBytes - the numBytes argument
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readFileText32

      public String readFileText32​(String handle, int offset, int numBytes, String charset)
      Reads up to numBytes bytes from handle at the 32-bit byte offset, decodes the bytes using charset, and returns the resulting text.

      See Supported Charsets.

      The requested size is measured in bytes, not characters. With a multibyte encoding such as UTF-8 or Shift_JIS, the final character can be split across calls. For robust streaming, read raw bytes and decode with application-maintained state.

      Parameters:
      handle - the handle argument (not null)
      offset - the offset argument
      numBytes - the numBytes argument
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readFileText64

      public String readFileText64​(String handle, long offset, int numBytes, String charset)
      Reads up to numBytes bytes from handle at the 64-bit byte offset, decodes the bytes using charset, and returns the resulting text.

      See Supported Charsets.

      The requested size is measured in bytes, not characters. With a multibyte encoding such as UTF-8 or Shift_JIS, the final character can be split across calls. For robust streaming, read raw bytes and decode with application-maintained state.

      Parameters:
      handle - the handle argument (not null)
      offset - the offset argument
      numBytes - the numBytes argument
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readFileText64s

      public String readFileText64s​(String handle, String offset, int numBytes, String charset)
      Reads up to numBytes bytes from handle at the byte offset supplied as decimal string offset, decodes the bytes using charset, and returns the resulting text.

      See Supported Charsets.

      The requested size is measured in bytes, not characters. With a multibyte encoding, the final character can be split across calls.

      Parameters:
      handle - the handle argument (not null)
      offset - the offset argument (not null)
      numBytes - the numBytes argument
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readLink

      public String readLink​(String path)
      Returns the target path stored in the symbolic link at remote path.

      The returned value is the target string stored in the link. It is not automatically canonicalized and can be relative, absolute, or refer to a nonexistent target.

      Parameters:
      path - the path argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • realPath

      public String realPath​(String originalPath, String composePath)
      Asks the server to canonicalize originalPath and returns the resulting absolute remote path.

      For SFTP v5 or later, composePath may optionally modify or extend the original path; pass an empty string when no composition is needed. If composePath is absolute, it replaces originalPath.

      SFTP v3 and v4 do not support path composition. On those versions, composePath is ignored and the method canonicalizes only originalPath.

      Parameters:
      originalPath - the originalPath argument (not null)
      composePath - the composePath argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeDir

      public void removeDir​(String path)
      Deletes the remote directory specified by path.

      Most SFTP servers require the directory to be empty before it can be removed.

      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeFile

      public void removeFile​(String filename)
      Deletes the remote file specified by filename.
      Parameters:
      filename - the filename argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • renameFileOrDir

      public void renameFileOrDir​(String oldPath, String newPath)
      Renames or moves a remote file or directory from oldPath to newPath. 
      oldPath: someDirA/filename
 newPath: someDirB/abc/xyz/filename
      Parameters:
      oldPath - the oldPath argument (not null)
      newPath - the newPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • resumeDownloadFileByName

      public void resumeDownloadFileByName​(String remoteFilePath, String localFilePath)
      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.

      Important: The existing local bytes are not compared with the remote source. Before resuming, the application must ensure that the local file is the correct prefix of the remote file.

      Parameters:
      remoteFilePath - the remoteFilePath argument (not null)
      localFilePath - the localFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • resumeUploadFileByName

      public void resumeUploadFileByName​(String remoteFilePath, String localFilePath)
      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.

      Important: The existing remote bytes are not compared with the local source. Before resuming, the application must ensure that the remote file is the correct prefix of the local file.

      Parameters:
      remoteFilePath - the remoteFilePath argument (not null)
      localFilePath - the localFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendIgnore

      public void 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.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAllowedAlgorithms

      public void setAllowedAlgorithms​(JsonObject json)
      Configures the exact set of SSH algorithms permitted for subsequent connections using the settings in json.

      Call this method before Connect. The connection fails when no mutually supported algorithm remains in a required category.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setCreateDt

      public void setCreateDt​(String pathOrHandle, boolean isHandle, DateTime createDateTime)
      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.

      SFTP v3 and earlier do not support setting creation time.

      createDateTime supplies the new value.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      isHandle - the isHandle argument
      createDateTime - the createDateTime argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setCreateTimeStr

      public void setCreateTimeStr​(String pathOrHandle, boolean bIsHandle, String dateTimeStr)
      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.

      SFTP v3 and earlier do not support setting creation time.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bIsHandle - the bIsHandle argument
      dateTimeStr - the dateTimeStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setLastAccessDt

      public void setLastAccessDt​(String pathOrHandle, boolean isHandle, DateTime accessDateTime)
      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.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      isHandle - the isHandle argument
      accessDateTime - the accessDateTime argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setLastAccessTimeStr

      public void setLastAccessTimeStr​(String pathOrHandle, boolean bIsHandle, String dateTimeStr)
      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.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bIsHandle - the bIsHandle argument
      dateTimeStr - the dateTimeStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setLastModifiedDt

      public void setLastModifiedDt​(String pathOrHandle, boolean isHandle, DateTime modifiedDateTime)
      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.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      isHandle - the isHandle argument
      modifiedDateTime - the modifiedDateTime argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setLastModifiedTimeStr

      public void setLastModifiedTimeStr​(String pathOrHandle, boolean bIsHandle, String dateTimeStr)
      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.

      When SFTP v3 is negotiated, the stored timestamp has whole-second precision.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      bIsHandle - the bIsHandle argument
      dateTimeStr - the dateTimeStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setOwnerAndGroup

      public void setOwnerAndGroup​(String pathOrHandle, boolean isHandle, String owner, String group)
      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.

      SFTP v3 and earlier do not support textual owner and group names.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      isHandle - the isHandle argument
      owner - the owner argument (not null)
      group - the group argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setPermissions

      public void setPermissions​(String pathOrHandle, boolean isHandle, int permissions)
      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.

      After setting permissions, getFilePermissions(String, boolean, boolean) returns the complete mode, including the file-type bits. For example, setting 0644 on a regular file can subsequently return 0100644.

      Parameters:
      pathOrHandle - the pathOrHandle argument (not null)
      isHandle - the isHandle argument
      permissions - the permissions argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • startKeyboardAuth

      public String startKeyboardAuth​(String login)
      Begins keyboard-interactive authentication for login and returns XML describing the server's prompts. 
      <infoRequest numPrompts="N">
   <name>name_string</name>
   <instruction>instruction_string</instruction>
   <prompt1 echo="1_or_0">prompt_string</prompt1>
   ...
   <promptN echo="1_or_0">prompt_string</promptN>
 </infoRequest>

      The echo attribute indicates whether the response may be displayed while entered. A value of 0 normally identifies secret input such as a password.

      If authentication immediately succeeds or fails, the result has one of these forms: 

      <success>success message</success>
 
 <error>error message</error>
      Parameters:
      login - the login argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • symLink

      public void symLink​(String oldPath, String newPath)
      Creates a symbolic link on the server. oldPath identifies the link target and newPath identifies the new symbolic-link path.

      The server's SFTP implementation determines path interpretation and whether symbolic links are permitted.

      Parameters:
      oldPath - the oldPath argument (not null)
      newPath - the newPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • syncTreeDownload

      public void syncTreeDownload​(String remoteRoot, String localRoot, int mode, boolean recurse)
      Synchronizes files from the remote directory remoteRoot to the local filesystem directory localRoot.

      Mode Behavior

      0 Download all files.

      1 Download files that do not exist locally.

      2 Download files that are newer remotely or missing locally.

      3 Download only files that are newer remotely; do not download missing local files.

      5 Download files that are missing locally or differ in size.

      6 Mode 5 plus files that are newer remotely.

      99 Do not download; delete remote files that do not exist locally.

      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(StringTable) after the operation to retrieve the relative paths that were downloaded or created.

      With getSyncCreateAllLocalDirs() 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.

      Parameters:
      remoteRoot - the remoteRoot argument (not null)
      localRoot - the localRoot argument (not null)
      mode - the mode argument
      recurse - the recurse argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • syncTreeUpload

      public void syncTreeUpload​(String localBaseDir, String remoteBaseDir, int mode, boolean bRecurse)
      Synchronizes files from the local filesystem directory localBaseDir to the remote directory remoteBaseDir.

      Mode Behavior

      0 Upload all files.

      1 Upload files that do not exist remotely.

      2 Upload files that are newer locally or missing remotely.

      3 Upload only files that are newer locally; do not upload missing remote files.

      4 Upload files that are missing remotely or differ in size.

      5 Mode 4 plus files that are newer locally.

      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(StringTable) after the operation to retrieve the relative paths that were uploaded.

      Mode 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.

      Parameters:
      localBaseDir - the localBaseDir argument (not null)
      remoteBaseDir - the remoteBaseDir argument (not null)
      mode - the mode argument
      bRecurse - the bRecurse argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadBd

      public void uploadBd​(BinData binData, String remoteFilePath)
      Uploads all bytes in binData to the remote file at remoteFilePath.

      If the destination exists, it is truncated before the bytes are uploaded.

      Parameters:
      binData - the binData argument (not null)
      remoteFilePath - the remoteFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadFile

      public void uploadFile​(String handle, String fromLocalFilePath)
      Streams the local filesystem file at fromLocalFilePath to the remote file identified by handle. The handle must have been returned by openFile(String, String, String).

      Close the remote handle when the upload is complete.

      The upload begins at the handle's current sequential write position. Existing bytes before that position are preserved unless the file was truncated when opened.

      Parameters:
      handle - the handle argument (not null)
      fromLocalFilePath - the fromLocalFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadFileByName

      public void uploadFileByName​(String remoteFilePath, String localFilePath)
      Uploads the local filesystem file at localFilePath to remoteFilePath.

      When getPreserveDate() is true, Chilkat preserves the local file's last-modified time on the remote file.

      An absolute remote path begins with / and is relative to the server filesystem root. A relative path is interpreted relative to the authenticated user's home directory.If the destination exists, it is truncated before the upload. A zero-byte local file creates or truncates the remote file to zero bytes. Missing remote parent directories are not created automatically.

      Parameters:
      remoteFilePath - the remoteFilePath argument (not null)
      localFilePath - the localFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadSb

      public void uploadSb​(StringBuilder sb, String remoteFilePath, String charset, boolean includeBom)
      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.

      If the destination exists, it is truncated before the text is uploaded. For utf-8, setting includeBom to true prepends the three bytes EF BB BF; setting it to false omits them.

      Parameters:
      sb - the sb argument (not null)
      remoteFilePath - the remoteFilePath argument (not null)
      charset - the charset argument (not null)
      includeBom - the includeBom argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFileBd

      public void writeFileBd​(String handle, BinData bd)
      Appends all bytes in bd to the remote file identified by handle. The handle must have been returned by openFile(String, String, String).
      Parameters:
      handle - the handle argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFileText

      public void writeFileText​(String handle, String charset, String textData)
      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.

      No byte-order mark or line ending is added unless it is present in the supplied text or produced by the selected encoding.

      Parameters:
      handle - the handle argument (not null)
      charset - the charset argument (not null)
      textData - the textData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFileText32

      public void writeFileText32​(String handle, int offset32, String charset, String textData)
      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.No byte-order mark or line ending is added unless it is present in the supplied text or produced by the selected encoding.

      Parameters:
      handle - the handle argument (not null)
      offset32 - the offset32 argument
      charset - the charset argument (not null)
      textData - the textData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFileText64

      public void writeFileText64​(String handle, long offset64, String charset, String textData)
      Encodes textData using charset and writes the resulting bytes to handle at the 64-bit byte offset offset64.

      See Supported Charsets.

      No byte-order mark or line ending is added unless it is present in the supplied text or produced by the selected encoding.

      Parameters:
      handle - the handle argument (not null)
      offset64 - the offset64 argument
      charset - the charset argument (not null)
      textData - the textData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFileText64s

      public void writeFileText64s​(String handle, String offset64, String charset, String textData)
      Encodes textData using charset and writes the resulting bytes to handle at the byte offset supplied as decimal string offset64.

      See Supported Charsets.

      No byte-order mark or line ending is added unless it is present in the supplied text or produced by the selected encoding.

      Parameters:
      handle - the handle argument (not null)
      offset64 - the offset64 argument (not null)
      charset - the charset argument (not null)
      textData - the textData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener