Package com.chilkatsoft.chilkat2

Class Ftp2

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

Connect, secure, transfer, synchronize, and manage files on FTP servers.

Ftp2 is a comprehensive FTP and FTPS client class for applications that need reliable file transfer and remote file management. It supports connection setup, explicit and implicit TLS, passive and active data connections, uploads, downloads, directory listings, recursive operations, synchronization, proxy traversal, credential protection, and detailed diagnostics.

FTP and FTPS connections

Connect using plain FTP, explicit TLS, or implicit TLS, with control over ports, timeouts, passive mode, and IPv4/IPv6 behavior.

Upload and download files

Transfer files, text, binary data, streams, and in-memory content, with support for resume, append, and progress monitoring.

Remote file management

List directories, create and remove folders, rename files, delete files, inspect sizes and timestamps, and manage remote paths.

Recursive and sync operations

Upload or download directory trees, mirror folders, and synchronize local and remote content.

Security and credentials

Use TLS options, client certificates, secure password handling, and secret-backed credential references where appropriate.

Diagnostics and TLS details

Use LastErrorText, session logs, directory listings, and TLS negotiation details to troubleshoot server behavior.

Protocol note: Ftp2 implements FTP and FTP over TLS (FTPS). It does not implement SSH File Transfer Protocol. Use SFtp when the server requires SFTP over SSH.

Stateful session: One Ftp2 object represents one FTP session with a current remote directory, transfer type, detected server capabilities, and a cached directory listing. FTP commands and replies use the persistent control connection, while each listing, upload, or download uses a separate data connection.

Paths and encodings: Remote paths are interpreted by the FTP server and are normally relative to the current remote directory unless the server recognizes an absolute path. Remote command text uses CommandCharset, directory-listing bytes use DirListingCharset, and text-transfer methods use their own content charset argument.

Partial operations: FTP operations are not transactional. A transfer, recursive operation, deletion, or synchronization can complete some work before a later step fails. Chilkat does not generally roll back completed filesystem or server changes and does not automatically retry or resume a failed transfer unless the application explicitly uses the resume features.

Server variability: FTP extensions and server behavior vary. Features such as MLSD, EPSV, MODE Z, checksum commands, timestamp-setting commands, wildcard matching, and rename-overwrite behavior depend on the server. Inspect LastReply, LastErrorText, and the session log when behavior differs between servers.

FTPS certificate verification: RequireSslCertVerify defaults to false. Production FTPS clients should normally enable certificate-chain verification and use the expected server hostname. Certificate pinning and certificate requirements are additional checks and do not replace normal trust and hostname validation.

Tip: For FTPS troubleshooting, inspect the detailed diagnostic output and, when available, the last JSON data describing the TLS negotiation, certificate validation, protocol version, and related connection details.

For an extended overview, see Ftp2 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

    • Ftp2

      public Ftp2()
      Creates a new Ftp2 object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Set to true to request cancellation of the operation currently running on this object. Long-running network and file-transfer methods periodically check this property; methods that complete quickly may finish before the request is observed.

      A synchronous call can be cancelled from another thread by setting this property on the same object. The property is reset to false after cancellation is processed, and a stale request is cleared when a later method begins.

      Cancellation behavior: Treat this as a cancellation request, not a guarantee of immediate termination. Use the method's normal return value and diagnostic properties to determine the outcome.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

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

    • getAccount

      public String getAccount()
      Very rarely needed today: Almost all modern FTP servers rely exclusively on the USER and PASS commands for authentication and access control.

      The ACCT command is a legacy feature from early computing systems that sometimes required a separate account code for billing or resource allocation. Today, those details are usually associated directly with the user's server-side profile, making ACCT obsolete for most applications. Leave this property empty unless the server administrator or login instructions explicitly require an FTP account value.

      Specifies the FTP account string sent with the ACCT command when a server requires an account in addition to the username and password.

      Returns:
      the value of the Account property

    • setAccount

      public void setAccount​(String value)
      Sets the Account property; see getAccount().
      Parameters:
      value - the new value (not null)

    • getActivePortRangeEnd

      public int getActivePortRangeEnd()
      Specifies the last local TCP port that may be used for active-mode data connections. The default is 0. Valid nonzero values are 1 through 65535.

      The range beginning with getActivePortRangeStart() is inclusive. If ActivePortRangeStart is 0, this property is ignored and the operating system chooses an ephemeral listening port. If this value is 0 or is less than ActivePortRangeStart, Chilkat behaves as though both endpoints equal ActivePortRangeStart.

      Unavailable ports are skipped. Chilkat tries each port in the effective range until binding succeeds, and fails only after all ports have been tried. The range applies to both PORT and EPRT and may be changed while the control connection is already established.

      Active mode setting: This property is used only when getPassive() is false. Passive mode is typically preferred because it avoids the server-initiated connection back to the client that many client-side firewalls block. When active mode is required, any fixed port range must be allowed by the client-side firewall and reachable through intervening NAT.

      Returns:
      the value of the ActivePortRangeEnd property

    • setActivePortRangeEnd

      public void setActivePortRangeEnd​(int value)
      Sets the ActivePortRangeEnd property; see getActivePortRangeEnd().
      Parameters:
      value - the new value

    • getActivePortRangeStart

      public int getActivePortRangeStart()
      Specifies the first local TCP port that may be used for active-mode data connections. The default is 0. Valid nonzero values are 1 through 65535.

      When this property is 0, getActivePortRangeEnd() is ignored and Chilkat binds the listening socket to port 0, allowing the operating system to choose an available ephemeral port. When this property is nonzero, the effective range is inclusive. If the ending value is 0 or is less than the starting value, Chilkat tries only the starting port.

      For each active-mode data connection, Chilkat tries the ports in the effective range in ascending order, skipping any port for which the listening socket cannot be bound. The operation fails only after every port in the range has been tried.

      Scope: The range applies to both PORT and EPRT operation and may be changed after the FTP control connection has been established. Active mode setting: This property is used only when getPassive() is false. Passive mode is typically preferred because the client initiates both the control and data connections, making it much friendlier to client-side firewalls and NAT.

      Returns:
      the value of the ActivePortRangeStart property

    • setActivePortRangeStart

      public void setActivePortRangeStart​(int value)
      Sets the ActivePortRangeStart property; see getActivePortRangeStart().
      Parameters:
      value - the new value

    • getAllocateSize

      public long getAllocateSize()
      Rarely needed: The FTP ALLO command pre-allocates disk space on the server before an upload. It is generally needed only by certain legacy systems, such as older mainframes, that require the exact file size in advance to reserve storage. Most modern FTP servers allocate space dynamically and either ignore ALLO or do not require it. Leave this property at its default value of 0 unless the server explicitly requires pre-allocation.

      Specifies the size, in bytes, to send in an ALLO command before the next applicable upload. For example, a value of 20 sends ALLO 20. The default value of 0 disables the command.

      This is a one-shot setting. It is consumed by the next applicable upload and automatically reset to 0. It applies to normal, in-memory, text, and append uploads. A successful FTP reply indicating that allocation is unnecessary, such as reply code 202, does not prevent the upload from continuing.

      Returns:
      the value of the AllocateSize property

    • setAllocateSize

      public void setAllocateSize​(long value)
      Sets the AllocateSize property; see getAllocateSize().
      Parameters:
      value - the new value (0 .. 4294967295)

    • getAllowMlsd

      public boolean getAllowMlsd()
      Controls whether machine-readable directory listings are requested with MLSD when the server advertises support. The default is true.

      When this property is true and MLSD is advertised, Chilkat uses MLSD. Otherwise, a legacy listing is used: NLST when getPreferNlst() is true, or LIST when it is false.

      MLSD provides standardized facts such as type, size, and modification time and is generally more reliable than parsing server-specific LIST output. Facts not supplied by the server remain unavailable. When a perm fact is present, getPermissions(int) returns it rather than a UNIX-style permission string.

      Recommended setting: Keep this property enabled unless a particular server has a broken MLSD implementation. Disabling it can reduce the accuracy or availability of timestamps, sizes, and other listing information.

      Returns:
      the value of the AllowMlsd property

    • setAllowMlsd

      public void setAllowMlsd​(boolean value)
      Sets the AllowMlsd property; see getAllowMlsd().
      Parameters:
      value - the new value

    • getAuthSsl

      public boolean getAuthSsl()
      Legacy and very uncommon: AUTH SSL originated in early FTP security drafts from the era when SSL was the standard encryption protocol. For modern FTP servers, use getAuthTls() instead. Most security-conscious servers require AUTH TLS and may reject AUTH SSL to enforce current security policies and prevent protocol downgrades. This property is normally needed only for a decades-old legacy server that was never updated to support AUTH TLS. Set to true to use explicit FTP over TLS by sending AUTH SSL on the FTP control channel. The client first establishes a plain FTP control connection, receives the server greeting, and then upgrades that connection to TLS.

      The TLS upgrade is completed before USER and PASS are sent. connectOnly() performs the explicit TLS upgrade but does not log in. During connect(), Chilkat sends PBSZ and PROT as required by getDataProtection(). If the server responds with 530 Please login with USER and PASS, Chilkat logs in and automatically retries those commands.

      If the server accepts the AUTH command but rejects a required PBSZ or PROT command, the connection attempt fails. A failed connection attempt does not leave the underlying plain FTP connection open.

      AUTH SSL is the alternative explicit-TLS command used by this property. If getSsl() is true, implicit TLS takes priority. If both this property and getAuthTls() are true while Ssl is false, AuthTls takes priority and Chilkat sends AUTH TLS.

      Returns:
      the value of the AuthSsl property

    • setAuthSsl

      public void setAuthSsl​(boolean value)
      Sets the AuthSsl property; see getAuthSsl().
      Parameters:
      value - the new value

    • getAuthTls

      public boolean getAuthTls()
      Set to true to use explicit FTP over TLS by sending AUTH TLS on the FTP control channel. The client first establishes a plain FTP control connection, receives the server greeting, and then upgrades that connection to TLS. Port 21 is conventionally used.

      The TLS upgrade is completed before USER and PASS are sent. connectOnly() performs the explicit TLS upgrade but does not log in. During connect(), Chilkat sends PBSZ and PROT as required by getDataProtection(). If the server responds with 530 Please login with USER and PASS, Chilkat logs in and automatically retries those commands.

      If the server accepts the AUTH command but rejects a required PBSZ or PROT command, the connection attempt fails. A failed connection attempt does not leave the underlying plain FTP connection open.

      If getSsl() is true, implicit TLS takes priority and this property is ignored. If both AuthTls and getAuthSsl() are true while Ssl is false, AuthTls takes priority.

      AuthTls versus AuthSsl: Both properties select explicit FTPS. Their only difference is the command sent to initiate TLS: AUTH TLS for this property and AUTH SSL for AuthSsl.

      Returns:
      the value of the AuthTls property

    • setAuthTls

      public void setAuthTls​(boolean value)
      Sets the AuthTls property; see getAuthTls().
      Parameters:
      value - the new value

    • getAutoFeat

      public boolean getAutoFeat()
      Rarely changed: Leave this property at its default value of true for nearly all modern FTP servers. The FEAT command was standardized in RFC 2389 in 1998 and is broadly supported by mainstream FTP software, including FileZilla Server, vsftpd, ProFTPD, and IIS. Set it to false only for a legacy or nonconforming server that mishandles FEAT. Controls whether a FEAT command is sent automatically after login. The default is true. The response is processed to detect capabilities such as MLSD, UTF8, EPSV, MODE Z, and server-specific extensions.

      When getAutoSyst() is also true, automatic SYST is sent first. If UTF8 is advertised and getAutoOptsUtf8() is true, capability processing is followed by OPTS UTF8 ON.

      The same capability processing can be performed later by calling feat() explicitly.

      Returns:
      the value of the AutoFeat property

    • setAutoFeat

      public void setAutoFeat​(boolean value)
      Sets the AutoFeat property; see getAutoFeat().
      Parameters:
      value - the new value

    • getAutoFix

      public boolean getAutoFix()
      Controls automatic adjustment of getSsl(), getAuthSsl(), and getAuthTls() based solely on getPort(). The default is true. The only recognized ports are 21 and 990.

      Port Automatic adjustment

      21 Sets getSsl() to false. getAuthTls() and getAuthSsl() continue to determine whether explicit TLS is requested.

      990 Sets getSsl() to true and sets getAuthTls() and getAuthSsl() to false.

      Any other port Makes no changes because the intended plain, explicit-TLS, or implicit-TLS mode cannot be inferred from a custom port number.

      Scope: AutoFix does not probe the server or resolve arbitrary conflicting settings. It only applies the conventional meaning of ports 21 and 990.

      Returns:
      the value of the AutoFix property

    • setAutoFix

      public void setAutoFix​(boolean value)
      Sets the AutoFix property; see getAutoFix().
      Parameters:
      value - the new value

    • getAutoGetSizeForProgress

      public boolean getAutoGetSizeForProgress()
      Controls whether Chilkat sends a SIZE command before a download so percentage-based progress can be calculated. The default is false. Each size query adds a control-channel round trip.

      A nonzero one-shot value in getProgressMonSize() or getProgressMonSize64() supplies the expected size directly and avoids this additional query. Even when this property is false, percentage progress may be available if the server includes a usable size in its preliminary transfer reply.

      Returns:
      the value of the AutoGetSizeForProgress property

    • setAutoGetSizeForProgress

      public void setAutoGetSizeForProgress​(boolean value)
      Sets the AutoGetSizeForProgress property; see getAutoGetSizeForProgress().
      Parameters:
      value - the new value

    • getAutoOptsUtf8

      public boolean getAutoOptsUtf8()
      Controls whether OPTS UTF8 ON is sent automatically when a processed FEAT response advertises UTF8. The default is true. When UTF-8 is advertised, Chilkat sets getCommandCharset() and getDirListingCharset() to utf-8, overwriting values previously assigned by the application.

      If UTF8 is not advertised, the existing charset property values are left unchanged. This behavior applies both during automatic capability discovery and when feat() is called explicitly.

      Set to false for a server that advertises UTF-8 but rejects the option or uses a different encoding in practice.

      Returns:
      the value of the AutoOptsUtf8 property

    • setAutoOptsUtf8

      public void setAutoOptsUtf8​(boolean value)
      Sets the AutoOptsUtf8 property; see getAutoOptsUtf8().
      Parameters:
      value - the new value

    • getAutoSetUseEpsv

      public boolean getAutoSetUseEpsv()
      Recommended setting: Applications should set this property to true. The default is false in current versions, but will change to true in Chilkat v12.0.0.

      EPSV is preferred on modern networks because it supports both IPv4 and IPv6, whereas PASV cannot represent an IPv6 address. It is also more reliable through NAT and firewalls because the EPSV reply contains only a port number and relies on the address of the existing control connection. In contrast, a PASV reply includes an IP address, which can fail when a server behind NAT returns its private internal address.

      Virtually all modern FTP servers, including vsftpd, ProFTPD, FileZilla Server, and IIS, support EPSV. It was standardized in RFC 2428 in 1998 and is widely implemented.

      Controls whether getUseEpsv() is recalculated when server capabilities are processed. The default is false. Processing occurs during the initial connection when getAutoFeat() is true, or when feat() is called explicitly.

      The result is based on both the advertised capabilities and the connection context; it is not simply a copy of whether EPSV appears in the FEAT reply. For example, an IPv4 connection may retain UseEpsv = FALSE even when the server advertises EPSV. Automatic recalculation can overwrite an explicitly assigned value, and each new connection recalculates it for the new session.

      If an attempted EPSV command is rejected, Chilkat falls back to PASV for that data connection. The failed attempt is not remembered as a session-wide reason to disable future EPSV attempts.

      Returns:
      the value of the AutoSetUseEpsv property

    • setAutoSetUseEpsv

      public void setAutoSetUseEpsv​(boolean value)
      Sets the AutoSetUseEpsv property; see getAutoSetUseEpsv().
      Parameters:
      value - the new value

    • getAutoSyst

      public boolean getAutoSyst()
      Controls whether a SYST command is sent automatically after login. The default is true. The server's operating-system type can help Chilkat interpret legacy LIST output and other server-specific behavior.

      When both this property and getAutoFeat() are true, automatic SYST occurs before automatic FEAT.

      Set to false only when a particular server rejects or mishandles SYST.

      Returns:
      the value of the AutoSyst property

    • setAutoSyst

      public void setAutoSyst​(boolean value)
      Sets the AutoSyst property; see getAutoSyst().
      Parameters:
      value - the new value

    • getAutoXcrc

      public boolean getAutoXcrc()
      Controls automatic post-upload verification with the server-specific XCRC command. The default is false. When enabled and the server supports XCRC, Chilkat requests a CRC after an upload and treats a mismatch as transfer failure.

      If XCRC support is not detected, Chilkat does not send the verification command and the upload proceeds normally. This extension is not part of the core FTP standard and is not supported by every server. Capability detection normally depends on a processed FEAT response.

      Integrity scope: CRC verification can detect accidental corruption in transit or storage, but it is not a cryptographic authenticity check.

      Returns:
      the value of the AutoXcrc property

    • setAutoXcrc

      public void setAutoXcrc​(boolean value)
      Sets the AutoXcrc property; see getAutoXcrc().
      Parameters:
      value - the new value

    • getBandwidthThrottleDown

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

      Client-side download throttling is approximate because the server continues sending as permitted by TCP. The operating system's socket buffers absorb data between reads, so very small transfers may complete before the configured rate can be meaningfully enforced.

      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 value of 0 disables throttling.

      The limit is averaged over the transfer. Very small uploads may complete before the configured rate can be closely approximated.

      Returns:
      the value of the BandwidthThrottleUp property

    • setBandwidthThrottleUp

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

    • 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)

    • getCommandCharset

      public String getCommandCharset()
      Specifies the character encoding used by high-level FTP operations for commands containing non-ASCII text, including remote paths and filenames. The default is ANSI. Charset names and the keyword ANSI are case-insensitive. An unrecognized charset name is clamped to utf-8, and the getter returns utf-8. Usually changed automatically to UTF-8: Although the default value is ANSI, when the server advertises UTF-8 and getAutoOptsUtf8() is enabled, Chilkat automatically changes this property to utf-8. Nearly all modern FTP servers support UTF-8, so utf-8 is typically the effective value after connecting. If UTF-8 is not advertised, the existing value is left unchanged. What ANSI means: It does not name one specific charset. It tells Chilkat to use the system-default encoding or default system locale. Typical examples include windows-1252 on Western-language Windows systems, windows-1251 for Cyrillic, windows-1256 for Arabic, and windows-932 (Shift_JIS) for Japanese. On many modern Unix-like systems, the default locale encoding is utf-8. The actual encoding therefore depends on the computer on which the application runs.

      Changing this property after connecting affects subsequent high-level FTP commands. If a character cannot be represented in a selected single-byte encoding, the character is omitted from the transmitted command; use utf-8 to preserve full Unicode names.

      FTP filename encoding: The original FTP protocol did not define one universal encoding for path names. The client and server must use the same encoding; UTF-8 is preferred when the server supports it.

      Returns:
      the value of the CommandCharset property

    • setCommandCharset

      public void setCommandCharset​(String value)
      Sets the CommandCharset property; see getCommandCharset().
      Parameters:
      value - the new value (not null)

    • getConnectFailReason

      public int getConnectFailReason()
      Contains a numeric reason code after connect() or connectOnly() fails. Use this value for broad classification and inspect LastErrorText for detailed diagnostics.

      Code Meaning

      0 Success.

      1 The hostname is empty.

      2 DNS lookup failed.

      3 DNS lookup timed out.

      4 Cancelled by the application.

      5 Internal failure.

      6 TCP connection timed out.

      7 TCP connection was rejected or otherwise failed.

      100 Internal TLS failure.

      101 Failed to send the TLS ClientHello.

      102 An unexpected TLS handshake message was received.

      103 Failed to read the ServerHello.

      104 The server did not provide a certificate.

      105 Unexpected TLS protocol version.

      106 Server certificate verification failed.

      107 The negotiated TLS version is not allowed.

      109 Failed while reading TLS handshake messages.

      110 Failed to send the client-certificate handshake message.

      111 Failed to send the client key exchange.

      112 The client certificate private key is not accessible.

      113 Failed to send client certificate verification.

      114 Failed to send ChangeCipherSpec.

      115 Failed to send the Finished handshake message.

      116 The server Finished message is invalid.

      200 Connected, but the FTP greeting was not received.

      201 The AUTH TLS or AUTH SSL upgrade failed.

      300 An asynchronous operation is already in progress.

      301 FTP authentication failed.

      A successful connection sets this property to 0. An authentication failure can set it to 301 while getConnectVerified() remains true, because the TCP and FTP connection succeeded before the login was rejected.

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

    • getConnectTimeout

      public int getConnectTimeout()
      Specifies the maximum number of seconds to wait for a remote endpoint to accept a TCP connection. The default is 30. A value of 0 or any negative value waits indefinitely.

      This timeout applies whenever Ftp2 establishes a TCP connection, including the FTP control connection, FTP data connections, and connections to configured proxy servers.

      It covers only TCP connection establishment. It does not apply to TLS handshakes, FTP greetings or replies, authentication, file data, or any other communication after the TCP connection has been accepted.

      Returns:
      the value of the ConnectTimeout property

    • setConnectTimeout

      public void setConnectTimeout​(int value)
      Sets the ConnectTimeout property; see getConnectTimeout().
      Parameters:
      value - the new value

    • getConnectVerified

      public boolean getConnectVerified()
      Indicates whether the TCP connection to the FTP server was successfully established during the most recent connection attempt. It does not indicate that FTP authentication succeeded; see getLoginVerified().

      This is a verification result, not a current-socket-state property. It remains true after disconnect() if the preceding connection was successfully established.

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

    • getCrlfMode

      public int getCrlfMode()
      Controls line-ending conversion when downloading in ASCII transfer mode. The default is 0.

      Value Downloaded text

      0 Leaves line endings as received.

      1 Converts line endings to CRLF.

      2 Converts line endings to LF.

      3 Converts line endings to CR.

      Binary mode: This property has no effect on binary transfers. Use binary mode for files whose bytes must be preserved exactly.

      Returns:
      the value of the CrlfMode property

    • setCrlfMode

      public void setCrlfMode​(int value)
      Sets the CrlfMode property; see getCrlfMode().
      Parameters:
      value - the new value

    • getCurBytesReceived

      public long getCurBytesReceived()
      Returns the number of bytes received by the current or most recently completed FTP download as a 32-bit unsigned integer. The value is updated while the transfer is in progress and may be read from another thread to display progress. A subsequent upload does not clear the retained download count.
      Returns:
      the value of the CurBytesReceived property (read-only)

    • getCurBytesReceived64

      public long getCurBytesReceived64()
      Returns the number of bytes received by the current or most recently completed FTP download as a 64-bit integer. The value is updated while the transfer is in progress and may be read from another thread to display progress. A subsequent upload does not clear the retained download count.
      Returns:
      the value of the CurBytesReceived64 property (read-only)

    • getCurBytesReceivedStr

      public String getCurBytesReceivedStr()
      Returns the number of bytes received by the current or most recently completed FTP download as a decimal string. The value is updated while the transfer is in progress and may be read from another thread to display progress. A subsequent upload does not clear the retained download count.
      Returns:
      the value of the CurBytesReceivedStr property (read-only)

    • getCurBytesSent

      public long getCurBytesSent()
      Returns the number of bytes sent by the current or most recently completed FTP upload as a 32-bit unsigned integer. The value is updated while the transfer is in progress and may be read from another thread to display progress. A subsequent download does not clear the retained upload count.
      Returns:
      the value of the CurBytesSent property (read-only)

    • getCurBytesSent64

      public long getCurBytesSent64()
      Returns the number of bytes sent by the current or most recently completed FTP upload as a 64-bit integer. The value is updated while the transfer is in progress and may be read from another thread to display progress. A subsequent download does not clear the retained upload count.
      Returns:
      the value of the CurBytesSent64 property (read-only)

    • getCurBytesSentStr

      public String getCurBytesSentStr()
      Returns the number of bytes sent by the current or most recently completed FTP upload as a decimal string. The value is updated while the transfer is in progress and may be read from another thread to display progress. A subsequent download does not clear the retained upload count.
      Returns:
      the value of the CurBytesSentStr property (read-only)

    • getDataProtection

      public String getDataProtection()
      Specifies the protection level for FTP data connections. The value is compared case-insensitively. The default is control.

      Value Behavior

      control Data connections use the same protection state as the control connection. If the control connection is unencrypted, no PBSZ or PROT commands are sent.

      clear Data connections are requested as unencrypted. If the control connection is also unencrypted, no PBSZ or PROT commands are sent. If the control connection uses TLS, Chilkat sends PBSZ 0 followed by PROT C. If the server rejects PROT C but accepts PROT P, Chilkat falls back to private data protection.

      private Data connections are protected with TLS. For an encrypted control connection, Chilkat sends PBSZ 0 followed by PROT P.

      connect() sends the required PBSZ and PROT commands. If the server requires login first and replies with 530 Please login with USER and PASS, Chilkat authenticates and automatically retries them. A required protection setup fails only when no acceptable protection level can be established.

      Control and data channels: FTP uses one long-lived control connection and a separate data connection for each listing, upload, or download. FTPS can protect these channels independently.

      Returns:
      the value of the DataProtection property

    • setDataProtection

      public void setDataProtection​(String value)
      Sets the DataProtection property; see getDataProtection().
      Parameters:
      value - the new value (not null)

    • getDirListingCharset

      public String getDirListingCharset()
      Specifies the character encoding used only to decode directory-listing and related server-response bytes. It applies to responses from LIST, NLST, and MLSD. It does not affect commands, remote paths, filenames, usernames, passwords, or other text sent to the server.

      The default is ANSI. Charset names and the keyword ANSI are case-insensitive. ANSI means the platform's system-default single-byte encoding or default system locale; on Windows, this is the active code page (ACP).

      What ANSI means: It does not name one specific charset. It tells Chilkat to use the system-default encoding or default system locale. Typical examples include windows-1252 on Western-language Windows systems, windows-1251 for Cyrillic, windows-1256 for Arabic, and windows-932 (Shift_JIS) for Japanese. On many modern Unix-like systems, the default locale encoding is utf-8. The actual encoding therefore depends on the computer on which the application runs.

      Using the wrong encoding can produce incorrectly decoded names without causing the listing operation itself to fail. When getAutoOptsUtf8() is enabled and UTF-8 support is advertised, Chilkat changes this property to utf-8, even if the application previously assigned another value. If UTF-8 is not advertised, the existing value is left unchanged.

      Returns:
      the value of the DirListingCharset property

    • setDirListingCharset

      public void setDirListingCharset​(String value)
      Sets the DirListingCharset property; see getDirListingCharset().
      Parameters:
      value - the new value (not null)

    • getDownloadTransferRate

      public int getDownloadTransferRate()
      Returns the current average download rate in bytes per second. The value is updated during synchronous and asynchronous downloads and describes the download in progress or the most recently completed download. A subsequent upload does not clear the retained download rate.
      Returns:
      the value of the DownloadTransferRate property (read-only)

    • getEnableSecrets

      public boolean getEnableSecrets()
      Controls automatic resolution of credential values from secure operating-system storage. The default is false. When enabled, supported password properties may contain a secret specification beginning with !! instead of the literal password. 
      !![appName|]service[|domain]|username

      Secret specifications are supported by getPassword(), getHttpProxyPassword(), getProxyPassword(), and getSocksPassword(). Chilkat resolves them through Windows Credential Manager on Windows or Apple Keychain on macOS.

      Credential handling: This feature avoids embedding plaintext credentials in source code or configuration. Access to the secret still depends on the permissions of the process and operating-system account.

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

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

    • getForcePortIpAddress

      public String getForcePortIpAddress()
      Specifies the IPv4 address advertised to the server for active-mode data connections. This property affects both PORT and EPRT. Supply a numeric IPv4 address, the keyword control, or an IPv4 address prefixed with bind-. IPv6 values are not accepted. Keywords and prefixes are case-insensitive.
      • control uses the local IPv4 address of the established FTP control socket.
      • bind-192.0.2.10 advertises the address and also binds the local data-listener socket to that address.
      • A plain IPv4 address changes the address sent in PORT or EPRT without explicitly binding the listener to that address.

      If getClientIpAddress() is set, this property should specify the same local address. When a bind- value is used with getActivePortRangeStart() and getActivePortRangeEnd(), Chilkat binds to the specified address while searching the effective range for an available port.

      Active mode setting: This property is used only when getPassive() is false. Passive mode is typically preferred because the client initiates both the control and data connections, making it much friendlier to client-side firewalls and NAT. NAT caution: The advertised address must be reachable from the FTP server. Incorrect active-mode addressing commonly causes the control command to succeed while the subsequent data connection fails.

      Returns:
      the value of the ForcePortIpAddress property

    • setForcePortIpAddress

      public void setForcePortIpAddress​(String value)
      Sets the ForcePortIpAddress property; see getForcePortIpAddress().
      Parameters:
      value - the new value (not null)

    • getGreeting

      public String getGreeting()
      Contains the initial FTP server greeting received for the most recent connection immediately after the TCP or implicit-TLS connection was established. It normally begins with reply code 220 and may include server identification or policy information.

      The value remains available after disconnect().

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

    • getHasModeZ

      public boolean getHasModeZ()
      Indicates whether the FTP server advertised support for MODE Z, which compresses FTP data streams using the DEFLATE algorithm.

      This property becomes meaningful after Chilkat has processed a successful FEAT response, either automatically because getAutoFeat() is true or through an explicit call to feat(). Before capability discovery, a value of false does not establish that the server lacks MODE Z support.

      Call setModeZ() after connecting to enable or disable compressed transfer mode.

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

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck callbacks during methods that support periodic cancellation checks. The default is 0, which disables these callbacks.

      Smaller values can improve cancellation responsiveness but increase callback overhead. Methods that complete quickly may not generate a callback.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

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

    • getHostname

      public String getHostname()
      Specifies the FTP server hostname or numeric IPv4/IPv6 address. Do not include a URL scheme, path, or port; configure the port separately with Port.
      Returns:
      the value of the Hostname property

    • setHostname

      public void setHostname​(String value)
      Sets the Hostname property; see getHostname().
      Parameters:
      value - the new value (not null)

    • getHttpProxyAuthMethod

      public String getHttpProxyAuthMethod()
      Specifies the authentication method used with an HTTP proxy. Supported values are Basic and NTLM. Leave empty when the proxy does not require 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 Windows domain used for NTLM authentication to the HTTP proxy. It is ignored for Basic authentication and may be left empty when the username already includes the required domain information.
      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 FTP control connection. Leave empty to connect directly.
      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 to the HTTP proxy. It is used together with HttpProxyUsername and HttpProxyAuthMethod.
      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 TCP port of the HTTP proxy. Common values include 8080 and 3128, but the correct value is determined by the proxy configuration.
      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 to the HTTP proxy. Leave empty when the proxy allows unauthenticated connections.
      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 no control-channel response or forward upload progress is observed. The default is 60000. A value of 0 or any negative value waits indefinitely.

      During an upload, the same limit applies when the operating-system send buffer remains full because the server is not consuming data.

      Returns:
      the value of the IdleTimeoutMs property

    • setIdleTimeoutMs

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

    • getIsConnected

      public boolean getIsConnected()
      Deprecated. Indicates whether the object appears to be connected and authenticated. Reading this property may send NOOP to test the session. Use checkConnection() instead.
      Returns:
      the value of the IsConnected property (read-only)

    • getKeepSessionLog

      public boolean getKeepSessionLog()
      Controls collection of an in-memory FTP protocol log. When enabled, commands and server replies are available in getSessionLog(). Use clearSessionLog() to discard previously collected text.
      Returns:
      the value of the KeepSessionLog property

    • setKeepSessionLog

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

    • getLargeFileMeasures

      public boolean getLargeFileMeasures()
      Controls an additional keepalive measure for very long uploads and downloads. The default is false. When enabled, Chilkat sends NOOP on the FTP control channel once per minute while a long-running file transfer is in progress.

      This helps prevent the otherwise idle control connection from being closed by the server, a firewall, or a NAT device while file data continues on the separate data connection.

      FTP connection model: File contents travel over a data connection, while FTP commands and replies use the control connection. During a long transfer, the control connection may appear idle even though the data connection remains active.

      Returns:
      the value of the LargeFileMeasures property

    • setLargeFileMeasures

      public void setLargeFileMeasures​(boolean value)
      Sets the LargeFileMeasures property; see getLargeFileMeasures().
      Parameters:
      value - the new value

    • getLastReply

      public String getLastReply()
      Contains the most recent FTP control-channel reply, including its three-digit status code and message. Examples include 250 Directory successfully changed. and 550 Failed to change directory.

      The value is updated by successful as well as failed commands. After disconnect(), it normally contains the server's reply to QUIT, such as 221 Goodbye.. Some replies are multiline; use this property together with the method return value and LastErrorText when diagnosing a failure.

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

    • getListOption

      public String getListOption()
      Specifies an option string appended literally to the legacy LIST command, such as -a. For example, setting this property to -a sends LIST -a. Chilkat does not interpret the option locally. It has no effect when getAllowMlsd() causes MLSD to be used or when getPreferNlst() causes NLST to be used.

      LIST options and output formats are not standardized by FTP. Many UNIX-like servers pass the option to an underlying ls implementation, while other servers may reject or interpret it differently.

      Returns:
      the value of the ListOption property

    • setListOption

      public void setListOption​(String value)
      Sets the ListOption property; see getListOption().
      Parameters:
      value - the new value (not null)

    • getListPattern

      public String getListPattern()
      Specifies the case-insensitive wildcard pattern applied to the cached listing of the current remote directory. The default is *. It affects methods such as getDirCount(), getFilename(int), getIsDirectory(int), getSize(int), and the listing timestamp methods.

      Chilkat retrieves the full directory listing and applies this pattern locally; the pattern is not appended to LIST, NLST, or MLSD. For example, *.txt also matches a name such as UPPER.TXT.

      Specify only a name pattern, such as *.txt. To list subdir/*.txt, first call changeRemoteDir(String) for subdir, then set this property to *.txt.

      Listing cache: Changing this property invalidates the cached directory listing, so the next indexed listing call retrieves a fresh listing from the server.

      Returns:
      the value of the ListPattern property

    • setListPattern

      public void setListPattern​(String value)
      Sets the ListPattern property; see getListPattern().
      Parameters:
      value - the new value (not null)

    • getLoginVerified

      public boolean getLoginVerified()
      Indicates whether FTP authentication succeeded during the most recent login attempt. A TCP connection may be established even when this property is false; for example, rejected credentials leave getConnectVerified() true and this property false.

      This is a verification result, not a current-socket-state property. It remains true after disconnect() if the preceding session was successfully authenticated.

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

    • getPartialTransfer

      public boolean getPartialTransfer()
      Indicates whether the most recent download method received some, but not all, of the remote file. It is false when no data was received or when the complete file was received.

      This property helps distinguish a mid-transfer failure from a failure that occurred before any file data arrived.

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

    • getPassive

      public boolean getPassive()
      Selects the FTP data-connection mode. The default is true for passive mode. Set to false for active mode.

      Mode Connection direction

      Passive The server listens and the client connects to the server for each data transfer.

      Active The client listens and the server connects back to the client.

      Typical choice: Passive mode. Passive mode is typically used because it is much friendlier to client-side firewalls and NAT (Network Address Translation). In active mode, the server attempts to initiate a data connection back to the client, which many client-side firewalls block. In passive mode, the client initiates both the control and data connections to the server.

      Returns:
      the value of the Passive property

    • setPassive

      public void setPassive​(boolean value)
      Sets the Passive property; see getPassive().
      Parameters:
      value - the new value

    • getPassiveUseHostAddr

      public boolean getPassiveUseHostAddr()
      Controls how the address returned by PASV is handled. The default is true. When enabled, Chilkat ignores the IP address embedded in the server's PASV reply and connects to the control connection's server address using only the returned port.

      This avoids private or otherwise unreachable addresses returned by FTP servers behind NAT, especially when TLS prevents a network device from rewriting the reply.

      Returns:
      the value of the PassiveUseHostAddr property

    • setPassiveUseHostAddr

      public void setPassiveUseHostAddr​(boolean value)
      Sets the PassiveUseHostAddr property; see getPassiveUseHostAddr().
      Parameters:
      value - the new value

    • getPassword

      public String getPassword()
      Specifies the password used for FTP authentication. For anonymous FTP, this is commonly an email address or arbitrary identifying string. Applications that already store the password in a SecureString should use setSecurePassword(SecureString) instead.
      Returns:
      the value of the Password property

    • setPassword

      public void setPassword​(String value)
      Sets the Password property; see getPassword().
      Parameters:
      value - the new value (not null)

    • getPercentDoneScale

      public int getPercentDoneScale()
      Specifies the integer value that represents 100 percent in PercentDone callbacks. The default is 100. For example, a scale of 1000 allows one-tenth-percent resolution, where callback value 453 represents 45.3 percent.

      The value is limited to the range 10 through 100000. This property is relevant only in environments that support event callbacks and only for operations whose total work 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

    • getPort

      public int getPort()
      Specifies the FTP server port. Port 21 is conventionally used for plain FTP or explicit FTPS, and port 990 is conventionally used for implicit FTPS.

      When getAutoFix() is true, only these two port numbers cause automatic changes to getSsl(), getAuthSsl(), and getAuthTls(). A custom port leaves all three TLS-mode properties unchanged.

      Returns:
      the value of the Port property

    • setPort

      public void setPort​(int value)
      Sets the Port property; see getPort().
      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

    • getPreferNlst

      public boolean getPreferNlst()
      Controls whether NLST is preferred over LIST when a legacy directory listing is required. The default is false. This property is consulted only when getAllowMlsd() does not result in MLSD being used.

      NLST generally returns names only. Do not rely on indexed sizes, timestamps, ownership, group, or permission information after an NLST listing. Because NLST does not reliably identify entry types, Chilkat may send additional commands, such as directory-change tests, to determine which names are directories.

      When to use: Enable this only for a server whose LIST output truncates or corrupts names. Keep getAllowMlsd() enabled whenever possible because MLSD is the standardized machine-readable listing command.

      Returns:
      the value of the PreferNlst property

    • setPreferNlst

      public void setPreferNlst​(boolean value)
      Sets the PreferNlst property; see getPreferNlst().
      Parameters:
      value - the new value

    • getProgressMonSize

      public int getProgressMonSize()
      Specifies the expected size, in bytes, of the next file downloaded by getFile(String, String) when the size is not otherwise known. Chilkat uses the value to calculate percentage progress.

      This is a one-shot setting. It is consumed by the next applicable download and automatically reset to 0. Set it immediately before the download. When a nonzero value is supplied, Chilkat does not need the additional size query controlled by getAutoGetSizeForProgress().

      If this property is zero, percentage progress may still be available when the server's preliminary transfer reply includes the file size.

      Returns:
      the value of the ProgressMonSize property

    • setProgressMonSize

      public void setProgressMonSize​(int value)
      Sets the ProgressMonSize property; see getProgressMonSize().
      Parameters:
      value - the new value

    • getProgressMonSize64

      public long getProgressMonSize64()
      The 64-bit form of getProgressMonSize(). Specifies the expected size, in bytes, of the next download when the value may exceed the 32-bit integer range. It is consumed by the next applicable download and automatically reset to 0.
      Returns:
      the value of the ProgressMonSize64 property

    • setProgressMonSize64

      public void setProgressMonSize64​(long value)
      Sets the ProgressMonSize64 property; see getProgressMonSize64().
      Parameters:
      value - the new value

    • getProxyHostname

      public String getProxyHostname()
      Specifies the hostname or IP address of a traditional FTP application proxy or firewall. This is distinct from an HTTP CONNECT proxy and from a SOCKS proxy. The login sequence is selected by ProxyMethod.
      Returns:
      the value of the ProxyHostname property

    • setProxyHostname

      public void setProxyHostname​(String value)
      Sets the ProxyHostname property; see getProxyHostname().
      Parameters:
      value - the new value (not null)

    • getProxyMethod

      public int getProxyMethod()
      Selects the login sequence required by a traditional FTP proxy or firewall. The default is 0, meaning no FTP proxy. Configure getProxyHostname(), getProxyPort(), and the required proxy credentials before connecting.

      Value Sequence sent

      1 — SITE 

      USER ProxyUsername
 PASS ProxyPassword
 SITE Hostname
 USER Username
 PASS Password

      2 — USER user@site 

      USER Username@Hostname:Port
 PASS Password

      3 — USER with proxy login 

      USER ProxyUsername
 PASS ProxyPassword
 USER Username@Hostname:Port
 PASS Password

      4 — USER/PASS/ACCT 

      USER Username@Hostname:Port ProxyUsername
 PASS Password
 ACCT ProxyPassword

      5 — OPEN 

      USER ProxyUsername
 PASS ProxyPassword
 OPEN Hostname
 USER Username
 PASS Password

      6 — firewall ID 

      USER ProxyUsername@Hostname
 USER Username
 PASS Password

      7 

      USER ProxyUsername
 USER ProxyPassword
 SITE Hostname:Port
 USER Username
 PASS Password

      8 

      USER Username@ProxyUsername@Hostname
 PASS Password@ProxyPassword

      9 

      ProxyUsername
 ProxyPassword
 Username
 Password

      Server-specific feature: These sequences describe historical FTP firewall conventions, not one standardized proxy protocol. Use the value required by the proxy administrator.

      Returns:
      the value of the ProxyMethod property

    • setProxyMethod

      public void setProxyMethod​(int value)
      Sets the ProxyMethod property; see getProxyMethod().
      Parameters:
      value - the new value

    • getProxyPassword

      public String getProxyPassword()
      Specifies the password used to authenticate to a traditional FTP proxy or firewall. Its placement in the login exchange depends on ProxyMethod.
      Returns:
      the value of the ProxyPassword property

    • setProxyPassword

      public void setProxyPassword​(String value)
      Sets the ProxyPassword property; see getProxyPassword().
      Parameters:
      value - the new value (not null)

    • getProxyPort

      public int getProxyPort()
      Specifies the TCP port on which the traditional FTP proxy or firewall accepts connections.
      Returns:
      the value of the ProxyPort property

    • setProxyPort

      public void setProxyPort​(int value)
      Sets the ProxyPort property; see getProxyPort().
      Parameters:
      value - the new value

    • getProxyUsername

      public String getProxyUsername()
      Specifies the username used to authenticate to a traditional FTP proxy or firewall. Its placement in the login exchange depends on ProxyMethod.
      Returns:
      the value of the ProxyUsername property

    • setProxyUsername

      public void setProxyUsername​(String value)
      Sets the ProxyUsername property; see getProxyUsername().
      Parameters:
      value - the new value (not null)

    • getReadTimeout

      public int getReadTimeout()
      Specifies the maximum number of seconds that a data connection may remain without receiving another byte. The default is 60. A value of 0 or any negative value waits indefinitely.

      This is an inactivity timeout, not a limit on total transfer duration. Receiving any data, even a single byte, resets the timer and begins a new full timeout interval. A large download may therefore continue indefinitely as long as data keeps arriving within the configured interval.

      Returns:
      the value of the ReadTimeout property

    • setReadTimeout

      public void setReadTimeout​(int value)
      Sets the ReadTimeout property; see getReadTimeout().
      Parameters:
      value - the new value

    • getRequireSslCertVerify

      public boolean getRequireSslCertVerify()
      Controls verification of the FTP server's TLS certificate chain.

      Value Behavior

      false (default) A connection is not rejected solely because normal certificate-chain verification fails.

      true The connection fails when the certificate is expired, is not yet valid, its signature is invalid, or its chain cannot be verified to a trusted root.

      Certificate-chain verification is separate from hostname matching and public-key pinning. Hostname matching, when required, is enforced independently even when this property is false. getTlsPinSet() supplements rather than replaces normal certificate verification.

      The hostname used for the TLS connection is also used for Server Name Indication (SNI) and certificate hostname comparison.

      Returns:
      the value of the RequireSslCertVerify property

    • setRequireSslCertVerify

      public void setRequireSslCertVerify​(boolean value)
      Sets the RequireSslCertVerify property; see getRequireSslCertVerify().
      Parameters:
      value - the new value

    • getRestartNext

      public boolean getRestartNext()
      Set to true to request that the next applicable upload or download resume from existing content instead of starting over. Unrelated FTP commands do not consume the setting. The next applicable transfer consumes it and automatically resets it to false.

      For a resumed upload, Chilkat obtains the existing remote size, begins reading the local content at that offset, and appends the remaining bytes. For a resumed download, Chilkat uses the existing destination length as the REST offset and appends the remaining remote bytes.

      The setting applies to the ordinary file, BinData, and StringBuilder upload and download methods, including putFile(String, String), putFileBd(BinData, String), putFileSb(StringBuilder, String, boolean, String), getFile(String, String), getFileBd(String, BinData), and getFileSb(String, String, StringBuilder).

      Resume requires compatible server support and a correct partial local or remote file. The application should verify that the existing content belongs to the same file version before resuming.

      Returns:
      the value of the RestartNext property

    • setRestartNext

      public void setRestartNext​(boolean value)
      Sets the RestartNext property; see getRestartNext().
      Parameters:
      value - the new value

    • getSessionLog

      public String getSessionLog()
      Contains the in-memory FTP session log collected while getKeepSessionLog() is true. The log includes protocol commands and server replies and is useful for troubleshooting. Passwords and other sensitive information may appear; handle the text accordingly.
      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 hostname or IP address of the SOCKS proxy. It 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 password for SOCKS5 username/password authentication. It is ignored for SOCKS4, which has no password-authentication field.
      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. It 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 user identifier. SOCKS5 may use it with password authentication; SOCKS4 sends it as the protocol user ID. It is used only when getSocksVersion() is 4 or 5.
      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 SOCKS proxy usage.

      Value Behavior

      0 Default. Connect directly without a SOCKS proxy.

      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

    • getSsl

      public boolean getSsl()
      Set to true to use implicit FTP over TLS. TLS begins immediately after the TCP connection is established, before the FTP greeting is received. Port 990 is conventionally used for implicit FTPS.

      This property has priority over getAuthTls() and getAuthSsl(). If Ssl is true, implicit TLS is used even when either explicit-TLS property is also true. connectOnly() performs the implicit TLS handshake but does not send USER or PASS.

      TLS-mode precedence: Ssl has highest priority. When it is false, AuthTls takes priority over AuthSsl. When all three properties are false, plain FTP is used. Protocol distinction: FTPS is FTP protected by TLS. SFTP is a different protocol carried by SSH and is implemented by the SFtp class.

      Returns:
      the value of the Ssl property

    • setSsl

      public void setSsl​(boolean value)
      Sets the Ssl property; see getSsl().
      Parameters:
      value - the new value

    • getSslAllowedCiphers

      public String getSslAllowedCiphers()
      Restricts the cipher suites and selected TLS security requirements offered for FTP TLS connections.

      Leave this property empty to allow all cipher suites implemented by the installed Chilkat version. To restrict negotiation, provide a comma-separated list in preference order, for example: 

      TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

      The server chooses from the cipher suites offered by the client; the client cannot force a suite the server does not support.

      The list may also contain these policy keywords:

      • rsa1024 or rsa2048 to require a minimum RSA server-key size.
      • secure-renegotiation to require secure TLS renegotiation.
      • best-practices to use the security policy recommended by the installed Chilkat version.

      Legacy keywords such as aes256-cbc, aes128-cbc, 3des-cbc, and rc4 remain recognized for compatibility, but explicitly listing acceptable suites is preferred.

      Returns:
      the value of the SslAllowedCiphers property

    • setSslAllowedCiphers

      public void setSslAllowedCiphers​(String value)
      Sets the SslAllowedCiphers property; see getSslAllowedCiphers().
      Parameters:
      value - the new value (not null)

    • getSslProtocol

      public String getSslProtocol()
      Selects the TLS protocol version or minimum version allowed for secure FTP connections.

      The complete list of accepted values is: 

      default
 TLS 1.3
 TLS 1.2
 TLS 1.1
 TLS 1.0
 SSL 3.0
 TLS 1.3 or higher
 TLS 1.2 or higher
 TLS 1.1 or higher
 TLS 1.0 or higher

      The default is default, which allows Chilkat to negotiate a protocol supported by both client and server. A minimum-version setting is generally more interoperable than requiring one exact version.

      Returns:
      the value of the SslProtocol property

    • setSslProtocol

      public void setSslProtocol​(String value)
      Sets the SslProtocol property; see getSslProtocol().
      Parameters:
      value - the new value (not null)

    • getSslServerCertVerified

      public boolean getSslServerCertVerified()
      Indicates whether the FTP server certificate chain was successfully verified for the current or most recent TLS connection.

      This property reports certificate-chain verification only. It does not report hostname matching or public-key pinning. If hostname matching or getTlsPinSet() pinning is required and the check fails, the TLS connection itself fails.

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

    • getSyncCreateAllLocalDirs

      public boolean getSyncCreateAllLocalDirs()
      Controls whether download synchronization creates empty remote directories on the local filesystem. The default is true. When false, a local directory is created only when it is needed to contain a downloaded file.
      Returns:
      the value of the SyncCreateAllLocalDirs property

    • setSyncCreateAllLocalDirs

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

    • getSyncMustMatch

      public String getSyncMustMatch()
      Specifies a semicolon-separated list of case-insensitive wildcard patterns for files that are eligible for synchronization and tree operations. For example: *.xml;*.txt;*.csv.

      When nonempty, a file must match at least one pattern. Matching is performed against the file's basename, not its relative path. Thus keep.txt can match a file in any traversed subdirectory, while a pattern such as subdir/*.txt does not match a nested relative path.

      This filter applies to synchronization methods and also to putTree(String), downloadTree(String), and dirTreeXml().

      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 case-insensitive wildcard patterns for directories that synchronization methods are allowed to enter. For example: src;data_*;reports. When nonempty, a directory must match at least one pattern before its contents are traversed.
      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 case-insensitive wildcard patterns for files that must be excluded from synchronization and tree operations. For example: *.tmp;*.bak;~*.

      Matching is performed against the file's basename, not its relative path. Exclusion is applied in addition to getSyncMustMatch().

      This filter also applies to putTree(String), downloadTree(String), and dirTreeXml().

      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 case-insensitive wildcard patterns for directories that synchronization methods must not enter. For example: .git;temp;archive_*. Exclusion is applied in addition to SyncMustMatchDir.
      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)

    • getSyncPreview

      public String getSyncPreview()
      Contains the preview produced by syncRemoteTree2(String, int, boolean, boolean) when ARG4 is true. Each CRLF-delimited line is an absolute local path that would be uploaded if preview mode were disabled.

      The value is replaced at the start of each preview operation. It is empty when no files qualify, when the preview fails, or when ARG2 is not a valid synchronization mode. A subsequent non-preview synchronization operation also clears it. Unrelated methods do not clear the most recent preview.

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

    • getTlsCipherSuite

      public String getTlsCipherSuite()
      Contains the cipher suite negotiated for the current or most recent successful TLS connection, such as TLS_AES_256_GCM_SHA384. It is empty before a TLS session has been established or after a failed attempt that produced no negotiated suite.
      Returns:
      the value of the TlsCipherSuite property (read-only)

    • getTlsPinSet

      public String getTlsPinSet()
      Specifies one or more expected Subject Public Key Info (SPKI) fingerprints for TLS public-key pinning. If none of the configured pins matches the server certificate, the TLS handshake fails.

      Pinning supplements normal certificate-chain verification; it does not replace it. A matching pin does not make an expired or otherwise invalid certificate acceptable. When a pin set is configured, pin matching is enforced even if getRequireSslCertVerify() is false.

      The format is: 

      hashAlgorithm, encoding, fingerprint1, fingerprint2, ...

      Example: 

      sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE=

      Supported hash algorithms include sha1, sha256, sha384, sha512, md2, md5, haval, ripemd128, ripemd160, ripemd256, and ripemd320. Supported encodings include base64, hex, and other Chilkat-supported binary encodings.

      FTP connection scope: Pin matching is enforced for every TLS connection established by this object, including the FTPS control connection and all TLS-protected data connections.

      Returns:
      the value of the TlsPinSet property

    • setTlsPinSet

      public void setTlsPinSet​(String value)
      Sets the TlsPinSet property; see getTlsPinSet().
      Parameters:
      value - the new value (not null)

    • getTlsVersion

      public String getTlsVersion()
      Contains the protocol version negotiated for the current or most recent successful TLS connection, such as TLS 1.2 or TLS 1.3. It is empty when no TLS session has been established.
      Returns:
      the value of the TlsVersion property (read-only)

    • getUncommonOptions

      public String getUncommonOptions()
      Provides a comma-separated list of compatibility options for uncommon platform or server requirements. The default is empty and should normally remain empty.

      Keyword Effect

      OpenNonExclusive On Windows, opens a local download file without exclusive sharing so another process may access it while data is being written.

      ProtectFromVpn On Android, requests that FTP sockets bypass an active VPN.

      EnableTls13 Compatibility switch that explicitly enables offering TLS 1.3 in builds where it is not already enabled by policy.

      DisableTls13 Prevents TLS 1.3 negotiation for compatibility with a problematic peer.

      NoPreserveFileTime Leaves downloaded files with the current local time instead of attempting to preserve the remote modification time.

      Use sparingly: These options alter low-level behavior and may be platform-specific. Configure one only when the documented default causes a known interoperability problem.

      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)

    • getUploadTransferRate

      public int getUploadTransferRate()
      Returns the current average upload rate in bytes per second. The value is updated during synchronous and asynchronous uploads and describes the upload in progress or the most recently completed upload. A subsequent download does not clear the retained upload rate.
      Returns:
      the value of the UploadTransferRate property (read-only)

    • getUseEpsv

      public boolean getUseEpsv()
      Controls whether passive data connections first use EPSV instead of PASV. The default is false. This property has no effect when getPassive() is false.

      If EPSV is rejected, Chilkat automatically retries the data connection using PASV. The rejection does not disable EPSV for the remainder of the session, so a later passive data connection may try EPSV again.

      getAutoSetUseEpsv() can change this property automatically when server capabilities are examined.

      Compatibility: EPSV avoids embedding an IP address in the server reply and is the passive-mode command defined for IPv6. Some legacy FTP-aware firewalls mishandle it.

      Returns:
      the value of the UseEpsv property

    • setUseEpsv

      public void setUseEpsv​(boolean value)
      Sets the UseEpsv property; see getUseEpsv().
      Parameters:
      value - the new value

    • getUsername

      public String getUsername()
      Specifies the FTP login name. The default is anonymous. Set it to an empty string to have connect() establish the connection without performing authentication; authentication may then be handled separately with loginAfterConnectOnly().
      Returns:
      the value of the Username property

    • setUsername

      public void setUsername​(String value)
      Sets the Username property; see getUsername().
      Parameters:
      value - the new value (not null)

    • appendFile

      public void appendFile​(String localFilePath, String remoteFilePath)
      Appends the contents of the local file at localFilePath to the remote file at remoteFilePath. Both arguments are paths in their respective local and remote filesystems.

      Uses the FTP APPE command. On servers with normal APPE behavior, a missing remote file is created and an existing file is extended. A failed or interrupted append can leave the bytes already accepted by the server in place; the operation is not transactional.

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

    • appendFileBd

      public void appendFileBd​(String remoteFilename, BinData bd)
      Appends the bytes in the BinData object bd to the remote file at remoteFilename. No text encoding or line-ending conversion is performed.

      Uses the FTP APPE command. On servers with normal APPE behavior, a missing remote file is created and an existing file is extended. A failed or interrupted append can leave the bytes already accepted by the server in place; the operation is not transactional.

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

    • appendFileFromTextData

      public void appendFileFromTextData​(String remoteFilename, String textData, String charset)
      Encodes the text in textData using the character encoding named by charset and appends the resulting bytes to the remote file at remoteFilename.

      This method controls the encoding of the file content. The encoding used for the remote filename itself is controlled separately by getCommandCharset().

      Uses the FTP APPE command. On servers with normal APPE behavior, a missing remote file is created and an existing file is extended. A failed or interrupted append can leave the bytes already accepted by the server in place; the operation is not transactional.

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

    • appendFileSb

      public void appendFileSb​(String remoteFilename, StringBuilder sb, String charset)
      Encodes the text in the StringBuilder sb using the charset named by charset and appends the resulting bytes to the remote file at remoteFilename.

      Uses the FTP APPE command. On servers with normal APPE behavior, a missing remote file is created and an existing file is extended. A failed or interrupted append can leave the bytes already accepted by the server in place; the operation is not transactional.

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

    • changeRemoteDir

      public void changeRemoteDir​(String remoteDirPath)
      Changes the current working directory on the FTP server to remoteDirPath. A relative path is resolved from the current remote directory; an absolute path is interpreted according to the server's path syntax.

      Chilkat sends one CWD command containing remoteDirPath. It does not split a multi-level path into separate directory changes. A server may accept a path such as a/b/c in one command or may require the application to change one level at a time.

      If the CWD command fails, the current remote directory remains unchanged.

      Current directory: Many Ftp2 methods operate relative to the current remote directory. Use getCurrentRemoteDir() to inspect it.

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

    • checkConnection

      public boolean checkConnection()
      Returns whether Chilkat currently considers the FTP control connection to be open. It does not require that the session be authenticated: it can return true after connectOnly() and before loginAfterConnectOnly().

      This is a local connection-state check. It does not send NOOP, reconnect automatically, or prove that a silently broken network path will carry the next command.

      Returns:
      the result; this method never throws ChilkatException

    • clearControlChannel

      public void clearControlChannel()
      Requests that an explicit-FTPS control connection return to clear text after authentication. Data connections may remain protected according to getDataProtection(). Security and compatibility: This is a legacy workaround for FTP-aware NAT devices that must inspect PORT or PASV commands. It exposes FTP commands and replies, including path names, and should not be used unless required by the network environment.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearDirCache

      public void clearDirCache()
      Clears the cached listing for the current remote directory. The next call to getDirCount() or another indexed listing method retrieves a fresh listing from the server.

      The cache is automatically invalidated when the current remote directory or getListPattern() changes. Uploading, deleting, renaming, creating, or removing a remote item does not automatically refresh the cache. Changing getAllowMlsd(), getPreferNlst(), getListOption(), or getDirListingCharset() also leaves the existing cache intact.

      After a remote change: Call this method before relying on indexed listing methods when the application has uploaded, renamed, deleted, created, or removed an item in the current remote directory.

    • clearSessionLog

      public void clearSessionLog()
      Clears the in-memory FTP protocol log collected while getKeepSessionLog() is enabled.

    • connect

      public void connect()
      Connects to the server specified by getHostname() and getPort(), negotiates any configured proxy and TLS layer, receives the FTP greeting, and authenticates using getUsername(), getPassword(), and getAccount().

      For implicit or explicit FTPS, TLS is established before USER and PASS are sent. Chilkat sends PBSZ 0 and the PROT command required by getDataProtection(). If the server requires login before accepting those protection commands, Chilkat authenticates and retries them. Rejection of a required protection command causes the connection attempt to fail.

      After login, Chilkat sets binary transfer mode with TYPE I, requests SYST, sends FEAT when getAutoFeat() is enabled, and may send OPTS UTF8 ON when UTF-8 support is advertised and getAutoOptsUtf8() is enabled. It also obtains the initial current remote directory.

      Calling this method while already connected establishes a new FTP session and replaces the previous session state. The current remote directory, capability state, and listing cache are initialized for the new login.

      A failed connection attempt does not leave an underlying plain FTP connection open. To separate connection establishment from authentication, call connectOnly() followed by loginAfterConnectOnly().

      Failure diagnosis: After failure, inspect getConnectFailReason(), getLastReply(), and LastErrorText. A failure before the FTP greeting is usually DNS, routing, firewall, proxy, TCP, or implicit-TLS related; a failure after the greeting may involve explicit TLS, data-protection setup, authentication, or server policy.

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

    • connectOnly

      public void connectOnly()
      Establishes the configured proxy and TCP connection, performs any configured implicit or explicit TLS setup, and receives the FTP server greeting, but does not send USER or PASS. Complete authentication by calling loginAfterConnectOnly().

      With implicit FTPS, the TLS handshake occurs immediately after the TCP connection is established and before the greeting is received. With explicit FTPS, Chilkat first receives the greeting, sends AUTH TLS or AUTH SSL, and then performs the TLS handshake. When the control channel is protected, Chilkat also sends PBSZ 0 and the PROT command required by getDataProtection(), even though login has not yet occurred.

      After success, getConnectVerified() is true and getLoginVerified() remains false. The current remote directory may be unavailable until login because many servers reject PWD before authentication.

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

    • convertToTls

      public void convertToTls()
      Upgrades an already-connected clear FTP control channel to explicit TLS. This method is intended for a manually staged connection created with connectOnly() while getSsl(), getAuthTls(), and getAuthSsl() were disabled.

      Chilkat sends AUTH TLS, performs the TLS handshake, sends PBSZ 0, and then sends the PROT command required by getDataProtection(). The method does not authenticate; call loginAfterConnectOnly() afterward.

      Do not call it when explicit or implicit FTPS was already enabled before connecting.

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

    • createPlan

      public String createPlan​(String localDir)
      Creates and returns a textual upload plan for the local directory at localDir. The object must be connected because the plan records the current absolute remote directory together with the local source paths.

      The generated plan contains absolute local paths and absolute remote directory operations. Treat the text as a Chilkat-generated plan for putPlan(String, String) rather than as a portable or stable interchange format.

      The plan records what to do, not a snapshot of file contents. If a local file changes before PutPlan executes, the current file contents are uploaded.

      Resumable bulk upload: PutPlan records completed operations in a log file. Reusing the plan and log after interruption allows already completed steps to be skipped.

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

    • createRemoteDir

      public void createRemoteDir​(String remoteDirPath)
      Creates the remote directory at remoteDirPath by sending one MKD command. The path is interpreted relative to the current remote directory unless the server recognizes it as absolute.

      Chilkat does not split a multi-level path and does not issue separate commands to create missing parent directories. Some servers create all levels from one MKD a/b/c command, while others require the parent directories to exist.

      If the directory already exists, the server commonly returns an error. A successful call does not refresh the cached indexed listing; call clearDirCache() when a fresh listing is required.

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

    • deleteMatching

      public int deleteMatching​(String remotePattern)
      Deletes files in the current remote directory whose names match the wildcard pattern in remotePattern. The method returns the number deleted, or -1 if the operation fails.

      Chilkat sends a server-side legacy listing request such as LIST *.txt, parses the returned entries, and sends DELE for matching files. Matching case sensitivity and wildcard behavior therefore depend on the server. Matching directories are not removed by this method.

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

    • deleteRemoteFile

      public void deleteRemoteFile​(String remoteFilePath)
      Deletes the remote file at remoteFilePath. The path may be relative to the current remote directory or absolute according to the server's path syntax.

      A successful deletion does not refresh the cached indexed listing. Call clearDirCache() when a fresh listing is required.

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

    • deleteTree

      public void deleteTree()
      Recursively deletes the files and subdirectories beneath the current remote directory. Child directories are removed after their contents are deleted, but the current root directory itself remains in place and remains the current remote directory. Destructive operation: Set the current remote directory carefully before calling this method. The VerifyDeleteFile and VerifyDeleteDir callbacks can set their skip output to prevent selected items from being deleted.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • dirTreeXml

      public String dirTreeXml()
      Returns an XML representation of the complete remote directory tree rooted at the current remote directory. The result uses a <dirTree> root, nested <dir name="..."> elements, and file elements containing the name, size, and available modification time. 
      <dirTree>
   <file sz="123" dt="Mon, 27 Jul 2026 06:55:00 -0500">root.txt</file>
   <dir name="subdir">
     <file sz="456" dt="...">nested.txt</file>
   </dir>
 </dirTree>

      Chilkat traverses by listing each directory and temporarily changing the server's current directory. Empty directories are included, and the original current remote directory is restored after successful traversal.

      Traversal is affected by getSyncMustMatch(), getSyncMustNotMatch(), getSyncMustMatchDir(), and getSyncMustNotMatchDir(). This method retrieves metadata; it does not download file content.

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

    • disconnect

      public void disconnect()
      Ends the FTP session and closes the control connection. When connected, Chilkat sends QUIT when possible and then closes the socket.

      The method is idempotent. Calling it before a connection exists or calling it again after the session is already closed succeeds without sending another FTP command. Historical properties such as getConnectVerified(), getLoginVerified(), getGreeting(), and getLastReply() may retain information from the completed session; use checkConnection() for current connection state.

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

    • downloadTree

      public void downloadTree​(String localRoot)
      Downloads all selected files and subdirectories beneath the current remote directory and recreates the tree under the local directory at localRoot. Existing local files are overwritten, and eligible empty remote directories are created locally.

      The file and directory filters in getSyncMustMatch(), getSyncMustNotMatch(), getSyncMustMatchDir(), and getSyncMustNotMatchDir() apply. Use setOldestDateStr(String) to exclude files older than a chosen date.

      Windows filenames: Remote names that contain characters invalid in a Windows filename are sanitized when creating the local tree. Invalid characters are replaced with underscores and trailing periods are removed. For example, a<b>c:d|e?f*g.txt is saved as a_b_c_d_e_f_g.txt. Different remote names can potentially map to the same local path.

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

    • feat

      public String feat()
      Sends FEAT and returns the server's multiline capability reply. A server may return an error when the command is unsupported or not permitted in the current session state.

      A successful explicit call performs the same capability processing as automatic FEAT. It can update getHasModeZ(), listing-extension detection, UTF-8 handling through getAutoOptsUtf8(), and getUseEpsv() through getAutoSetUseEpsv(), even when getAutoFeat() is false.

      Some servers permit FEAT before authentication and others do not.

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

    • getCreateTimeByNameStr

      public String getCreateTimeByNameStr​(String filename)
      Returns the creation time for the file or directory named by filename in the current remote directory as an RFC 822 date-time string, such as Fri, 21 Nov 1997 09:55:06 -0600.

      filename must be a name, not a path. Set the current remote directory first, and ensure getListPattern() matches the name so the item is present in the cached listing.

      Creation times: Many UNIX-like filesystems and FTP listing formats do not provide a file creation time. In that case the server or parser may report the modification time instead.

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

    • getCreateTimeStr

      public String getCreateTimeStr​(int index)
      Returns the creation time for cached directory-listing entry index as an RFC 822 date-time string, such as Fri, 21 Nov 1997 09:55:06 -0600. index is a zero-based index from 0 through one less than getDirCount(). Creation-time availability depends on the server and listing format.

      An invalid index or unavailable creation time is a method failure and sets LastMethodSuccess to false.

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

    • getCurrentRemoteDir

      public String getCurrentRemoteDir()
      Returns the current working directory reported by the FTP server, normally by using the PWD command.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getDirCount

      public int getDirCount()
      Returns the number of files and directories in the cached listing of the current remote directory after applying the case-insensitive getListPattern(). On the first call, Chilkat obtains and caches the full directory listing and then applies the pattern locally. Repeated indexed listing calls use the cache until it is invalidated. Returns -1 if the listing cannot be obtained or parsed.

      The cache is not automatically refreshed by uploads, deletions, renames, directory creation/removal, raw commands, or changes to the listing-command selection properties. Call clearDirCache() when the server contents or desired listing format may have changed.

      Directory listings use a data connection: An FTP listing is transferred over a separate data connection, just like an upload or download. If this method stalls, investigate passive/active mode, NAT, firewall rules, and the data-connection details in LastErrorText.

      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getFile

      public void getFile​(String remoteFilePath, String localFilePath)
      Downloads the remote file at remoteFilePath to the local filesystem path at localFilePath. The local parent directory must already exist; this method does not create missing local directories.

      When not resuming, the downloaded file replaces an existing destination after the server accepts the transfer. If the server rejects the request before transfer begins, such as when the remote file does not exist, an existing destination file is preserved.

      Use getRestartNext() immediately before this call to resume from the existing local file length. getReadTimeout() controls data-channel inactivity. If a transfer fails after receiving some data, inspect getPartialTransfer(); completed bytes are not rolled back.

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

    • getFileBd

      public void getFileBd​(String remoteFilePath, BinData binData)
      Downloads the remote file at remoteFilePath and appends its bytes to the existing contents of the BinData object in binData. The object is not cleared automatically. No text decoding or line-ending conversion is performed.

      When getRestartNext() is true, the current byte count in binData is used as the resume offset and only the remaining remote bytes are appended.

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

    • getFileSb

      public void getFileSb​(String remoteFilePath, String charset, StringBuilder sb)
      Downloads the remote file at remoteFilePath, decodes its bytes using the charset named by charset, and appends the resulting text to the existing contents of the StringBuilder in sb. The destination is not cleared automatically.

      A byte-order mark for the selected encoding is recognized and removed from the decoded text. Invalid byte sequences are replaced during decoding rather than causing the transfer itself to fail.

      When getRestartNext() is true, the existing destination content is used to determine the resume offset, and the remaining decoded content is appended.

      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

    • getFileToStream

      public void getFileToStream​(String remoteFilePath, Stream toStream)
      Downloads the remote file at remoteFilePath and writes its bytes to the Stream in toStream.

      For a synchronous call, toStream must be configured with a destination sink before the method begins. For an asynchronous call, application code may read from the stream while the background download produces data.

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

    • getFilename

      public String getFilename​(int index)
      Returns the name of cached directory-listing entry index. index is a zero-based index from 0 through one less than getDirCount(). The returned value is the name from the listing, not necessarily a full remote path.

      An out-of-range or negative index is a method failure and sets LastMethodSuccess to false.

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

    • getGroup

      public String getGroup​(int index)
      Returns the group name or identifier for cached directory-listing entry index. The value is empty when the server does not provide group metadata. MLSD metadata: MLSD commonly provides accurate size and time facts but often omits owner and group. On a UNIX-like server, disabling getAllowMlsd() may expose owner/group through LIST, at the cost of less standardized and potentially less accurate listing data.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getIsDirectory

      public boolean getIsDirectory​(int index)
      Returns true when cached directory-listing entry index is identified as a directory. index is a zero-based index into the current cached listing.

      For an invalid index the method returns false and sets LastMethodSuccess to false. Check that property when false must be distinguished from a valid non-directory entry.

      Parameters:
      index - the index argument
      Returns:
      the result; this method never throws ChilkatException

    • getIsSymbolicLink

      public boolean getIsSymbolicLink​(int index)
      Returns true when cached directory-listing entry index is identified as a symbolic link. This information is available only when the server's listing format reports it.

      For an invalid index the method returns false and sets LastMethodSuccess to false. A valid false result can also mean the entry is not a link or the listing did not provide link metadata.

      Parameters:
      index - the index argument
      Returns:
      the result; this method never throws ChilkatException

    • getLastJsonData

      public void getLastJsonData​(JsonObject json)
      Copies structured supplemental JSON produced by the immediately preceding method into the JsonObject in json. TLS connection and protected data-connection operations can populate information such as the negotiated TLS version.

      The data is transient. A later method may replace it or clear it to an empty object, including ordinary commands such as NOOP, raw commands, or disconnect(). Call this method immediately after the operation whose details are needed.

      Parameters:
      json - the json argument (not null)

    • getLastModifiedTimeByNameStr

      public String getLastModifiedTimeByNameStr​(String filename)
      Returns the last-modified time for the item named by filename in the current remote directory as an RFC 822 date-time string, such as Fri, 21 Nov 1997 09:55:06 -0600.

      filename must be a name, not a path. Set the current remote directory first, and ensure getListPattern() matches the name.

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

    • getLastModifiedTimeStr

      public String getLastModifiedTimeStr​(int index)
      Returns the last-modified time for cached directory-listing entry index as an RFC 822 date-time string, such as Fri, 21 Nov 1997 09:55:06 -0600. index is a zero-based index into the current cached listing.

      An invalid index or unavailable timestamp is a method failure and sets LastMethodSuccess to false.

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

    • getOwner

      public String getOwner​(int index)
      Returns the owner name or identifier for cached directory-listing entry index. The value is empty when a valid entry has no owner metadata. An invalid index is a method failure and sets LastMethodSuccess to false. MLSD metadata: MLSD commonly provides accurate size and time facts but often omits owner and group. On a UNIX-like server, disabling getAllowMlsd() may expose owner/group through LIST, at the cost of less standardized and potentially less accurate listing data.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getPermType

      public String getPermType​(int index)
      Returns the format identifier for the permissions string available for cached listing entry index. The value is empty when no permissions are available.

      Value Format

      mlsd The RFC 3659 perm fact.

      unix A UNIX/POSIX-style mode string.

      netware NetWare trustee rights.

      openvms An OpenVMS protection string.

      batchStatusFlags Connect:Enterprise batch status flags.

      Use getPermissions(int) to obtain the corresponding value.

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

    • getPermissions

      public String getPermissions​(int index)
      Returns the permissions or status string for cached directory-listing entry index. The value is empty when the server provides no such metadata. Use getPermType(int) to determine how to interpret the result.

      Permission type Returned information

      mlsd The RFC 3659 perm fact. Letters describe FTP operations available to the logged-in user, such as append, create, delete, enter, list, rename, or write.

      unix A UNIX-style string such as rwxr-xr-x.

      netware NetWare trustee-right letters such as read, write, create, erase, modify, file scan, access control, and supervisor.

      openvms An OpenVMS protection string such as (RWED,RWED,R,R).

      batchStatusFlags A fixed-position Connect:Enterprise batch-status string such as -CR--M----.

      MLSD perm is not a file mode: The MLSD perm fact describes operations the current FTP account may perform. It is not equivalent to UNIX owner/group/other permission bits.

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

    • getRemoteFileTextC

      public String getRemoteFileTextC​(String remoteFilename, String charset)
      Downloads the remote file at remoteFilename, decodes the bytes using the character encoding named by charset, and returns the text. A byte-order mark for the selected encoding is recognized and omitted from the returned text.

      This method controls file-content decoding. The encoding used for the remote path itself is controlled by getCommandCharset().

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

    • getRemoteFileTextData

      public String getRemoteFileTextData​(String remoteFilename)
      Downloads the remote file at remoteFilename and returns its contents decoded using the ANSI character encoding. Use getRemoteFileTextC(String, String) when the file uses UTF-8 or another explicitly known encoding.
      Parameters:
      remoteFilename - the remoteFilename argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getServerCert

      public void getServerCert​(Cert cert)
      Loads into the Cert object in cert the leaf certificate presented on the currently connected FTPS control channel.

      The method requires an active TLS control connection. A protected data connection does not replace the control-channel certificate returned here, and the certificate is not retained for retrieval after disconnect().

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

    • getSize

      public int getSize​(int index)
      Returns the size in bytes of cached directory-listing entry index as a 32-bit integer. Use getSize64(int) for large files.

      Returns -1 when index is invalid or the size is unavailable. Because this method returns an integer, do not use LastMethodSuccess to interpret the result.

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

    • getSize64

      public long getSize64​(int index)
      Returns the size in bytes of cached directory-listing entry index as a 64-bit integer. Returns -1 when index is invalid or the size is unavailable.

      Because this method returns an integer, do not use LastMethodSuccess to interpret the result.

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

    • getSizeByName

      public int getSizeByName​(String filename)
      Returns the size in bytes of the file named by filename in the current remote directory as a 32-bit integer. Returns -1 when the file is not found or the size cannot be obtained. Use getSizeByName64(String) for large files.

      filename must be a name, not a path. Set the current remote directory first, and ensure getListPattern() matches the name.

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

    • getSizeByName64

      public long getSizeByName64​(String filename)
      Sends a SIZE command for filename and returns the remote size in bytes as a 64-bit integer. Returns -1 when the server rejects the command, the item is not found, or the size is unavailable.

      This method does not depend on the indexed directory cache or getListPattern(). Filename and path case sensitivity are determined by the FTP server and its filesystem.

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

    • getSizeStr

      public String getSizeStr​(int index)
      Returns the size in bytes of cached directory-listing entry index as a decimal string. This form avoids integer-size limits in languages without a convenient 64-bit type.

      An out-of-range or negative index is a method failure and sets LastMethodSuccess to false.

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

    • getSizeStrByName

      public String getSizeStrByName​(String filename)
      Returns the size in bytes of the file named by filename in the current remote directory as a decimal string. This form avoids language-specific integer limits.

      filename must be a name, not a path. Set the current remote directory first, and ensure getListPattern() matches the name.

      Parameters:
      filename - the filename argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • getSyncedFiles

      public void getSyncedFiles​(StringTable strTable)
      Appends to the StringTable in strTable the relative paths affected by the most recent synchronization operation. Existing entries in strTable are preserved.

      The appended paths include files uploaded, downloaded, or deleted by syncDeleteRemote(String), syncLocalDir(String, int), syncLocalTree(String, int), syncRemoteTree(String, int), or syncRemoteTree2(String, int, boolean, boolean). When a successful preview has no candidates, no placeholder or empty-string entry is appended.

      Parameters:
      strTable - the strTable argument (not null)

    • getTextDirListing

      public String getTextDirListing​(String pattern)
      Sends a legacy LIST request and returns the server's raw textual listing. pattern is appended literally as a server-side listing argument. An empty pattern lists the current remote directory; a value such as *.txt sends a command such as LIST *.txt.

      getListOption() is also appended literally before pattern. For example, ListOption = "-a" and pattern equal to *.txt send LIST -a *.txt.

      This method does not use MLSD, NLST, getListPattern(), or the indexed directory cache. Wildcard matching and case sensitivity are determined by the server. The format of LIST output is server-specific.

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

    • getXmlDirListing

      public String getXmlDirListing​(String pattern)
      Retrieves a directory listing for pattern and returns parsed entries as an XML document rooted at <remoteDir>. Files are represented by <file> elements containing <name>, <size>, and available time elements; directories are represented by <dir> elements. 
      <remoteDir>
   <file>
     <name>report.txt</name>
     <size>1234</size>
     <lastModTime full="20260727-065541" ... />
   </file>
   <dir lastModTime="20260727-065542" ...>archive</dir>
 </remoteDir>

      When pattern is empty, Chilkat uses the normal listing selection: MLSD when allowed and advertised, otherwise LIST or NLST according to the listing properties. When pattern is nonempty, Chilkat sends LIST pattern, so wildcard matching and case sensitivity are server-dependent.

      This method does not use or populate the indexed directory cache and getListPattern() is not applied.

      Timestamp interpretation: Returned last-modified values are expressed in the client's local time. MLSD timestamps are standardized as UTC, while legacy LIST timestamps may omit timezone and seconds, so exact conversion can be impossible when the server timezone is unknown.

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

    • largeFileUpload

      public void largeFileUpload​(String localPath, String remotePath, int chunkSize)
      Uploads the local file at localPath to the remote path at remotePath as a sequence of data transfers, each containing up to chunkSize bytes. The first chunk is sent with STOR, which creates or replaces remotePath, and each later chunk is sent with APPE.

      This method addresses a specific FTP failure mode: during one very long data transfer, the control connection is idle and may be silently dropped by a firewall, NAT device, or server timeout. Completing the upload as multiple shorter transfers periodically uses the control channel.

      chunkSize is the in-memory chunk size. Larger chunks reduce FTP command overhead but consume more memory and leave the control channel idle longer; smaller chunks have the opposite tradeoff. Transfer counters represent the complete source file, not only the final chunk.

      Alternative: For ordinary large files, first consider enabling getLargeFileMeasures(). Use chunked upload when infrastructure still drops the idle control session.

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

    • loginAfterConnectOnly

      public void loginAfterConnectOnly()
      Authenticates an FTP control connection previously established by connectOnly(). Chilkat sends USER, PASS, and ACCT when required, then performs the normal post-login initialization such as TYPE I, SYST, capability discovery, and UTF-8 setup.

      If authentication is rejected, the same connection cannot be retried by simply changing the credentials and calling this method again. Disconnect or reconnect with connectOnly() before attempting another login.

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

    • mGetFiles

      public int mGetFiles​(String remotePattern, String localDir)
      Downloads files in the current remote directory that match remotePattern into the existing local directory at localDir. Subdirectories are not traversed. The method returns the number of files downloaded, or -1 on failure.

      localDir must already exist; the method does not create it. Existing local files with matching names are replaced. Chilkat sends a server-side listing request for remotePattern, so wildcard matching and case sensitivity depend on the FTP server and remote filesystem.

      Windows filenames: Remote names that contain characters invalid in a Windows filename are sanitized for the local file. Invalid characters are replaced with underscores and trailing periods are removed. For example, a<b>c:d|e?f*g.txt is saved as a_b_c_d_e_f_g.txt. Different remote names can potentially map to the same local name.

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

    • mPutFiles

      public int mPutFiles​(String pattern)
      Uploads each local file matching pattern to the current remote directory. pattern may include a local directory and wildcard, such as C:/data/*.txt. Subdirectories are not traversed.

      Local wildcard behavior follows the local operating system; for example, Windows matching is case-insensitive. Only each matching file's basename is used as the remote filename. Existing remote files are replaced using normal STOR behavior.

      The method returns the number of files uploaded, or -1 on failure.

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

    • nlstXml

      public String nlstXml​(String remoteDirPattern)
      Sends NLST with remoteDirPattern appended literally and returns the names in XML form. An empty remoteDirPattern sends NLST; a value such as *.txt sends NLST *.txt. 
      <nlst>
   <e>name1</e>
   <e>name2</e>
 </nlst>

      The response is decoded using getDirListingCharset(). NLST normally returns names only; the XML does not distinguish files from directories and does not provide reliable sizes, times, ownership, or permissions. Wildcard matching and case sensitivity are server-dependent.

      This method does not use or populate the indexed directory cache.

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

    • noop

      public void noop()
      Sends the FTP NOOP command. The server must return a positive FTP reply for the method to succeed.

      Whether NOOP is accepted before login is server-dependent. This method does not reconnect a closed session.

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

    • putFile

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

      Uses the FTP STOR command. A normal upload creates a missing remote file or truncates and replaces an existing one. Chilkat does not create missing remote parent directories and does not upload through a temporary remote name followed by an atomic rename.

      Use getRestartNext() immediately before this call to resume an existing partial remote file. getIdleTimeoutMs() limits how long the upload may remain blocked without forward progress.

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

    • putFileBd

      public void putFileBd​(BinData binData, String remoteFilePath)
      Uploads the bytes contained in the BinData object in binData to the remote path at remoteFilePath. No character encoding or line-ending conversion is performed.

      Uses the FTP STOR command. A normal upload creates a missing remote file or truncates and replaces an existing one. Chilkat does not create missing remote parent directories and does not upload through a temporary remote name followed by an atomic rename.

      getRestartNext() can be used to upload only the bytes beyond the existing remote size.

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

    • putFileFromTextData

      public void putFileFromTextData​(String remoteFilename, String textData, String charset)
      Encodes the text in textData using the character encoding named by charset and uploads the resulting bytes to the remote file at remoteFilename.

      Uses the FTP STOR command. A normal upload creates a missing remote file or truncates and replaces an existing one. Chilkat does not create missing remote parent directories and does not upload through a temporary remote name followed by an atomic rename.

      The content charset is independent of getCommandCharset(), which controls the encoding of the remote path sent in the FTP command.

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

    • putFileSb

      public void putFileSb​(StringBuilder sb, String charset, boolean includeBom, String remoteFilePath)
      Encodes the text in the StringBuilder sb using the charset named by charset and uploads it to the remote path at remoteFilePath. When includeBom is true, a byte-order mark is included when the selected encoding defines one.

      Uses the FTP STOR command. A normal upload creates a missing remote file or truncates and replaces an existing one. Chilkat does not create missing remote parent directories and does not upload through a temporary remote name followed by an atomic rename.

      getRestartNext() can be used for a resumed upload when the existing remote content and encoded byte sequence are compatible.

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

    • putPlan

      public void putPlan​(String plan, String alreadyDoneFilename)
      Executes the upload plan in plan. alreadyDoneFilename is the local path of a completion log; each successful plan operation is recorded there.

      The absolute remote paths stored in the plan are used even if the current remote directory has changed since the plan was created. Local files are opened when this method executes, so changes made after createPlan(String) are reflected in the upload.

      To resume an interrupted plan, call this method again with the same plan and log path. Operations already recorded as complete are skipped.

      Log durability: Store the completion log on reliable local storage and do not edit it while the plan is running.

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

    • putTree

      public void putTree​(String localDir)
      Uploads the local directory tree rooted at localDir into the current remote directory, creating remote subdirectories as needed. The contents of localDir become children of the current remote directory.

      The file and directory filters in getSyncMustMatch(), getSyncMustNotMatch(), getSyncMustMatchDir(), and getSyncMustNotMatchDir() apply. Empty eligible local directories are created remotely. Existing remote files are overwritten with STOR.

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

    • quote

      public void quote​(String cmd)
      Sends the raw FTP command text in cmd to the server. Use this for a command not otherwise exposed by the API.

      cmd contains the command and parameters but must not contain CR or LF characters; such input is rejected without sending anything. Chilkat considers the method successful only when the server returns a positive FTP reply. A 4xx or 5xx reply causes failure and remains available through getLastReply().

      The method does not parse command-specific semantics. Use sendCommand(String) when the reply text is needed directly.

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

    • removeRemoteDir

      public void removeRemoteDir​(String remoteDirPath)
      Removes the remote directory at remoteDirPath. FTP servers generally require the directory to be empty before it can be removed.

      A successful call does not refresh the cached indexed listing. Call clearDirCache() before relying on indexed listing methods.

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

    • renameRemoteFile

      public void renameRemoteFile​(String existingRemoteFilePath, String newRemoteFilePath)
      Renames or moves a remote file or directory from existingRemoteFilePath to newRemoteFilePath using the FTP RNFR/RNTO sequence. Include directory components in newRemoteFilePath to move the item within the same FTP server.

      Chilkat does not perform a protective destination-existence check. If newRemoteFilePath already exists, one server may reject the rename while another may replace the destination. Cross-directory or cross-filesystem moves are also subject to server policy.

      A successful rename does not refresh the cached indexed listing. Call clearDirCache() when a fresh listing is required.

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

    • sendCommand

      public String sendCommand​(String cmd)
      Sends the raw FTP command in cmd and returns the complete server reply. The command text is sent as UTF-8; getCommandCharset() is not applied.

      cmd must not contain CR or LF characters; such input is rejected without sending anything. A positive FTP reply is returned normally. A 4xx or 5xx reply is treated as method failure and sets LastMethodSuccess to false.

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

    • setModeZ

      public void setModeZ()
      Enables MODE Z compression for subsequent data connections. Call this after connecting and only when getHasModeZ() is true. Uploads, downloads, and directory listings are then transferred through a DEFLATE-compressed stream. Performance tradeoff: Compression can reduce network traffic for text and other compressible data, but may increase CPU usage and provide little benefit for already-compressed formats such as ZIP, JPEG, or MP4.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setOldestDateStr

      public void setOldestDateStr​(String oldestDateTimeStr)
      Sets the oldest remote modification time eligible for downloadTree(String). oldestDateTimeStr is an RFC 822 date-time string, such as Fri, 21 Nov 1997 09:55:06 -0600. Files older than the configured value are skipped.

      The value remains active for subsequent DownloadTree calls; it is not consumed after one operation. Avoid relying on exact equality at the boundary because legacy LIST timestamps can have reduced precision or ambiguous timezone interpretation.

      Parameters:
      oldestDateTimeStr - the oldestDateTimeStr argument (not null)

    • setOption

      public void setOption​(String optionName)
      Enables or disables a named compatibility option. Option-name matching is case-insensitive. Prefix a recognized name with No- to disable it.

      The recognized option Microsoft-TLS-1.2-Workaround changes data-channel TLS behavior for compatibility with an old Microsoft FTP server defect. It weakens protocol selection and should be used only for the affected legacy server. An unrecognized option name is rejected.

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

    • setRemoteFileDateTimeStr

      public void setRemoteFileDateTimeStr​(String dateTimeStr, String remoteFilename)
      Sets the last-modified time of the remote file at remoteFilename. dateTimeStr is an RFC 822 date-time string, such as Fri, 21 Nov 1997 09:55:06 -0600.

      Chilkat converts dateTimeStr to UTC and sends a server-supported timestamp-setting extension. Depending on the server, the command may be MFMT YYYYMMDDhhmmss path or the nonstandard timestamp-setting form of MDTM YYYYMMDDhhmmss path. Precision is one second.

      FTP has no universally implemented standard for changing a file timestamp; success depends on server extensions and permissions.

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

    • setRemoteFileDt

      public void setRemoteFileDt​(DateTime dt, String remoteFilename)
      Sets the last-modified time of the remote file at remoteFilename using the CkDateTime in dt.

      Chilkat converts the value to UTC and sends a server-supported timestamp-setting extension. Depending on the server, the command may be MFMT YYYYMMDDhhmmss path or the nonstandard timestamp-setting form of MDTM YYYYMMDDhhmmss path. Precision is one second.

      FTP has no universally implemented standard for changing a file timestamp; success depends on server extensions and permissions.

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

    • setSecurePassword

      public void setSecurePassword​(SecureString password)
      Copies the password from the SecureString in password for subsequent FTP authentication. This avoids exposing the password as an ordinary immutable language string. It is equivalent to setting getPassword() for login behavior.
      Parameters:
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslCertRequirement

      public void setSslCertRequirement​(String reqName, String reqValue)
      Adds a required match against the FTP server certificate. reqName selects the certificate field and reqValue specifies the required value. Supported field names include SubjectDN, SubjectCN, IssuerDN, IssuerCN, and SAN. Wildcards such as * may be used in reqValue.

      Requirement-value matching is case-sensitive. Multiple calls add requirements that are combined with logical AND; every requirement must match.

      Requirements are evaluated when the FTPS control-channel TLS connection is established. Adding a new requirement after connection does not retroactively reject the existing control channel and is not applied to later protected data-channel handshakes within that session.

      Additional check: Certificate requirements supplement normal certificate validation; they should not be used as a substitute for trust-chain, validity, and hostname verification.

      Parameters:
      reqName - the reqName argument (not null)
      reqValue - the reqValue argument (not null)

    • setSslClientCert

      public void setSslClientCert​(Cert cert)
      Configures the Cert in cert as the client certificate for FTPS servers that request mutual TLS authentication. The certificate must have access to its private key.
      Parameters:
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslClientCertPem

      public void setSslClientCertPem​(String pemDataOrFilename, String pemPassword)
      Configures a client certificate and private key from PEM data or a PEM file. pemDataOrFilename may contain the PEM text or the local filesystem path of a PEM file. pemPassword is the private-key password, or an empty string when the key is not encrypted.
      Parameters:
      pemDataOrFilename - the pemDataOrFilename argument (not null)
      pemPassword - the pemPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslClientCertPfx

      public void setSslClientCertPfx​(String pfxFilename, String pfxPassword)
      Loads a client certificate and private key from the local PFX/P12 file at pfxFilename. pfxPassword is the file password. The certificate is used when the FTPS server requests mutual TLS authentication.
      Parameters:
      pfxFilename - the pfxFilename argument (not null)
      pfxPassword - the pfxPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setTypeAscii

      public void setTypeAscii()
      Sets the FTP representation type to ASCII for subsequent transfers. In ASCII mode, the FTP endpoints may translate line endings, and getCrlfMode() can apply additional conversion on downloads. Use carefully: ASCII mode is intended for text. Use setTypeBinary() for executables, archives, images, encrypted data, and any file whose bytes must remain unchanged.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setTypeBinary

      public void setTypeBinary()
      Sets the FTP representation type to binary (TYPE I) for subsequent transfers. Binary mode preserves file bytes and is the appropriate default for nearly all modern file types.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • site

      public void site​(String siteCommand)
      Sends a server-specific SITE command. siteCommand contains the text following SITE, for example RECFM=FB LRECL=600.

      SITE subcommands are defined by the server, not by the FTP standard, and may require special permissions.

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

    • sleepMs

      public void sleepMs​(int millisec)
      Blocks the calling thread for millisec milliseconds. This is a utility method and performs no FTP network operation.
      Parameters:
      millisec - the millisec argument

    • stat

      public String stat()
      Sends the FTP STAT command and returns the server's reply. Depending on the server and session state, the reply may contain status information or a directory listing.

      Support, accepted arguments, and whether the command is permitted before login are server-dependent.

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

    • syncDeleteRemote

      public void syncDeleteRemote​(String localRoot)
      Recursively compares the remote tree rooted at the current remote directory with the local tree rooted at localRoot and deletes remote files that have no corresponding local file. The synchronization file and directory filters apply. Empty remote directories are not deleted. Destructive synchronization: This method deletes server data. Verify the current remote directory, local root, and synchronization filters before calling it.

      Use getSyncedFiles(StringTable) after the call to obtain the relative paths deleted.

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

    • syncLocalDir

      public void syncLocalDir​(String localRoot, int mode)
      Synchronizes files from the current remote directory into the local directory at localRoot without descending into subdirectories. mode selects the same download modes documented for syncLocalTree(String, int).

      The filters are case-insensitive and match basenames. In mode 99, only unmatched remote files in the current directory are deleted; nested directories are not traversed and their contents are not examined. Extra local files are not deleted.

      Unsupported mode values fail before an FTP command is sent. Use getSyncedFiles(StringTable) afterward to obtain the affected relative paths.

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

    • syncLocalTree

      public void syncLocalTree​(String localRoot, int mode)
      Synchronizes the remote tree rooted at the current remote directory into the local directory at localRoot. mode selects which files are downloaded or deleted.

      Mode Action

      0 Download all selected files.

      1 Download files missing locally.

      2 Download files that are missing locally or newer on the server.

      3 Download only files that already exist locally and are newer on the server.

      5 Download files that are missing locally or have a different size.

      6 Download files that are missing, have a different size, or are newer on the server.

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

      The synchronization filters are case-insensitive and match file basenames rather than relative paths. A file is considered newer only when its timestamp is strictly later; equal timestamps do not qualify.

      Mode 99 deletes remote files that do not exist locally; it does not delete extra local files. Only the mode values shown in the table are valid. Other values fail before any FTP command is sent. Use getSyncedFiles(StringTable) afterward to obtain the affected relative paths.

      Mode numbers differ by direction: The upload and download synchronization methods do not assign the same meanings to all numeric modes. Use the table for the method being called. Time comparison: Newer-file modes depend on remote timestamps and local clock interpretation. Size-based modes may be more predictable when server timestamp precision is limited.

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

    • syncRemoteTree

      public void syncRemoteTree​(String localRoot, int mode)
      Synchronizes the local tree rooted at localRoot into the current remote directory. mode selects which files are uploaded.

      Mode Action

      0 Upload all selected files.

      1 Upload files missing on the server.

      2 Upload files that are missing or newer locally.

      3 Upload only files that already exist remotely and are newer locally.

      4 Upload files that are missing or have a different size.

      5 Upload files that are missing, have a different size, or are newer locally.

      The synchronization filters are case-insensitive and match file basenames rather than relative paths. A file is considered newer only when its timestamp is strictly later; equal timestamps do not qualify.

      Only the mode values shown in the table are valid. Other values fail before any FTP command is sent. Use getSyncedFiles(StringTable) afterward to obtain the relative paths uploaded.

      Mode numbers differ by direction: The upload and download synchronization methods do not assign the same meanings to all numeric modes. Use the table for the method being called rather than reusing a mode number from a download operation.

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

    • syncRemoteTree2

      public void syncRemoteTree2​(String localDirPath, int mode, boolean bDescend, boolean bPreviewOnly)
      Provides the upload synchronization behavior and valid modes of syncRemoteTree(String, int) with traversal and preview controls. localDirPath is the local root, mode is the upload synchronization mode, bDescend controls whether subdirectories are traversed, and bPreviewOnly selects preview-only mode. File and directory filters apply in both normal and preview operation.

      When bPreviewOnly is true, files are not uploaded and the absolute candidate file paths are placed in getSyncPreview(). Required remote directories may still be created during preview. If no files qualify, the preview is empty.

      Unsupported mode values fail before any FTP command is sent and clear SyncPreview. A failed preview also leaves it empty. A subsequent non-preview synchronization clears the previous preview.

      Parameters:
      localDirPath - the localDirPath argument (not null)
      mode - the mode argument
      bDescend - the bDescend argument
      bPreviewOnly - the bPreviewOnly argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • syst

      public String syst()
      Sends SYST and returns the server's operating-system type reply. Chilkat can use this information when interpreting legacy directory listings.

      Whether the command is accepted before authentication is server-dependent.

      Returns:
      the result (never 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