Commercial File Transfer Protocol (FTP) C Library.
The proxy scheme used by your FTP proxy server. Valid values are 0 to 6. The default value is 0 which indicates that no proxy server is used. Supported proxy methods are as follows:
Note: The ProxyHostname is the hostname of the firewall, if the proxy is a firewall. Also, the ProxyUsername and ProxyPassword are the firewall username/password (if the proxy is a firewall).
ProxyMethod = 1 (SITE site)
USER ProxyUsername
PASS ProxyPassword
SITE Hostname
USER Username
PASS Password
ProxyMethod = 2 (USER user@site)
USER Username@Hostname:Port
PASS Password
ProxyMethod = 3 (USER with login)
USER ProxyUsername
PASS ProxyPassword
USER Username@Hostname:Port
PASS Password
ProxyMethod = 4 (USER/PASS/ACCT)
USER Username@Hostname:Port ProxyUsername
PASS Password
ACCT ProxyPassword
ProxyMethod = 5 (OPEN site)
USER ProxyUsername
PASS ProxyPassword
OPEN Hostname
USER Username
PASS Password
ProxyMethod = 6 (firewallId@site)
USER ProxyUsername@Hostname
USER Username
PASS Password
ProxyMethod = 7
USER ProxyUsername
USER ProxyPassword
SITE Hostname:Port
USER Username
PASS Password
ProxyMethod = 8
USER Username@ProxyUsername@Hostname
PASS Password@ProxyPassword
void CkFtp2_getProxyPassword(HCkFtp2 cHandle, HCkString retval);
void CkFtp2_putProxyPassword(HCkFtp2 cHandle, const char *newVal);
The password for authenticating with the FTP proxy server.
long CkFtp2_getProxyPort(HCkFtp2 cHandle);
void CkFtp2_putProxyPort(HCkFtp2 cHandle, long newVal);
If an FTP proxy server is used, this is the port number at which the proxy server is listening for connections.
void CkFtp2_getProxyUsername(HCkFtp2 cHandle, HCkString retval);
void CkFtp2_putProxyUsername(HCkFtp2 cHandle, const char *newVal);
The username for authenticating with the FTP proxy server.
long CkFtp2_getReadTimeout(HCkFtp2 cHandle);
void CkFtp2_putReadTimeout(HCkFtp2 cHandle, long newVal);
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.
The default value is 60.
BOOL CkFtp2_getRequireSslCertVerify(HCkFtp2 cHandle);
void CkFtp2_putRequireSslCertVerify(HCkFtp2 cHandle, BOOL newVal);
If true, then the FTP2 client will verify the server's SSL certificate. The certificate is expired, or if the cert's signature is invalid, the connection is not allowed. The default value of this property is false.
BOOL CkFtp2_getRestartNext(HCkFtp2 cHandle);
void CkFtp2_putRestartNext(HCkFtp2 cHandle, BOOL newVal);
Both uploads and downloads may be resumed by simply setting this property = true and re-calling the upload or download method.
int CkFtp2_getSendBufferSize(HCkFtp2 cHandle);
void CkFtp2_putSendBufferSize(HCkFtp2 cHandle, int newVal);
The buffer size to be used with the underlying TCP/IP socket for sending. The default value is 524288 (512K). Set it to a smaller value for more frequent percentage completion event callbacks. A larger SendBufferSize may improve performance, but at the expense not having as frequent progress monitoring callbacks (if used and if supported by your programming language).
void CkFtp2_getSessionLog(HCkFtp2 cHandle, HCkString retval);
Contains the session log if KeepSessionLog is turned on.
void CkFtp2_getSocksHostname(HCkFtp2 cHandle, HCkString retval);
void CkFtp2_putSocksHostname(HCkFtp2 cHandle, const char *newVal);
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
void CkFtp2_getSocksPassword(HCkFtp2 cHandle, HCkString retval);
void CkFtp2_putSocksPassword(HCkFtp2 cHandle, const char *newVal);
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
int CkFtp2_getSocksPort(HCkFtp2 cHandle);
void CkFtp2_putSocksPort(HCkFtp2 cHandle, int newVal);
The SOCKS4/SOCKS5 proxy port. The default value is 1080.
This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).
void CkFtp2_getSocksUsername(HCkFtp2 cHandle, HCkString retval);
void CkFtp2_putSocksUsername(HCkFtp2 cHandle, const char *newVal);
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
int CkFtp2_getSocksVersion(HCkFtp2 cHandle);
void CkFtp2_putSocksVersion(HCkFtp2 cHandle, int newVal);
SocksVersion
May be set to one of the following integer values:
0 - No SOCKS proxy is used. This is the default.
4 - Connect via a SOCKS4 proxy.
5 - Connect via a SOCKS5 proxy.
BOOL CkFtp2_getSsl(HCkFtp2 cHandle);
void CkFtp2_putSsl(HCkFtp2 cHandle, BOOL newVal);
Use SSL for FTP connections. You would typically set Ssl = true when connecting to port 990 on FTP servers that support SSL mode. Note: It is more common to use AuthTls.
void CkFtp2_getSslProtocol(HCkFtp2 cHandle, HCkString retval);
void CkFtp2_putSslProtocol(HCkFtp2 cHandle, const char *newVal);
Selects the secure protocol to be used for secure (SSL/TLS) implicit and explicit (AUTH TLS / AUTH SSL) connections . Possible values are:
default
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "default", which means the client/server negotiate the protocol.
BOOL CkFtp2_getSslServerCertVerified(HCkFtp2 cHandle);
Read-only property that returns true if the FTP server's digital certificate was verified when connecting via SSL / TLS.
void CkFtp2_getSyncPreview(HCkFtp2 cHandle, HCkString retval);
Contains the list of files that would be transferred in a call to SyncRemoteTree2 when the previewOnly argument is set to true. 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.
long CkFtp2_getUploadRate(HCkFtp2 cHandle);
The average upload rate in bytes/second. This property is updated in real-time during any FTP upload (asynchronous or synchronous).
BOOL CkFtp2_getUseEpsv(HCkFtp2 cHandle);
void CkFtp2_putUseEpsv(HCkFtp2 cHandle, BOOL newVal);
If true, the FTP2 component will use the EPSV command instead of PASV for passive mode data transfers. The default value of this property is false. (It is somewhat uncommon for FTP servers to support EPSV.)
void CkFtp2_getUsername(HCkFtp2 cHandle, HCkString retval);
void CkFtp2_putUsername(HCkFtp2 cHandle, const char *newVal);
Username for logging into the FTP server. Defaults to "anonymous".
BOOL CkFtp2_getUtf8(HCkFtp2 cHandle);
void CkFtp2_putUtf8(HCkFtp2 cHandle, BOOL newVal);
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
BOOL CkFtp2_getVerboseLogging(HCkFtp2 cHandle);
void CkFtp2_putVerboseLogging(HCkFtp2 cHandle, BOOL newVal);
If set to true, then the LastErrorText may contain more verbose logging.
void CkFtp2_getVersion(HCkFtp2 cHandle, HCkString retval);
Version of the component, such as "1.0.0"
C "Methods"
BOOL CkFtp2_AppendFile(HCkFtp2 cHandle, const char *localFilename, const char *remoteFilename);
Same as PutFile but the file on the FTP server is appended.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_AppendFileFromBinaryData(HCkFtp2 cHandle, const char *remoteFilename, HCkByteData binaryData);
Same as PutFileFromBinaryData, except the file on the FTP server is appended.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_AppendFileFromTextData(HCkFtp2 cHandle, const char *remoteFilename, const char *textData);
Same as PutFileFromTextData, except the file on the FTP server is appended.
Returns TRUE for success, FALSE for failure.
void CkFtp2_AsyncAbort(HCkFtp2 cHandle);
Causes an asynchronous Get or Put to abort.
BOOL CkFtp2_AsyncAppendFileStart(HCkFtp2 cHandle, const char *localFilename, const char *remoteFilename);
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.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_AsyncGetFileStart(HCkFtp2 cHandle, const char *remoteFilename, const char *localFilename);
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.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_AsyncPutFileStart(HCkFtp2 cHandle, const char *localFilename, const char *remoteFilename);
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.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_ChangeRemoteDir(HCkFtp2 cHandle, const char *relativeDirPath);
Changes the current remote directory. The relativeDirPath should be relative to the current remote directory, which is initially the HOME directory of the FTP user account.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_ClearControlChannel(HCkFtp2 cHandle);
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.
Returns TRUE for success, FALSE for failure.
void CkFtp2_ClearDirCache(HCkFtp2 cHandle);
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.
void CkFtp2_ClearSessionLog(HCkFtp2 cHandle);
Clears the in-memory session log.
BOOL CkFtp2_Connect(HCkFtp2 cHandle);
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 false (indicating failure).
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_ConvertToTls(HCkFtp2 cHandle);
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 true, then DO NOT call ConvertToTls. The control channel is automatically converted to SSL/TLS from within the Connect method when these properties are set.
Note: It is very uncommon for this method to be needed.
BOOL CkFtp2_CreatePlan(HCkFtp2 cHandle, const char *localDir, HCkString str);
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.
BOOL CkFtp2_CreateRemoteDir(HCkFtp2 cHandle, const char *dir);
Creates a directory on the FTP server. If the directory already exists, a new one is not created and false is returned.
Returns TRUE for success, FALSE for failure.
long CkFtp2_DeleteMatching(HCkFtp2 cHandle, const char *remotePattern);
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.
BOOL CkFtp2_DeleteRemoteFile(HCkFtp2 cHandle, const char *filename);
Deletes a file on the FTP server.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_DeleteTree(HCkFtp2 cHandle);
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/
Returns TRUE for success, FALSE for failure.
int CkFtp2_DetermineProxyMethod(HCkFtp2 cHandle);
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.)
BOOL CkFtp2_DetermineSettings(HCkFtp2 cHandle, HCkString xmlReport);
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.
BOOL CkFtp2_DirTreeXml(HCkFtp2 cHandle, HCkString strXml);
Recursively downloads the structure of a complete remote directory tree. Returns an XML document with the directory structure. A zero-length string is returned to indicate failure.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_Disconnect(HCkFtp2 cHandle);
Disconnects from the FTP server, ending the current session.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_DownloadTree(HCkFtp2 cHandle, const char *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.
There are three event callbacks (for programming languages supporting events): BeginDownloadFile, EndDownloadFile, and VerifyDownloadDir. The 1st argument to each callback is the fully qualified pathname of the file or directory. The BeginDownloadFile event callbacks has a "skip" argument, which is output-only. The application can set it to true to prevent the file from being downloaded. The VerifyDownloadDir also has a "skip" argument where the application can cause an entire sub-tree to be skipped. The EndDownloadFile event includes a "numBytes" argument containing the size of the file in bytes.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_Feat(HCkFtp2 cHandle, HCkString sOut);
Sends a FEAT command to the FTP server and returns the response. Returns a zero-length string to indicate failure. Here is a typical response:
211-Features:
MDTM
REST STREAM
SIZE
MLST type*;size*;modify*;
MLSD
AUTH SSL
AUTH TLS
UTF8
CLNT
MFMT
211 End
BOOL CkFtp2_GetCreateTime(HCkFtp2 cHandle, long index, SYSTEMTIME *sysTime);
Returns the create time 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)
BOOL CkFtp2_GetCreateTimeByName(HCkFtp2 cHandle, const char *filename, SYSTEMTIME *sysTime);
Returns the file-creation time for a remote file by filename.
BOOL CkFtp2_GetCurrentRemoteDir(HCkFtp2 cHandle, HCkString str);
Returns the current remote directory.
BOOL CkFtp2_GetFile(HCkFtp2 cHandle, const char *remoteFilename, const char *localFilename);
Downloads a file from the FTP server to the local filesystem.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_GetFilename(HCkFtp2 cHandle, long index, HCkString str);
Returns the filename 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)
BOOL CkFtp2_GetIsDirectory(HCkFtp2 cHandle, long index);
Returns true for a sub-directory and false for a file, for the Nth entry in the current remote directory. The first file/dir is at index 0, and the last one is at index (NumFilesAndDirs-1)
BOOL CkFtp2_GetIsSymbolicLink(HCkFtp2 cHandle, long index);
Returns true if the remote file is a symbolic link. (Symbolic links only exist on Unix/Linux systems, not on Windows filesystems.)
BOOL CkFtp2_GetLastAccessTime(HCkFtp2 cHandle, long index, SYSTEMTIME *sysTime);
Returns the last access time 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)
BOOL CkFtp2_GetLastAccessTimeByName(HCkFtp2 cHandle, const char *filename, SYSTEMTIME *sysTime);
Returns a remote file's last-access time.
BOOL CkFtp2_GetLastModifiedTime(HCkFtp2 cHandle, long index, SYSTEMTIME *sysTime);
Returns the last modified time 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)
BOOL CkFtp2_GetLastModifiedTimeByName(HCkFtp2 cHandle, const char *filename, SYSTEMTIME *sysTime);
Returns the last-modified date/time for a remote file.
BOOL CkFtp2_GetRemoteFileBinaryData(HCkFtp2 cHandle, const char *remoteFilename, HCkByteData data);
Downloads the contents of a remote file into a byte array.
BOOL CkFtp2_GetRemoteFileTextC(HCkFtp2 cHandle, const char *remoteFilename, const char *charset, HCkString str);
Downloads a text file directly into a string variable. The character encoding of the text file is specified by the charset argument, which is a value such as utf-8, iso-8859-1, Shift_JIS, etc.
BOOL CkFtp2_GetRemoteFileTextData(HCkFtp2 cHandle, const char *remoteFilename, HCkString str);
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.
long CkFtp2_GetSize(HCkFtp2 cHandle, long index);
Returns the size of the Nth remote file in the current directory.
long CkFtp2_GetSizeByName(HCkFtp2 cHandle, const char *filname);
Returns a remote file's size in bytes.
BOOL CkFtp2_GetSizeStr(HCkFtp2 cHandle, long index, HCkString str);
Returns the size of a remote filename as a string. This is helpful for file sizes that are greater then 2GB.
BOOL CkFtp2_GetSizeStrByName(HCkFtp2 cHandle, const char *filename, HCkString outStr);
To be documented soon...
HCkCert CkFtp2_GetSslServerCert(HCkFtp2 cHandle);
Returns the FTP server's digital certificate (for SSL / TLS connections).
HCkCert CkFtp2_GetSslServerCert(HCkFtp2 cHandle);
Returns the FTP server's digital certificate (for SSL / TLS connections).
BOOL CkFtp2_GetTextDirListing(HCkFtp2 cHandle, const char *pattern, HCkString strRawListing);
Returns a listing of the files and directories in the current directory matching the pattern. Passing "*.*" will return all the files and directories.
BOOL CkFtp2_GetXmlDirListing(HCkFtp2 cHandle, const char *pattern, HCkString strXmlListing);
Returns (in XML format) the files and directories in the current directory matching the pattern. Passing "*.*" will return all the files and directories.
BOOL CkFtp2_IsUnlocked(HCkFtp2 cHandle);
Return true if the component is already unlocked.
long CkFtp2_MGetFiles(HCkFtp2 cHandle, const char *remotePattern, const char *localDir);
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).
long CkFtp2_MPutFiles(HCkFtp2 cHandle, const char *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.[
BOOL CkFtp2_NlstXml(HCkFtp2 cHandle, const char *pattern, HCkString outStr);
To be documented soon...
BOOL CkFtp2_Noop(HCkFtp2 cHandle);
Issues a no-op command to the FTP server.
BOOL CkFtp2_PutFile(HCkFtp2 cHandle, const char *localFilename, const char *remoteFilename);
Uploads a local file to the current directory on the FTP server.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_PutFileFromBinaryData(HCkFtp2 cHandle, const char *remoteFilename, HCkByteData binaryData);
Creates a file on the remote server containing the data passed in a byte array.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_PutFileFromTextData(HCkFtp2 cHandle, const char *remoteFilename, const char *textData);
Creates a file on the remote server containing the data passed in a string.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_PutPlan(HCkFtp2 cHandle, const char *planUtf8, const char *planLogFilename);
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.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_PutTree(HCkFtp2 cHandle, const char *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.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_Quote(HCkFtp2 cHandle, const char *cmd);
Sends an arbitrary (raw) command to the FTP server.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_RemoveRemoteDir(HCkFtp2 cHandle, const char *dir);
Removes a directory from the FTP server.
BOOL CkFtp2_RenameRemoteFile(HCkFtp2 cHandle, const char *existingFilename, const char *newFilename);
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.
BOOL CkFtp2_SaveLastError(HCkFtp2 cHandle, const char *filename);
Saves the last error information to an XML formatted file.
BOOL CkFtp2_SendCommand(HCkFtp2 cHandle, const char *cmd, HCkString reply);
Sends an raw command to the FTP server and returns the raw response.
BOOL CkFtp2_SetModeZ(HCkFtp2 cHandle);
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).
Call this method after connecting to enable Mode Z. Once enabled, all transfers (uploads, downloads, and directory listings) are compressed.
Returns TRUE for success, FALSE for failure.
void CkFtp2_SetOldestDate(HCkFtp2 cHandle, SYSTEMTIME *oldestDateTime);
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.
BOOL CkFtp2_SetRemoteFileDateTime(HCkFtp2 cHandle, SYSTEMTIME *dt, const char *remoteFilename);
Sets the last-modified date/time of a file on the FTP server. Important: Not all FTP servers support this functionality. Please see the information at the Chilkat blog below:
Setting FTP date/time not supported by all FTP servers.
void CkFtp2_SetSslCertRequirement(HCkFtp2 cHandle, const char *name, const char *value);
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.
void CkFtp2_SetSslClientCert(HCkFtp2 cHandle, HCkCert cert);
Allows for a client-side certificate to be used for the SSL / TLS connection.
void CkFtp2_SetSslClientCert(HCkFtp2 cHandle, HCkCert cert);
Allows for a client-side certificate to be used for the SSL / TLS connection.
BOOL CkFtp2_SetSslClientCertPfx(HCkFtp2 cHandle, const char *pfxFilename, const char *pfxPassword, const char *certSubjectCN);
To be documented soon...
BOOL CkFtp2_SetSslClientCertPfx(HCkFtp2 cHandle, const char *pfxFilename, const char *pfxPassword, const char *certSubjectCN);
To be documented soon...
BOOL CkFtp2_SetTypeAscii(HCkFtp2 cHandle);
Set the FTP transfer mode to us-ascii.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_SetTypeBinary(HCkFtp2 cHandle);
Set the FTP transfer mode to binary.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_Site(HCkFtp2 cHandle, const char *params);
Sends an arbitrary "site" command to the FTP server. The params argument should contain the parameters to the site command as they would appear on a command line. For example: "recfm=fb lrecl=600".
Returns TRUE for success, FALSE for failure.
void CkFtp2_SleepMs(HCkFtp2 cHandle, int millisec);
Causes the calling process to sleep for a number of milliseconds.
BOOL CkFtp2_Stat(HCkFtp2 cHandle, HCkString sOut);
Sends a STAT command to the FTP server and returns the server's reply.
BOOL CkFtp2_SyncLocalTree(HCkFtp2 cHandle, const char *localRoot, int mode);
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.
* There is no mode #4. It is a mode used internally by the DirTreeXml method.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_SyncRemoteTree(HCkFtp2 cHandle, const char *localRoot, int mode);
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.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_SyncRemoteTree2(HCkFtp2 cHandle, const char *localRoot, int mode, BOOL bDescend, BOOL bPreviewOnly);
Same as SyncRemoteTree, except two extra arguments are added to allow for more flexibility. If bDescend is false, then the directory tree is not descended and only the files in localDirPath are synchronized. If bPreviewOnly is true then no files are transferred and instead the files that would've been transferred (had bPreviewOnly been set to false) are listed in the SyncPreview property.
Returns TRUE for success, FALSE for failure.
BOOL CkFtp2_Syst(HCkFtp2 cHandle, HCkString sOut);
Sends a SYST command to the FTP server to find out the type of operating
system at the server. The method returns the FTP server's response string. Refer to RFC 959 for details.
BOOL CkFtp2_UnlockComponent(HCkFtp2 cHandle, const char *code);
Unlocks the component. This must be called once prior to calling any other method.
const char *CkFtp2_account(HCkFtp2 cHandle);
Some FTP servers require an Account name in addition to login/password. This property can be set for those servers with this requirement.
const char *CkFtp2_asyncLog(HCkFtp2 cHandle);
The last-error information for an asynchronous (background) file transfer.
const char *CkFtp2_ck_stat(HCkFtp2 cHandle);
To be documented soon...
const char *CkFtp2_createPlan(HCkFtp2 cHandle, const char *localDir);
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.
const char *CkFtp2_determineSettings(HCkFtp2 cHandle);
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.
const char *CkFtp2_dirListingCharset(HCkFtp2 cHandle);
Set to "ansi" by default. If the FTP server sends directory listings with non-English filenames, this property can be set to the appropriate value if necessary.
const char *CkFtp2_dirTreeXml(HCkFtp2 cHandle);
Recursively downloads the structure of a complete remote directory tree. Returns an XML document with the directory structure. A zero-length string is returned to indicate failure.
Returns TRUE for success, FALSE for failure.
const char *CkFtp2_feat(HCkFtp2 cHandle);
Sends a FEAT command to the FTP server and returns the response. Returns a zero-length string to indicate failure. Here is a typical response:
211-Features:
MDTM
REST STREAM
SIZE
MLST type*;size*;modify*;
MLSD
AUTH SSL
AUTH TLS
UTF8
CLNT
MFMT
211 End
const char *CkFtp2_forcePortIpAddress(HCkFtp2 cHandle);
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".
const char *CkFtp2_getCurrentRemoteDir(HCkFtp2 cHandle);
Returns the current remote directory.
const char *CkFtp2_getFilename(HCkFtp2 cHandle, long index);
Returns the filename 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)
const char *CkFtp2_getRemoteFileTextC(HCkFtp2 cHandle, const char *remoteFilename, const char *charset);
Downloads a text file directly into a string variable. The character encoding of the text file is specified by the charset argument, which is a value such as utf-8, iso-8859-1, Shift_JIS, etc.
const char *CkFtp2_getRemoteFileTextData(HCkFtp2 cHandle, const char *remoteFilename);
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.
const char *CkFtp2_getSizeStr(HCkFtp2 cHandle, long index);
Returns the size of a remote filename as a string. This is helpful for file sizes that are greater then 2GB.
const char *CkFtp2_getSizeStrByName(HCkFtp2 cHandle, const char *filename);
To be documented soon...
const char *CkFtp2_getTextDirListing(HCkFtp2 cHandle, const char *pattern);
Returns a listing of the files and directories in the current directory matching the pattern. Passing "*.*" will return all the files and directories.
const char *CkFtp2_getXmlDirListing(HCkFtp2 cHandle, const char *pattern);
Returns (in XML format) the files and directories in the current directory matching the pattern. Passing "*.*" will return all the files and directories.
const char *CkFtp2_greeting(HCkFtp2 cHandle);
The initial greeting received from the FTP server after connecting.
const char *CkFtp2_hostname(HCkFtp2 cHandle);
The FTP server hostname.
const char *CkFtp2_lastErrorHtml(HCkFtp2 cHandle);
Error information in HTML format for the last method called.
const char *CkFtp2_lastErrorText(HCkFtp2 cHandle);
Error information in plain-text format for the last method called.
const char *CkFtp2_lastErrorXml(HCkFtp2 cHandle);
Error information in XML format for the last method called.
const char *CkFtp2_listPattern(HCkFtp2 cHandle);
A wildcard pattern, defaulting to "*" that determines the files and directories included in the following properties and methods: 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".
const char *CkFtp2_nlstXml(HCkFtp2 cHandle, const char *pattern);
To be documented soon...
const char *CkFtp2_password(HCkFtp2 cHandle);
Password for logging into the FTP server.
const char *CkFtp2_proxyHostname(HCkFtp2 cHandle);
The hostname of your FTP proxy, if a proxy server is used.
const char *CkFtp2_proxyPassword(HCkFtp2 cHandle);
The password for authenticating with the FTP proxy server.
const char *CkFtp2_proxyUsername(HCkFtp2 cHandle);
The username for authenticating with the FTP proxy server.
const char *CkFtp2_sendCommand(HCkFtp2 cHandle, const char *cmd);
Sends an raw command to the FTP server and returns the raw response.
const char *CkFtp2_sessionLog(HCkFtp2 cHandle);
Contains the session log if KeepSessionLog is turned on.
const char *CkFtp2_socksHostname(HCkFtp2 cHandle);
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
const char *CkFtp2_socksPassword(HCkFtp2 cHandle);
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
const char *CkFtp2_socksUsername(HCkFtp2 cHandle);
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
const char *CkFtp2_sslProtocol(HCkFtp2 cHandle);
Selects the secure protocol to be used for secure (SSL/TLS) implicit and explicit (AUTH TLS / AUTH SSL) connections . Possible values are:
default
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "default", which means the client/server negotiate the protocol.
const char *CkFtp2_syncPreview(HCkFtp2 cHandle);
Contains the list of files that would be transferred in a call to SyncRemoteTree2 when the previewOnly argument is set to true. 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.
const char *CkFtp2_syst(HCkFtp2 cHandle);
Sends a SYST command to the FTP server to find out the type of operating
system at the server. The method returns the FTP server's response string. Refer to RFC 959 for details.
const char *CkFtp2_username(HCkFtp2 cHandle);
Username for logging into the FTP server. Defaults to "anonymous".
const char *CkFtp2_version(HCkFtp2 cHandle);
Version of the component, such as "1.0.0"