Object Creation

Properties

AbortCurrent

When set to 1, causes the currently running method to abort. Methods that always finish quickly (i.e.have no length file operations or network communications) are not affected. If no method is running, then this property is automatically reset to 0 when the next method is called. When the abort occurs, this property is reset to 0. Both synchronous and asynchronous method calls can be aborted. (A synchronous method call could be aborted by setting this property from a separate thread.)

ActivePortRangeEnd

When Active (i.e. PORT) mode is used (opposite of Passive), the client-side is responsible for choosing a random port for each data connection. (Note: In the FTP protocol, each data transfer occurs on a separate TCP/IP connection. Commands are sent over the control channel (port 21 for non-SSL, port 990 for SSL).)

This property, along with ActivePortRangeStart, allows the client to specify a range of ports for data connections.

AllowMlsd

If 1, then uses the MLSD command to fetch directory listings when the FTP server supports MLSD. This property is 1 by default.

When MLSD is used, the GetPermissions method will return the "perm fact" for a given file or directory. This is a different format than the more commonly recognized UNIX permissions string. Note: MLSD provides more accurate and dependable file listings, especially for last-mod date/time information. If usage of the MLSD command is turned off, it may adversely affect the quality and availability of other information.

AsyncBytesReceived

The number of bytes received during an asynchronous FTP download. This property is updated in real-time and an application may periodically fetch and display it's value while the download is in progress.

AsyncBytesReceived64

AsyncBytesReceivedStr

# $strVal is a string
# $ckStr is a CkString$ftp2->get_AsyncBytesReceivedStr($ckStr);
$strVal = $ftp2->asyncBytesReceivedStr();

The number of bytes received during an asynchronous FTP download. This property is updated in real-time and an application may periodically fetch and display it's value while the download is in progress.

AsyncBytesSent64

AsyncBytesSentStr

# $strVal is a string
# $ckStr is a CkString$ftp2->get_AsyncBytesSentStr($ckStr);
$strVal = $ftp2->asyncBytesSentStr();

The number of bytes sent during an asynchronous FTP upload. This string property is updated in real-time and an application may periodically fetch and display it's value while the upload is in progress.

AsyncFinished

# $boolVal is a boolean$boolVal = $ftp2->get_AsyncFinished();

This property is deprecated. It will be removed in a future version.

Set to 1 if the asynchronous transfer (download or upload) is finished.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

AsyncLog

# $strVal is a string
# $ckStr is a CkString$ftp2->get_AsyncLog($ckStr);
$strVal = $ftp2->asyncLog();

This property is deprecated. It will be removed in a future version.

The last-error information for an asynchronous (background) file transfer.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

AsyncPercentDone

# $intVal is a unsigned long$intVal = $ftp2->get_AsyncPercentDone();

This property is deprecated. It will be removed in a future version.

The current percentage completed of an asynchronous FTP upload or download. This property is updated in real-time and an application may periodically fetch and display it's value while the asynchronous data transfer is in progress.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

AsyncSuccess

# $boolVal is a boolean$boolVal = $ftp2->get_AsyncSuccess();

This property is deprecated. It will be removed in a future version.

Set to 1 if the asynchronous file transfer succeeded.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

AuthSsl

Same as AuthTls, except the command sent to the FTP server is "AUTH SSL" instead of "AUTH TLS". Most FTP servers accept either. AuthTls is more commonly used. If a particular server has trouble with AuthTls, try AuthSsl instead.

AuthTls

Set this to 1 to switch to a TLS 1.0 encrypted channel. This property should be set prior to connecting. If this property is set, the port typically remains at it's default (21) and the Ssl property should *not* be set. When AuthTls is used, all control and data transmissions are encrypted. If your FTP client is behind a network-address-translating router, you may need to call ClearControlChannel after connecting and authenticating (i.e. after calling the Connect method). This keeps all data transmissions encrypted, but clears the control channel so that commands are sent unencrypted, thus allowing the router to translate network IP numbers in FTP commands.

AutoFeat

When 1 (which is the default value), a "FEAT" command is automatically sent to the FTP server immediately after connecting. This allows the Chilkat FTP2 component to know more about the server's capabilities and automatically adjust any applicable internal settings based on the response. In rare cases, some FTP servers reject the "FEAT" command and close the connection. Usually, if an FTP server does not implement FEAT, a harmless "command not understood" response is returned.

AutoGetSizeForProgress

Forces the component to retrieve each file's size prior to downloading for the purpose of monitoring percentage completion progress. For many FTP servers, this is not required and therefore for performance reasons this property defaults to 0.

AutoSetUseEpsv

If 1 then the UseEpsv property is automatically set upon connecting to the FTP server. The default value of this property is 0.

If the AutoFeat property is 1, and if the AutoSetUseEpsv property is 1, then the FTP server's features are automatically queried when connecting. In this case, the UseEpsv property is automatically set to 1 if the FTP server supports EPSV.

Important: EPSV can cause problems with some deep-inspection firewalls. If a passive data connection cannot be established, make sure to test with both the AutoSetUseEpsv and UseEpsv properties set equal to 0.

AutoSyst

When 1 (which is the default value), a "SYST" command is automatically sent to the FTP server immediately after connecting. This allows the Chilkat FTP2 component to know more about the server and automatically adjust any applicable internal settings based on the response. If the SYST command causes trouble (which is rare), this behavior can be turned off by setting this property equal to 0.

AutoXcrc

Many FTP servers support the XCRC command. The Chilkat FTP component will automatically know if XCRC is supported because it automatically sends a FEAT command to the server immediately after connecting.

If this property is set to 1, then all uploads will be automatically verified by sending an XCRC command immediately after the transfer completes. If the CRC is not verified, the upload method (such as PutFile) will return a failed status.

BandwidthThrottleDown

If set to a non-zero value, the FTP2 component will bandwidth throttle all downloads to this value.

The default value of this property is 0. The value should be specified in bytes/second.

Note: It is difficult to throttle very small downloads. (For example, how do you bandwidth throttle a 1-byte download???) As the downloaded file size gets larger, the transfer rate will better approximate this property's setting.

BandwidthThrottleUp

If set to a non-zero value, the FTP2 component will bandwidth throttle all uploads to this value.

The default value of this property is 0. The value should be specified in bytes/second.

Note: It is difficult to throttle very small uploads. (For example, how do you bandwidth throttle a 1-byte upload???) As the uploaded file size gets larger, the transfer rate will better approximate this property's setting.

ClientIpAddress

The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.

The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124".

CommandCharset

Indicates the charset to be used for commands sent to the FTP server. The command charset must match what the FTP server is expecting in order to communicate non-English characters correctly. The default value of this property is "ansi".

This property may be updated to "utf-8" after connecting because a "FEAT" command is automatically sent to get the features of the FTP server. If UTF8 is indicated as a feature, then this property is automatically changed to "utf-8".

CrlfMode

Used to control CRLF line endings when downloading text files in ASCII mode. The default value is 0.

Possible values are:

0 = Do nothing. The line-endings are not modified as received from the FTP server.
1 = Convert all line-endings to CR+LF
2 = Convert all line-endings to bare LF's
3 = Convert all line-endings to bare CR's

DataProtection

Controls the data protection level for the data connections. Possible values are "control", "clear", or "private".

"control" is the default, and the data connections will be the same as for the control connection. If the control connection is SSL/TLS, then the data connections are also SSL/TLS. If the control connection is unencrypted, then the data connections will also be unencrypted.

DebugLogFilePath

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes).
A hang or crash should generally never happen. The typical causes of a hang are:

a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,

the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or

there is an internal problem (bug) in the Chilkat code that causes the hang.

DirListingCharset

Indicates the charset of the directory listings received from the FTP server. The FTP2 client must interpret the directory listing bytes using the correct character encoding in order to correctly receive non-English characters. The default value of this property is "ansi".

This property may be updated to "utf-8" after connecting because a "FEAT" command is automatically sent to get the features of the FTP server. If UTF8 is indicated as a feature, then this property is automatically changed to "utf-8".

ForcePortIpAddress

If set, forces the IP address used in the PORT command for Active mode (i.e. non-passive) data transfers. This string property should be set to the IP address in dotted notation, such as "233.190.65.31".

Note: This property can also be set to the special keyword "control" to force the PORT IP address to be the address of the control connection's peer.

Starting in v9.5.0.58, the IP address can be prefixed with the string "bind-". For example, "bind-233.190.65.31". When "bind-" is specified, the local data socket will be bound to the IP address when created. Otherwise, the IP address is only used as the argument to the PORT command that is sent to the server.

Greeting

HasModeZ

# $boolVal is a boolean$boolVal = $ftp2->get_HasModeZ();

Chilkat FTP2 supports MODE Z, which is a transfer mode implemented by some FTP servers. It allows for files to be uploaded and downloaded using compressed streams (using the zlib deflate algorithm). This is a read-only property. It will be set to 1 if the FTP2 component detects that your FTP server supports MODE Z. Otherwise it is set to 0.

IdleTimeoutMs

Forces a timeout when a response is expected on the control channel, but no response arrives for this number of milliseconds. Setting IdleTimeoutMs = 0 allows the application to wait indefinitely. The default value is 60000 (i.e. 60 seconds).

LargeFileMeasures

Enables internal features that can help when downloading extremely large files. In some cases, if the time required to download a file is long, the control connection is closed by the server or other network infrastructure because it was idle for so long. Setting this property equal to 1 will keep the control connection very slightly used to prevent this from happening.

The default value of this property is 0. This property should only be set to 1 if this sort of problem is encountered.

LastErrorText

# $strVal is a string
# $ckStr is a CkString$ftp2->get_LastErrorText($ckStr);
$strVal = $ftp2->lastErrorText();

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

LastMethodSuccess

Indicate whether the last method call succeeded or failed. A value of 1 indicates success, a value of 0 indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

LastReply

# $strVal is a string
# $ckStr is a CkString$ftp2->get_LastReply($ckStr);
$strVal = $ftp2->lastReply();

Contains the last control-channel reply. For example: "550 Failed to change directory." or "250 Directory successfully changed." The control channel reply is typically formatted as an integer status code followed by a one-line description.

ListPattern

A wildcard pattern, defaulting to "*" that determines the files and directories included in the following properties and methods: GetDirCount, NumFilesAndDirs, GetCreateTime, GetFilename, GetIsDirectory, GetLastAccessTime, GetModifiedTime, GetSize.

Note: Do not include a directory path in the ListPattern. For example, do not set the ListPattern equal to a string such as this: "subdir/*.txt". The correct solution is to first change the remote directory to "subdir" by calling ChangeRemoteDir, and then set the ListPattern equal to "*.txt".

NumFilesAndDirs

Important: This property is deprecated. Applications should instead call the GetDirCount method.

The number of files and sub-directories in the current remote directory that match the ListPattern. (The ListPattern defaults to "*", so unless changed, this is the total number of files and sub-directories.)

Important: Accessing this property can cause the directory listing to be retrieved from the FTP server. For FTP servers that doe not support the MLST/MLSD commands, this is technically a data transfer that requires a temporary data connection to be established in the same way as when uploading or downloading files. If your program hangs while accessing NumFilesAndDirs, it probably means that the data connection could not be established. The most common solution is to switch to using Passive mode by setting the Passive property = 1. If this does not help, examine the contents of the LastErrorText property after NumFilesAndDirs finally returns (after timing out). Also, see this Chilkat blog post about FTP connection settings.

PartialTransfer

# $boolVal is a boolean$boolVal = $ftp2->get_PartialTransfer();

A read-only property that indicates whether a partial transfer was received in the last method call to download a file. Set to 1 if a partial transfer was received. Set to 0 if nothing was received, or if the full file was received.

PassiveUseHostAddr

This can handle problems that may arise when an FTP server is located behind a NAT router. FTP servers respond to the PASV command by sending the IP address and port where it will be listening for the data connection. If the control connection is SSL encrypted, the NAT router is not able to convert from an internal IP address (typically beginning with 192.168) to an external address. When set to 1, PassiveUseHostAddr property tells the FTP client to discard the IP address part of the PASV response and replace it with the IP address of the already-established control connection. The default value of this property is 0.

PreferNlst

If 1, the NLST command is used instead of LIST when fetching a directory listing. This can help in very rare cases where the FTP server returns truncated filenames. The drawback to using NLST is that it won't return size or date/time info (but it should return the full filename).

ProgressMonSize

Progress monitoring for FTP downloads rely on the FTP server indicating the file size within the RETR response. Some FTP servers however, do not indicate the file size and therefore it is not possible to monitor progress based on percentage completion. This property allows the application to explicitly tell the FTP component the size of the file about to be downloaded for the next GetFile call.

ReadTimeout

Forces a timeout when incoming data is expected on a data channel, but no data arrives for this number of seconds.
The ReadTimeout is the amount of time that needs to elapse while no additional data is forthcoming. During a long download, if the data stream halts for more than this amount, it will timeout. Otherwise, there is no limit on the length of time for the entire download.

RequireSslCertVerify

If 1, then the FTP2 client will verify the server's SSL certificate. The server's certificate signature is verified with its issuer, and the issuer's cert is verified with its issuer, etc. up to the root CA cert. If a signature verification fails, the connection is not allowed. Also, if the certificate is expired, or if the cert's signature is invalid, the connection is not allowed. The default value of this property is 0.

SendBufferSize

This property is now deprecated, and has no effect in Chilkat versions 9.5.0.69 and greater.

In the past, it affected how often percent completion callbacks were made. Setting it to a smaller value caused more frequent percentage completion event callbacks. The default value is 65536 (64K) and should generally not be changed.

SslAllowedCiphers

Provides a means for setting a list of ciphers that are allowed for SSL/TLS connections. The default (empty string) indicates that all implemented ciphers are possible. The TLS ciphers supported in Chilkat v9.5.0.55 and later are:

To restrict SSL/TLS connections to one or more specific ciphers, set this property to a comma-separated list of ciphers such as "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384". The order should be in terms of preference, with the preferred algorithms listed first. (Note that the client cannot specifically choose the algorithm is picked because it is the server that chooses. The client simply provides the server with a list from which to choose.)

The property can also disallow connections with servers having certificates with RSA keys less than a certain size. By default, server certificates having RSA keys of 512 bits or greater are allowed. Add the keyword "rsa1024" to disallow connections with servers having keys smaller than 1024 bits. Add the keyword "rsa2048" to disallow connections with servers having keys smaller than 2048 bits.

Note: Prior to Chilkat v9.5.0.55, it was not possible to explicitly list allowed cipher suites. The deprecated means for indicating allowed ciphers was both incomplete and unprecise. For example, the following keywords could be listed to allow matching ciphers: "aes256-cbc", "aes128-cbc", "3des-cbc", and "rc4". These keywords will still be recognized, but programs should be updated to explicitly list the allowed ciphers.

secure-renegotiation: Starting in Chilkat v9.5.0.55, the keyword "secure-renegotiation" may be added to require that all renegotions be done securely (as per RFC 5746).

best-practices: Starting in Chilkat v9.5.0.55, this property may be set to the single keyword "best-practices". This will allow ciphers based on the current best practices. As new versions of Chilkat are released, the best practices may change. Changes will be noted here. The current best practices are:

The default value is "default" which will choose the, which allows for the protocol to be selected dynamically at runtime based on the requirements of the server. Choosing an exact protocol will cause the connection to fail unless that exact protocol is negotiated. It is better to choose "X or higher" than an exact protocol. The "default" is effectively "SSL 3.0 or higher".
top

SyncedFiles

The paths of the files uploaded or downloaded in the last call to SyncDeleteTree, SyncLocalDir, SyncLocalTree, SyncRemoteTree, or SyncRemoteTree2. The paths are listed one per line. In both cases (for upload and download) each line contains the paths relative to the root synced directory.

SyncMustMatch

Can contain a wildcarded list of file patterns separated by semicolons. For example, "*.xml; *.txt; *.csv". If set, the Sync* upload and download methods will only transfer files that match any one of these patterns. Pattern matching is case-insensitive.

Note: Starting in version 9.5.0.47, this property also applies to the DownloadTree and DirTreeXml methods.

SyncMustNotMatch

Can contain a wildcarded list of file patterns separated by semicolons. For example, "*.xml; *.txt; *.csv". If set, the Sync* upload and download methods will not transfer files that match any one of these patterns. Pattern matching is case-insensitive.

Note: Starting in version 9.5.0.47, this property also applies to the DownloadTree and DirTreeXml methods.

SyncPreview

# $strVal is a string
# $ckStr is a CkString$ftp2->get_SyncPreview($ckStr);
$strVal = $ftp2->syncPreview();

Contains the list of files that would be transferred in a call to SyncRemoteTree2 when the previewOnly argument is set to 1. This string property contains one filepath per line, separated by CRLF line endings. After SyncRemoteTree2 is called, this property contains the filepaths of the local files that would be uploaded to the FTP server.

TlsCipherSuite

Contains the current or last negotiated TLS cipher suite. If no TLS connection has yet to be established, or if a connection as attempted and failed, then this will be empty. A sample cipher suite string looks like this: TLS_DHE_RSA_WITH_AES_256_CBC_SHA256.

TlsPinSet

Specifies a set of pins for Public Key Pinning for TLS connections. This property lists the expected SPKI fingerprints for the server certificates. If the server's certificate (sent during the TLS handshake) does not match any of the SPKI fingerprints, then the TLS handshake is aborted and the connection fails. The format of this string property is as follows:

hash_algorithm, encoding, SPKI_fingerprint_1, SPKI_fingerprint_2, ...

For example, the following string specifies a single sha256 base64-encoded SPKI fingerprint:

TlsVersion

Contains the current or last negotiated TLS protocol version. If no TLS connection has yet to be established, or if a connection as attempted and failed, then this will be empty. Possible values are "SSL 3.0", "TLS 1.0", "TLS 1.1", and "TLS 1.2".

UseEpsv

If 1, the FTP2 component will use the EPSV command instead of PASV for passive mode data transfers. The default value of this property is 0. (It is somewhat uncommon for FTP servers to support EPSV.)

Note: If the AutoFeat property is 1, then the FTP server's features are automatically queried after connecting. In this case, if the AutoSetUseEpsv property is also set to 1, the UseEpsv property is automatically set to 1 if the FTP server supports EPSV.

Important: EPSV can cause problems with some deep-inspection firewalls. If a passive data connection cannot be established, make sure to test with both the AutoSetUseEpsv and UseEpsv properties set equal to 0.

Utf8

When set to 1, all "const char *" arguments are interpreted as utf-8 strings. If set to 0 (the default), then "const char *" arguments are interpreted as ANSI strings.
Also, when set to 1, and Chilkat method returning a "const char *" is returning the utf-8 representation. If set to 0, all "const char *" return values are ANSI strings.

VerboseLogging

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

AsyncAbort

$ftp2->AsyncAbort();

This method is deprecated. It will be removed in a future version.

Causes an asynchronous Get or Put to abort.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

AsyncAppendFileStart

Initiates an asynchronous append. The file is uploaded and appended to an existing file on the FTP server. The append happens in a background thread and can be aborted by calling AsyncAbort. The AsyncFinished property can be checked periodically to determine when the background transfer is finished. The status of the transfer is available in the AsyncSuccess property. The last-error information is available in the AsyncLog property. The AsyncBytesSent property is updated in real time to reflect the current number of bytes sent while the transfer is in progress. The UploadRate is also updated with the current upload rate in bytes/second. While a transfer is in progress, a program may periodically read the UploadRate and AsyncBytesSent properties to display progress.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

AsyncGetFileStart

Initiates an asynchronous file download. The download happens in a background thread and can be aborted by calling AsyncAbort. The AsyncFinished property can be checked periodically to determine when the background transfer is finished. The status of the transfer is available in the AsyncSuccess property. The last-error information is available in the AsyncLog property. The AsyncBytesReceived property is updated in real time to reflect the current number of bytes received while the transfer is in progress. The DownloadRate is also updated with the current download rate in bytes/second. While a transfer is in progress, a program may periodically read the DownloadRate and AsyncBytesReceived properties to display progress.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

AsyncPutFileStart

Initiates an asynchronous file upload. The file is uploaded and creates a new file on the FTP server, or overwrites an existing file. The upload happens in a background thread and can be aborted by calling AsyncAbort. The AsyncFinished property can be checked periodically to determine when the background transfer is finished. The status of the transfer is available in the AsyncSuccess property. The last-error information is available in the AsyncLog property. The AsyncBytesSent property is updated in real time to reflect the current number of bytes sent while the transfer is in progress. The UploadRate is also updated with the current upload rate in bytes/second. While a transfer is in progress, a program may periodically read the UploadRate and AsyncBytesSent properties to display progress.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

ClearControlChannel

$status = $ftp2->ClearControlChannel();

Reverts the FTP control channel from SSL/TLS to an unencrypted channel. This may be required when using FTPS with AUTH TLS where the FTP client is behind a DSL or cable-modem router that performs NAT (network address translation). If the control channel is encrypted, the router is unable to translate the IP address sent in the PORT command for data transfers. By clearing the control channel, the data transfers will remain encrypted, but the FTP commands are passed unencrypted. Your program would typically clear the control channel after authenticating.

ClearDirCache

$ftp2->ClearDirCache();

TheNumFilesAndDirs property returns the count of files and sub-directories in the current remote FTP directory, according to the ListPattern property. For example, if ListPattern is set to "*.xml", then NumFilesAndDirs returns the count of XML files in the remote directory.

The 1st time it is accessed, the component will (behind the scenes) fetch the directory listing from the FTP server. This information is cached in the component until (1) the current remote directory is changed, or (2) the ListPattern is changed, or (3) the this method (ClearDirCache) is called.

ClearSessionLog

Connect

Connects and logs in to the FTP server using the username/password provided in the component properties. Check the integer value of the ConnectFailReason if this method returns 0 (indicating failure).

Note: To separately establish the connection and then authenticate (in separate method calls), call ConnectOnly followed by LoginAfterConnectOnly.

Important: All TCP-based Internet communications, regardless of the protocol (such as HTTP, FTP, SSH, IMAP, POP3, SMTP, etc.), and regardless of SSL/TLS, begin with establishing a TCP connection to a remote host:port. External security-related infrastructure such as software firewalls (Windows Firewall), hardware firewalls, anti-virus, at either source or destination (or both) can block the connection. If the connection fails, make sure to check all potential external causes of blockage.

ConnectOnly

$status = $ftp2->ConnectOnly();

Connects to the FTP server, but does not authenticate. The combination of calling this method followed by LoginAfterConnectOnly is the equivalent of calling the Connect method (which both connects and authenticates).

Important: All TCP-based Internet communications, regardless of the protocol (such as HTTP, FTP, SSH, IMAP, POP3, SMTP, etc.), and regardless of SSL/TLS, begin with establishing a TCP connection to a remote host:port. External security-related infrastructure such as software firewalls (Windows Firewall), hardware firewalls, anti-virus, at either source or destination (or both) can block the connection. If the connection fails, make sure to check all potential external causes of blockage.

ConvertToTls

$status = $ftp2->ConvertToTls();

Explicitly converts the control channel to a secure SSL/TLS connection.

Note: If you initially connect with either the AuthTls or AuthSsl property set to 1, then DO NOT call ConvertToTls. The control channel is automatically converted to SSL/TLS from within the Connect method when these properties are set.

CreatePlan

Creates an "FTP plan" that lists the FTP operations that would be performed when PutTree is called. Additionally, the PutPlan method executes an "FTP plan" and logs each successful operation to a plan log file. If a large-scale upload is interrupted, the PutPlan can be resumed, skipping over the operations already listed in the plan log file.

DeleteMatching

Deletes all the files in the current remote FTP directory matching the pattern. Returns the number of files deleted, or -1 for failure. The pattern is a string such as "*.txt", where any number of "*" wildcard characters can be used. "*" matches 0 or more of any character.

DeleteTree

$status = $ftp2->DeleteTree();

Deletes the entire subtree and all files from the current remote FTP directory. To delete a subtree on the FTP server, your program would first navigate to the root of the subtree to be deleted by calling ChangeRemoteDir, and then call DeleteTree. There are two event callbacks: VerifyDeleteFile and VerifyDeleteDir. Both are called prior to deleting each file or directory. The arguments to the callback include the full filepath of the file or directory, and an output-only "skip" flag. If your application sets the skip flag to true, the file or directory is NOT deleted. If a directory is not deleted, all files and sub-directories will remain. Example programs can be found at http://www.example-code.com/

DetermineProxyMethod

$retInt = $ftp2->DetermineProxyMethod();

Automatically determines the ProxyMethod that should be used with an FTP proxy server. Tries each of the five possible ProxyMethod settings and returns the value (1-5) of the ProxyMethod that succeeded.

This method may take a minute or two to complete. Returns 0 if no proxy methods were successful. Returns -1 to indicate an error (i.e. it was unable to test all proxy methods.)

DetermineSettings

Discovers which combinations of FTP2 property settings result in successful data transfers.

DetermineSettings tries 13 different combinations of these properties:

Ssl
AuthTls
AuthSsl
Port
Passive
PassiveUseHostAddr

Within the FTP protocol, the process of fetching a directory listing is also considered a "data transfer". The DetermineSettings method works by checking to see which combinations result in a successful directory listing download. The method takes no arguments and returns a string containing an XML report of the results. It is a blocking call that may take approximately a minute to run. If you are unsure about how to interpret the results, cut-and-paste it into an email and send it to support@chilkatsoft.com.

DownloadTree

# $localRoot is a string
$status = $ftp2->DownloadTree($localRoot);

Downloads an entire tree from the FTP server and recreates the directory tree on the local filesystem.

This method downloads all the files and subdirectories in the current remote directory. An application would first navigate to the directory to be downloaded via ChangeRemoteDir and then call this method.

Note: Starting in version 9.5.0.47, the SyncMustMatch and SyncMustNotMatch properties apply to this method.

GetCreateDtByName

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

Note: Linux/Unix type filesystems do not store "create" date/times. Therefore, if the FTP server is on such as system, this method will return a date/time equal to the last-modified date/time.

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

Note: Linux/Unix type filesystems do not store "create" date/times. If the FTP server is on such as system, this method will return a date/time equal to the last-modified date/time.

GetCreateTimeStr

Returns the create time (in RFC822 string format, such as "Tue, 25 Sep 2012 12:25:32 -0500") for the Nth file or sub-directory in the current remote directory. The first file/dir is at index 0, and the last one is at index (NumFilesAndDirs-1)

GetDirCount

Returns the number of files and sub-directories in the current remote directory that match the ListPattern property.

Important: Calling this method may cause the directory listing to be retrieved from the FTP server. For FTP servers that do not support the MLST/MLSD commands, this is technically a data transfer that requires a temporary data connection to be established in the same way as when uploading or downloading files. If your program hangs while calling this method, it probably means that the data connection could not be established. The most common solution is to switch to using Passive mode by setting the Passive property = 1, with the PassiveUseHostAddr property also set equal to 1. If this does not help, examine the contents of the LastErrorText property after this method finally returns (after timing out). Also, see this Chilkat blog post about FTP connection settings.

GetFileToStream

Downloads a file to a stream. If called synchronously, the remoteFilePath must have a sink, such as a file or another stream object. If called asynchronously, then the foreground thread can read the stream.

GetGroup

Returns group name, if available, for the Nth file. If empty, then no group information is available.

Note: When MLSD is used to get directory listings, it is likely that the owner and group information is not transmitted. In cases where the FTP server is on a UNIX/Linux system, the AllowMlsd property can be set to 0 to force UNIX directory listings instead of MLSD directory listings. This should result in being able to obtain owner/group information. However, it may sacrifice the quality and accuracy of the various date/time values that are returned.

GetLastAccessDtByName

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

GetLastAccessTimeStr

Returns the last access date/time (in RFC822 string format, such as "Tue, 25 Sep 2012 12:25:32 -0500") for the Nth file or sub-directory in the current remote directory. The first file/dir is at index 0, and the last one is at index (NumFilesAndDirs-1)

GetLastModDtByName

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

GetLastModifiedTimeStr

Returns the last modified date/time (in RFC822 string format, such as "Tue, 25 Sep 2012 12:25:32 -0500") for the Nth file or sub-directory in the current remote directory. The first file/dir is at index 0, and the last one is at index (NumFilesAndDirs-1)

GetOwner

Returns owner name, if available, for the Nth file. If empty, then no owner information is available.

Note: When MLSD is used to get directory listings, it is likely that the owner and group information is not transmitted. In cases where the FTP server is on a UNIX/Linux system, the AllowMlsd property can be set to 0 to force UNIX directory listings instead of MLSD directory listings. This should result in being able to obtain owner/group information. However, it may sacrifice the quality and accuracy of the various date/time values that are returned.

GetPermissions

Returns permissions information, if available, for the Nth file. If empty, then no permissions information is available. The value returned by the GetPermType method defines the content and format of the permissions string returned by this method. Possible permission types are "mlsd", "unix", "netware", "openvms", and "batchStatusFlags". The format of each permission type is as follows:

PermType: mlsd:

A "perm fact" is returned. The format of the perm fact is defined in RFC 3659 as follows:

The perm fact is used to indicate access rights the current FTP user
has over the object listed. Its value is always an unordered
sequence of alphabetic characters.
perm-fact = "Perm" "=" *pvals
pvals = "a" / "c" / "d" / "e" / "f" /
"l" / "m" / "p" / "r" / "w"
There are ten permission indicators currently defined. Many are
meaningful only when used with a particular type of object. The
indicators are case independent, "d" and "D" are the same indicator.
The "a" permission applies to objects of type=file, and indicates
that the APPE (append) command may be applied to the file named.
The "c" permission applies to objects of type=dir (and type=pdir,
type=cdir). It indicates that files may be created in the directory
named. That is, that a STOU command is likely to succeed, and that
STOR and APPE commands might succeed if the file named did not
previously exist, but is to be created in the directory object that
has the "c" permission. It also indicates that the RNTO command is
likely to succeed for names in the directory.
The "d" permission applies to all types. It indicates that the
object named may be deleted, that is, that the RMD command may be
applied to it if it is a directory, and otherwise that the DELE
command may be applied to it.
The "e" permission applies to the directory types. When set on an
object of type=dir, type=cdir, or type=pdir it indicates that a CWD
command naming the object should succeed, and the user should be able
to enter the directory named. For type=pdir it also indicates that
the CDUP command may succeed (if this particular pathname is the one
to which a CDUP would apply.)
The "f" permission for objects indicates that the object named may be
renamed - that is, may be the object of an RNFR command.
The "l" permission applies to the directory file types, and indicates
that the listing commands, LIST, NLST, and MLSD may be applied to the
directory in question.
The "m" permission applies to directory types, and indicates that the
MKD command may be used to create a new directory within the
directory under consideration.
The "p" permission applies to directory types, and indicates that
objects in the directory may be deleted, or (stretching naming a
little) that the directory may be purged. Note: it does not indicate
that the RMD command may be used to remove the directory named
itself, the "d" permission indicator indicates that.
The "r" permission applies to type=file objects, and for some
systems, perhaps to other types of objects, and indicates that the
RETR command may be applied to that object.
The "w" permission applies to type=file objects, and for some
systems, perhaps to other types of objects, and indicates that the
STOR command may be applied to the object named.
Note: That a permission indicator is set can never imply that the
appropriate command is guaranteed to work -- just that it might.
Other system specific limitations, such as limitations on
available space for storing files, may cause an operation to fail,
where the permission flags may have indicated that it was likely
to succeed. The permissions are a guide only.
Implementation note: The permissions are described here as they apply
to FTP commands. They may not map easily into particular
permissions available on the server's operating system. Servers
are expected to synthesize these permission bits from the
permission information available from operating system. For
example, to correctly determine whether the "D" permission bit
should be set on a directory for a server running on the UNIX(TM)
operating system, the server should check that the directory named
is empty, and that the user has write permission on both the
directory under consideration, and its parent directory.
Some systems may have more specific permissions than those listed
here, such systems should map those to the flags defined as best
they are able. Other systems may have only more broad access
controls. They will generally have just a few possible
permutations of permission flags, however they should attempt to
correctly represent what is permitted.

PermType: unix:

A Unix/Linux permissions string is returned ( such as "drwxr-xr-x" or "-rw-r--r--")

The UNIX permissions string is 10 characters. Each character has a specific meaning. If the first character is:
d the entry is a directory.
b the entry is a block special file.
c the entry is a character special file.
l the entry is a symbolic link. Either the -N flag was specified, or the symbolic link did not point to an existing file.
p the entry is a first-in, first-out (FIFO) special file.
s the entry is a local socket.
- the entry is an ordinary file.
The next nine characters are divided into three sets of three characters each. The first set of three characters show
the owner's permission. The next set of three characters show the permission of the other users in the group. The last
set of three characters shows the permission of anyone else with access to the file. The three characters in each set
indicate, respectively, read, write, and execute permission of the file. With execute permission of a directory, you can search
a directory for a specified file. Permissions are indicated like this:
r read
w write (edit)
x execute (search)
- corresponding permission not granted

Contains the batch status flags from a Connect:Enterprise Server. Such as "-CR--M----" or "-ART------".

The Batch Status Flags is a 10-character string where each character describes an attribute of the batch.
A dash indicates that flag is turned off and therefore has no meaning to the
batch in question. The flags are always displayed in the same order:
1) I -- Incomplete batch which will NOT be processed.
2) A or C -- Added or Collected
3) R -- Requestable by partner
4) T -- Transmitted to partner
5) E -- Extracted (inbound file processed by McLane)
6) M -- Multi-transmittable
7) U -- Un-extractable
8) N -- Non-transmittable
9) P -- In Progress
10) - -- Always a dash.

GetPermType

Returns the type of permissions information that is available for the Nth file. If empty, then no permissions information is available. The value returned by this method defines the content and format of the permissions string returned by the GetPermissions method. Possible values are "mlsd", "unix", "netware", "openvms", and "batchStatusFlags".

GetRemoteFileTextData

Downloads the content of a remote text file directly into an in-memory string.

Note: If the remote text file does not use the ANSI character encoding, call GetRemoteFileTextC instead, which allows for the character encoding to be specified so that characters are properly interpreted.

GetSize64

GetSizeByName

# $filename is a string
$retInt = $ftp2->GetSizeByName($filename);

Returns a remote file's size in bytes. Returns -1 if the file does not exist.

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

GetSizeByName64

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

GetSizeStrByName

Returns the size of a remote file as a string. This is helpful when file a file size is greater than what can fit in a 32-bit integer.

Note: The filename passed to this method must NOT include a path. Prior to calling this method, make sure to set the current remote directory (via the ChangeRemoteDir method) to the remote directory where this file exists.

Note: Prior to calling this method, it should be ensured that the ListPattern property is set to a pattern that would match the requested filename. (The default value of ListPattern is "*", which will match all filenames.)

LargeFileUpload

This is the same as PutFile, but designed to work around the following potential problem associated with an upload that is extremely large.

FTP uses two TCP (or TLS) connections: a control connection to submit commands and receive replies, and a data connection for actual file transfers.
It is the nature of FTP that during a transfer the control connection stays completely idle.
Many routers and firewalls automatically close idle connections after a certain period of time.
Worse, they often don't notify the user, but just silently drop the connection.

For FTP, this means that during a long transfer the control connection can get dropped because it is detected as idle, but neither client nor server are notified.
When all data has been transferred, the server assumes the control connection is alive
and it sends the transfer confirmation reply.

Likewise, the client thinks the control connection is alive and it waits for the reply from the server.
But since the control connection got dropped without notification,
the reply never arrives and eventually the connection will timeout.

The Solution: This method uploads the file in chunks, where each chunk appends to the remote file. This way, each chunk is a separate FTP upload that does not take too long to complete.
The chunkSize specifies the number of bytes to upload in each chunk. The size should be based on the amount of memory available (because each chunk will reside in memory as it's being uploaded), the transfer rate, and the total size of the file being uploaded. For example, if a 4GB file is uploaded, and the chunkSize is set to 1MB (1,048,576 bytes), then 4000 separate chunks would be required. This is likely not a good choice for chunkSize. A more appropriate chunkSize might be 20MB, in which case the upload would complete in 200 separate chunks. The application would temporarily be using a 20MB buffer for uploading chunks. The tradeoff is between the number of chunks (the more chunks, the larger the overall time to upload), the amount of memory that is reasonable for the temporary buffer, and the amount of time required to upload each chunk (if the chunk size is too large, then the problem described above is not solved).

LoginAfterConnectOnly

$status = $ftp2->LoginAfterConnectOnly();

Authenticates with the FTP server using the values provided in the Username, Password, and/or other properties. This can be called after establishing the connection via the ConnectOnly method. (The Connect method both connects and authenticates.) The combination of calling ConnectOnly followed by LoginAfterConnectOnly is the equivalent of calling the Connect method.

Note: After successful authentication, the FEAT and SYST commands are automatically sent to help the client understand what is supported by the FTP server. To prevent these commands from being sent, set the AutoFeat and/or AutoSyst properties equal to 0.

MGetFiles

Copies all the files in the current remote FTP directory to a local directory. To copy all the files in a remote directory, set remotePattern to "*.*" The pattern can contain any number of "*"characters, where "*" matches 0 or more of any character. The return value is the number of files transferred, and on error, a value of -1 is returned. Detailed information about the transfer can be obtained from the last-error information (LastErrorText/LastErrorHtml/LastErrorXml/SaveLastError).

About case sensitivity: The MGetFiles command works by sending the "LIST" command to the FTP server. For example: "LIST *.txt". The FTP server responds with a directory listing of the files matching the wildcarded pattern, and it is these files that are downloaded. Case sensitivity depends on the case-sensitivity of the remote file system. If the FTP server is running on a Windows-based computer, it is likely to be case insensitive. However, if the FTP server is running on Linux, MAC OS X, etc. it is likely to be case sensitive. There is no good way to force case-insensitivity if the remote filesystem is case-sensitive because it is not possible for the FTP client to send a LIST command indicating that it wants the matching to be case-insensitive.

MPutFiles

# $pattern is a string
$retInt = $ftp2->MPutFiles($pattern);

Uploads all the files matching pattern on the local computer to the current remote FTP directory. The pattern parameter can include directory information, such as "C:/my_dir/*.txt" or it can simply be a pattern such as "*.*" that matches the files in the application's current directory. Subdirectories are not recursed. The return value is the number of files copied, with a value of -1 returned for errors. Detailed information about the transfer can be obtained from the XML log.[

NlstXml

Sends an NLST command to the FTP server and returns the results in XML format. The NLST command returns a list of filenames in the given directory (matching the pattern). The remoteDirPattern should be a pattern such as "*", "*.*", "*.txt", "subDir/*.xml", etc.

PutPlan

Executes an "FTP plan" (created by the CreatePlan method) and logs each successful operation to a plan log file. If a large-scale upload is interrupted, the PutPlan can be resumed, skipping over the operations already listed in the plan log file. When resuming an interrupted PutPlan method, use the same log file. All completed operations found
in the already-existing log will automatically be skipped.

PutTree

# $localDir is a string
$status = $ftp2->PutTree($localDir);

Uploads an entire directory tree from the local filesystem to the remote FTP server, recreating the directory tree on the server. The PutTree method copies a directory tree to the current remote directory on the FTP server.

RenameRemoteFile

Renames a file or directory on the FTP server. To move a file from one directory to another on a remote FTP server, call this method and include the source and destination directory filepath.

If the existingRemoteFilePath or newRemoteFilePath contains non-English characters, it may be necessary to set the DirListingCharset property equal to "utf-8". Please refer to the documentation for the DirListingCharset property.

SetOldestDateStr

# $oldestDateTimeStr is a string
$ftp2->SetOldestDateStr($oldestDateTimeStr);

Used in conjunction with the DownloadTree method. Call this method prior to calling DownloadTree to set the oldest date for a file to be downloaded. When DownloadTree is called, any file older than this date will not be downloaded.

The oldestDateTimeStr should be a date/time string in RFC822 format, such as "Tue, 25 Sep 2012 12:25:32 -0500".

SetOption

This is a general purpose method to set miscellaneous options that might arise due to buggy or quirky FTP servers. The option is a string describing the option. The current list of possible options are:

"Microsoft-TLS-1.2-Workaround" -- This is to force the data connection to use TLS 1.0 instead of the default. It works around the Microsoft FTP server bug found here: https://support.microsoft.com/en-us/kb/2888853

To turn off an option, prepend the string "No-". For example "No-Microsoft-TLS-1.2-Workaround". All options are turned off by default.

SetSslCertRequirement

# $reqName is a string
# $reqValue is a string
$ftp2->SetSslCertRequirement($reqName, $reqValue);

Enforces a requirement on the FTP server's certificate. The reqName can be "SubjectDN", "SubjectCN", "IssuerDN", or "IssuerCN". The reqName specifies the part of the certificate, and the reqValue is the value that it must match (exactly). If the FTP server's certificate does not match, the SSL / TLS connection is aborted.

SetSslClientCertPem

Allows for a client-side certificate to be used for the SSL / TLS connection. If the PEM requires no password, pass an empty string in pemPassword. If the PEM is in a file, pass the path to the file in pemDataOrFilename. If the PEM is already loaded into a string variable, then pass the string containing the contents of the PEM in pemDataOrFilename.

SyncLocalDir

The same as SyncLocalTree, except the sub-directories are not traversed. The files in the current remote directory are synchronized (downloaded) with the files in localRoot. For possible mode settings, see SyncLocalTree.

Note: In v9.5.0.51 and higher, the list of downloaded files is available in the SyncedFiles property.

SyncLocalTree

Downloads files from the FTP server to a local directory tree. Synchronization modes include:

mode=0: Download all files
mode=1: Download all files that do not exist on the local filesystem.
mode=2: Download newer or non-existant files.
mode=3: Download only newer files. If a file does not already exist on the local filesystem, it is not downloaded from the server.
mode=5: Download only missing files or files with size differences.
mode=6: Same as mode 5, but also download newer files.
mode=99: Do not download files, but instead delete remote files that do not exist locally.
* There is no mode #4. It is a mode used internally by the DirTreeXml method.

Note: In v9.5.0.51 and higher, the list of downloaded (or deleted) files is available in the SyncedFiles property.

SyncRemoteTree

Uploads a directory tree from the local filesystem to the FTP server. Synchronization modes include:

mode=0: Upload all files
mode=1: Upload all files that do not exist on the FTP server.
mode=2: Upload newer or non-existant files.
mode=3: Upload only newer files. If a file does not already exist on the FTP server, it is not uploaded.
mode=4: transfer missing files or files with size differences.
mode=5: same as mode 4, but also newer files.

Note: In v9.5.0.51 and higher, the list of uploaded files is available in the SyncedFiles property.

SyncRemoteTree2

# $localDirPath is a string
# $mode is an integer
# $bDescend is a boolean
# $bPreviewOnly is a boolean
$status = $ftp2->SyncRemoteTree2($localDirPath, $mode, $bDescend, $bPreviewOnly);

Same as SyncRemoteTree, except two extra arguments are added to allow for more flexibility. If bDescend is 0, then the directory tree is not descended and only the files in localDirPath are synchronized. If bPreviewOnly is 1 then no files are transferred and instead the files that would've been transferred (had bPreviewOnly been set to 0) are listed in the SyncPreview property.

Note: If bPreviewOnly is set to 1, the remote directories (if they do not exist) are created. It is only the files that are not uploaded.

Note: In v9.5.0.51 and higher, the list of uploaded files is available in the SyncedFiles property.