Chilkat.Ftp2 Class Overview
Chilkat.Ftp2 provides a full-featured client for FTP and FTPS file transfer. It supports plain FTP, explicit FTPS using AUTH TLS or AUTH SSL, implicit FTPS, passive and active data connections, directory listings, uploads, downloads, recursive transfers, synchronization, proxies, bandwidth controls, TLS options, and detailed diagnostics.
What the Class Is Used For
Use Chilkat.Ftp2 when an application needs to connect to an FTP or FTPS server to upload, download, delete, rename, list, synchronize, or inspect files and directories. The class handles both the FTP control channel and the separate data connections used for file transfers and directory listings.
Connect to FTP / FTPS Servers
Use plain FTP, explicit FTPS with AUTH TLS,
or implicit FTPS on port 990.
Transfer Files
Upload and download files, memory bytes, text, streams,
BinData, and StringBuilder
content.
Work with Directories
Change directories, create directories, delete trees, retrieve listings,
inspect sizes, timestamps, owners, groups, and permissions.
Synchronize Trees
Sync local-to-remote or remote-to-local directory trees with include/exclude
patterns and preview support.
Protocol note:
Ftp2 is for FTP and FTPS. FTPS is FTP secured with
TLS/SSL. It is different from SFTP, which is the SSH File Transfer Protocol.
Typical Workflow
- Set connection properties such as Hostname, Port, Username, and Password.
- Choose the security mode: plain FTP, explicit FTPS with AuthTls, or implicit FTPS with Ssl.
- Choose the data-connection mode. Passive mode is the default and is usually the best choice for clients behind NAT routers or firewalls.
- Call Connect to connect and authenticate, or use ConnectOnly followed by LoginAfterConnectOnly for separate connection and login steps.
- Navigate with ChangeRemoteDir, list with GetDirCount and related methods, then upload, download, delete, rename, or synchronize files.
- Use LastErrorText, LastReply, SessionLog, and GetLastJsonData to troubleshoot failures.
- Call Disconnect when finished.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Control Channel | The connection used for FTP commands and replies, such as login, directory changes, and transfer commands. | Connect, LastReply, SessionLog, ClearControlChannel |
| Data Connection | A separate TCP connection used for each file transfer or directory listing. Many FTP connectivity problems are actually data-connection problems. | Passive, PassiveUseHostAddr, UseEpsv, ActivePortRangeStart, ActivePortRangeEnd |
| Passive Mode | The client asks the server where to connect for the data transfer. This is the default and usually works best behind NAT/firewalls. | Passive = true, PassiveUseHostAddr, UseEpsv |
| Active Mode | The client opens a local listening port and tells the server to connect back to the client. This can require firewall configuration. | Passive = false, ActivePortRangeStart, ActivePortRangeEnd, ForcePortIpAddress |
| MLSD Listings | A machine-readable FTP directory listing format. It is preferred when supported because it provides more dependable file information. | AllowMlsd, GetDirCount, GetFilename, GetPermissions, GetPermType |
| Restart / Resume | Failed or interrupted uploads and downloads can be resumed by setting a property before repeating the transfer call. | RestartNext, PartialTransfer |
FTP and FTPS Connection Modes
| Mode | Typical Port | Settings | Description |
|---|---|---|---|
| Plain FTP | 21 |
Ssl = false AuthTls = false AuthSsl = false |
Standard unencrypted FTP. Commands, credentials, and file data are sent without TLS protection. |
| Explicit FTPS using AUTH TLS | 21 |
AuthTls = true Ssl = false |
The client connects normally, then sends AUTH TLS to upgrade the session to TLS. This is the most common FTPS mode. |
| Explicit FTPS using AUTH SSL | 21 |
AuthSsl = true Ssl = false |
Similar to AUTH TLS, but sends AUTH SSL. Use this only when a server requires or works better with that command. |
| Implicit FTPS | 990 |
Ssl = true AuthTls = false AuthSsl = false |
TLS begins immediately when the TCP connection opens. This is less common than explicit FTPS. |
AutoFix behavior:
AutoFix is enabled by default. When connecting on
port 990, Chilkat automatically treats the connection
as implicit FTPS. When connecting on port 21, it
automatically clears implicit Ssl.
TLS and Certificate Options
The class provides detailed control over TLS behavior for both implicit FTPS and explicit FTPS. The most common configuration is to use AuthTls = true on port 21, or Ssl = true on port 990.
| Need | Use | Notes |
|---|---|---|
| Require server certificate verification | RequireSslCertVerify | When true, the connection fails if the certificate is expired or cannot be verified. |
| Inspect the negotiated TLS version | TlsVersion | Returns values such as TLS 1.2 or TLS 1.3 after a TLS connection is established. |
| Inspect the negotiated cipher suite | TlsCipherSuite | Useful for diagnosing server TLS configuration. |
| Restrict TLS protocols | SslProtocol | Prefer settings such as TLS 1.2 or higher instead of requiring one exact protocol version. |
| Restrict allowed cipher suites | SslAllowedCiphers | Can list explicit cipher suites or use keywords such as best-practices. |
| Pin the server public key | TlsPinSet | Provides public-key pinning by matching expected SPKI fingerprints. |
| Use a TLS client certificate | SetSslClientCert, SetSslClientCertPem, SetSslClientCertPfx | Used when the FTP server requires client-certificate authentication. |
| Get the server certificate | GetServerCert | Retrieves the certificate presented by the FTPS server. |
Data Connection Behavior
FTP is unusual because the command connection and file-transfer connection are separate. Directory listings are also data transfers, so a failure in GetDirCount or a listing method can indicate the same kind of firewall/NAT problem as a failed upload or download.
| Scenario | Recommended Properties | Guidance |
|---|---|---|
| Most client applications |
Passive = true PassiveUseHostAddr = true |
Passive mode is the default and usually works best when the client is behind NAT or a firewall. |
| Server sends a private IP address in PASV response | PassiveUseHostAddr = true | Chilkat ignores the IP address in the PASV response and uses the already established control connection host address. |
| Testing EPSV support | UseEpsv, AutoSetUseEpsv | EPSV can help in some environments, but may cause problems with some deep-inspection firewalls. Test with it both enabled and disabled when diagnosing passive connection failures. |
| Active mode with fixed local port range |
Passive = false ActivePortRangeStart ActivePortRangeEnd |
Useful when firewall rules only allow a specific client-side port range. |
| Active mode with a specific PORT IP address | ForcePortIpAddress | Forces the IP address sent in the FTP PORT command. The special value control uses the control connection peer address. |
| FTPS behind NAT using explicit TLS | ClearControlChannel | Can revert the control channel to clear text after authentication so a NAT router can inspect and translate FTP commands, while data transfers remain encrypted. |
Major Feature Areas
| Area | What You Can Do | Representative Members |
|---|---|---|
| Connection and Login | Connect, authenticate, check the connection, and disconnect from an FTP server. | Connect, ConnectOnly, LoginAfterConnectOnly, CheckConnection, Noop, Disconnect |
| Uploads | Upload files, bytes, text, streams, BinData, and StringBuilder content. | PutFile, PutFileBd, PutFileFromBinaryData, PutFileFromTextData, PutFileSb, LargeFileUpload |
| Appends | Append local files, bytes, text, BinData, or StringBuilder content to a remote file. | AppendFile, AppendFileBd, AppendFileFromBinaryData, AppendFileFromTextData, AppendFileSb |
| Downloads | Download to local files, memory, streams, BinData, or StringBuilder. | GetFile, GetFileBd, GetFileSb, GetFileToStream, GetRemoteFileBinaryData, GetRemoteFileTextData |
| Directory Listings | Retrieve directory counts, names, XML listings, text listings, NLST listings, and recursive tree XML. | GetDirCount, GetFilename, GetTextDirListing, GetXmlDirListing, NlstXml, DirTreeXml |
| Directory and File Management | Change directories, create directories, remove directories, delete files, delete matching files, delete trees, and rename files. | ChangeRemoteDir, CreateRemoteDir, RemoveRemoteDir, DeleteRemoteFile, DeleteMatching, DeleteTree, RenameRemoteFile |
| File Metadata | Inspect file sizes, timestamps, owner, group, permissions, symbolic-link status, and directory status. | GetSize, GetSize64, GetSizeByName64, GetLastModifiedTimeStr, GetCreateTimeStr, GetOwner, GetGroup, GetPermissions |
| Recursive Transfers | Upload or download entire directory trees, create transfer plans, and resume planned large-scale uploads. | PutTree, DownloadTree, CreatePlan, PutPlan |
| Synchronization | Synchronize local and remote trees, preview sync operations, filter files and directories, and delete remote files not present locally. | SyncLocalDir, SyncLocalTree, SyncRemoteTree, SyncRemoteTree2, SyncDeleteRemote, SyncPreview |
| Raw FTP Commands | Send FTP commands directly for diagnostics or server-specific features. | Quote, SendCommand, Site, Stat, Syst, Feat |
| Proxies | Connect through FTP proxies, HTTP proxies, or SOCKS4/SOCKS5 proxies. | ProxyMethod, ProxyHostname, DetermineProxyMethod, HttpProxyHostname, SocksVersion |
| Diagnostics | Inspect connection failure reasons, server replies, session logs, TLS details, and structured JSON details after selected operations. | LastErrorText, LastReply, Greeting, ConnectFailReason, SessionLog, GetLastJsonData |
Directory Listings and Metadata
Chilkat caches directory listing information after it is retrieved. Methods such as GetDirCount, GetFilename, GetSize, and timestamp methods operate on the current cached listing. The cache is refreshed when the remote directory changes, when ListPattern changes, or when ClearDirCache is called.
| Need | Use | Notes |
|---|---|---|
| Count matching entries | GetDirCount | Returns files and subdirectories matching ListPattern. |
| Get a filename by index | GetFilename | Indexing begins at 0 and ends at GetDirCount() - 1. |
| Filter listed entries | ListPattern | Use patterns such as *.txt. Do not include a directory path in the pattern; change to the directory first. |
| Request LIST options | ListOption | Applies only when Chilkat uses LIST, not MLSD. |
| Prefer machine-readable listings | AllowMlsd = true | MLSD is preferred when supported because it provides more reliable metadata. |
| Force NLST instead of LIST | PreferNlst | Useful only in rare cases. NLST usually does not provide size or date/time information. |
| Clear cached listing data | ClearDirCache | Forces the next listing-related call to retrieve fresh data from the server. |
Transfer Options
| Feature | Members | Purpose |
|---|---|---|
| Resume next transfer | RestartNext | Set to true before retrying an interrupted upload or download. |
| Detect partial download | PartialTransfer | Indicates whether the previous download received only part of the file. |
| Binary vs ASCII transfer type | SetTypeBinary, SetTypeAscii, CrlfMode | Binary is normally preferred for exact file preservation. ASCII mode can convert line endings for text files. |
| Large file reliability | LargeFileMeasures | Helps keep the control channel lightly active during very long transfers. |
| Bandwidth throttling | BandwidthThrottleUp, BandwidthThrottleDown | Upload throttling is straightforward. Download throttling is less reliable because the FTP server sends data as fast as possible. |
| Upload allocation | AllocateSize | Sends an FTP ALLO command before uploading when a server requires space reservation. |
| Upload verification | AutoXcrc | Uses the server’s XCRC capability, when available, to verify uploaded content. |
| Compressed transfers | HasModeZ, SetModeZ | Enables MODE Z compressed transfers when the server supports it. |
Synchronization and Recursive Transfer
The class includes high-level methods for transferring whole directory trees and synchronizing local and remote folders. These methods are useful for deployment, mirroring, backups, and recurring file exchange workflows.
| Task | Use | Notes |
|---|---|---|
| Upload a complete local tree | PutTree | Uploads a local directory tree to the current remote location. |
| Download a complete remote tree | DownloadTree | Downloads all files and subdirectories from the current remote directory. |
| Preview a large upload plan | CreatePlan | Creates a list of FTP operations that would be performed by a tree upload. |
| Execute or resume an upload plan | PutPlan | Can skip operations already recorded in a plan log after an interrupted upload. |
| Sync local directory from server | SyncLocalDir, SyncLocalTree | Downloads missing or changed remote files to the local filesystem. |
| Sync remote directory from local files | SyncRemoteTree, SyncRemoteTree2 | Uploads missing or changed local files to the FTP server. |
| Delete remote files not present locally | SyncDeleteRemote | Useful for mirroring local state to a remote FTP location. |
| Filter sync and tree operations | SyncMustMatch, SyncMustNotMatch, SyncMustMatchDir, SyncMustNotMatchDir | Uses semicolon-separated wildcard patterns, such as *.xml;*.txt;*.csv. |
Character Encoding
FTP servers vary in how they encode filenames, directory listings, and command arguments. Chilkat provides separate settings for command encoding and directory listing interpretation.
| Setting | Purpose | Guidance |
|---|---|---|
| CommandCharset | Controls the character set used for FTP commands sent to the server. | Defaults to ansi, but may be changed to utf-8 when the server advertises UTF8 support. |
| DirListingCharset | Controls how directory listing bytes are decoded into filenames. | Important for non-English filenames. Like CommandCharset, it may be changed automatically after server feature detection. |
| AutoFeat | Automatically sends FEAT after connecting. | Allows Chilkat to discover server capabilities such as UTF8, MLSD, AUTH TLS, REST STREAM, and SIZE. |
| AutoOptsUtf8 | Automatically sends OPTS UTF8 ON when supported. | Enabled by default and usually helpful for international filenames. |
Proxy Support
| Proxy Type | Members | Use Case |
|---|---|---|
| FTP Proxy / Firewall Proxy | ProxyMethod, ProxyHostname, ProxyPort, ProxyUsername, ProxyPassword, DetermineProxyMethod | Supports multiple legacy FTP proxy login schemes. DetermineProxyMethod can test common proxy methods. |
| HTTP Proxy | HttpProxyHostname, HttpProxyPort, HttpProxyUsername, HttpProxyPassword, HttpProxyAuthMethod | Used when FTP traffic must pass through an HTTP proxy. |
| SOCKS Proxy | SocksVersion, SocksHostname, SocksPort, SocksUsername, SocksPassword | Supports SOCKS4 and SOCKS5. Set SocksVersion to 4 or 5 to enable. |
Secure Credential Handling
EnableSecrets allows selected password properties to accept a Chilkat secret specification string instead of a literal password. Chilkat can then resolve the secret from platform secure storage.
| Feature | Details |
|---|---|
| Supported secure stores | Windows Credential Manager on Windows and Apple Keychain on macOS. |
| Secret string format | !![appName|]service[|domain]|username |
| Applies to | Password, HttpProxyPassword, ProxyPassword, and SocksPassword. |
Best practice:
Use EnableSecrets when possible to avoid embedding
FTP, FTPS, proxy, or SOCKS passwords directly in application source code.
Diagnostics and Troubleshooting
FTP problems are often caused by firewalls, NAT, proxy settings, TLS settings, or data-connection negotiation. Chilkat exposes both protocol-level and connection-level diagnostics to help identify the failing step.
| Diagnostic Need | Use |
|---|---|
| Detailed text for the last method call | LastErrorText |
| Last FTP server reply | LastReply |
| Initial greeting after connecting | Greeting |
| Connection failure category | ConnectFailReason |
| Whether TCP connection succeeded | ConnectVerified |
| Whether login succeeded | LoginVerified |
| Check current connection/login state | CheckConnection |
| In-memory FTP protocol transcript | Set KeepSessionLog = true, then read SessionLog. |
| Discover working FTP settings | DetermineSettings |
| Discover supported server features | Feat |
| Get structured details after selected calls | GetLastJsonData |
Common troubleshooting pattern:
If login succeeds but listings or transfers fail, focus on passive/active mode,
NAT behavior, EPSV, firewall rules, and whether the failure occurs while opening
the data connection.
Best Practices
| Recommendation | Reason |
|---|---|
| Prefer explicit FTPS with AuthTls = true when FTPS is required. | Explicit FTPS on port 21 is more common than implicit FTPS on port 990. |
| Use passive mode first. | Passive = true is the default and is usually the most compatible choice for clients behind NAT or firewalls. |
| When passive transfers fail, test with UseEpsv both enabled and disabled. | EPSV can help in some environments but can also fail with certain deep-inspection firewalls. |
| Use AllowMlsd = true unless a server requires otherwise. | MLSD generally provides better, machine-readable directory listing data than traditional LIST output. |
| Use 64-bit size methods for large files. | Prefer GetSize64 and GetSizeByName64 when files may exceed 32-bit sizes. |
| Use RestartNext for resumable transfers. | A failed upload or download can often be resumed by setting this property before retrying the transfer. |
| Use LastErrorText and session logging for support cases. | FTP failures are often server- or network-specific. The raw replies and protocol transcript are essential for diagnosis. |
| Use EnableSecrets for credentials. | It avoids hard-coding passwords and allows secure runtime resolution from the operating system’s credential store. |
Summary
Chilkat.Ftp2 is a comprehensive FTP/FTPS client class for applications that need reliable file transfer and remote file management. It covers connection setup, TLS security, passive and active data connections, uploads, downloads, directory listings, recursive tree operations, synchronization, metadata inspection, proxy support, credential protection, and deep diagnostics.
For SSH-based file transfer, use an SFTP-specific class instead. FTPS and SFTP are different protocols even though both provide secure file transfer.