ftpDownload()

The function ftpDownload downloads a file from an FTP or FTPS server.

Synopsis

bool ftpDownload(string url, string remotePath, string localPath [, mapping options]);

Parameters

Parameter Description
url

The FTP or FTPS URL of the server (e.g. ftp://myserver.com or ftps://myserver.com).
remotePath

Path to the file on the FTP server. The folder(s) must exist on the server.
localPath

Path to the local file. The file will be overwritten if it already exists or created if it does not exist yet.
options

Optional. A mapping with additional options for the FTP transfer. See Options Mapping below.

Return Value

The function returns TRUE if the download was successful, FALSE in case of an error.

Error

An error is given in case of missing or invalid arguments, failed connection to the FTP server or when the remote file does not exist.

Description

The function ftpDownload downloads a file from an FTP or FTPS server to a local path. The function supports plain FTP as well as FTP over TLS (FTPS) with various SSL/TLS configuration options.

Credentials can either be specified as part of the URL (e.g. ftp://user:password@myserver.com) or via the username and password keys in the options mapping. If both are provided, the options mapping values take precedence.

Options Mapping

The optional options parameter is a mapping that can contain the following keys:

Key Type Default Description
useEpsv bool true

Use Extended Passive Mode (EPSV) instead of regular PASV.
timeout int 0

Total operation timeout in seconds. A value of 0 means unlimited.
username string -

FTP username. Overrides URL credentials if provided.
password string -

FTP password. Overrides URL credentials if provided.
sslOptions mapping -

SSL/TLS configuration mapping. See SSL Options below.

SSL Options

The sslOptions key within the options mapping accepts a mapping with the following keys:

Key Type Default Description
sslMode int 4 (Auto)

SSL/TLS encryption mode. See SSL Modes below.
verifyCertificate bool true

Verify the server certificate against the CA. Set to false to accept self-signed certificates.
verifyHost bool true

Verify that the hostname matches the certificate. Set to false to disable hostname verification.
caCertificatePath string -

Path to the CA certificate file in PEM format. This is required if verifyCertificate is set to true.
localCertificatePath string -

Path to the client certificate file in PEM format. Only required for mutual TLS authentication.
privateKeyPath string -

Path to the client private key file in PEM format. Only required for mutual TLS authentication.

SSL Modes

The following values are available for the sslMode key:

Value Name Description
0 None

No SSL/TLS encryption.
1 Try

Try SSL/TLS, fall back to plain FTP if it fails.
2 Control

SSL/TLS only for the control connection.
3 All

SSL/TLS for both control and data connections.
4 Auto

Default. Uses All for ftps:// URLs and None for ftp:// URLs.

Simple FTP Download

main()
{
  bool result = ftpDownload("ftp://myserver.com", "/data/report.csv", "C:/temp/report.csv");
  if (result)
    DebugN("Download successful");
  else
    DebugN("Download failed");
}

FTPS Download with Options

main()
{
  mapping sslOpts;
  sslOpts["sslMode"] = 3;
  sslOpts["verifyCertificate"] = true;
  sslOpts["caCertificatePath"] = "C:/certs/ca.pem";

  mapping opts;
  opts["username"] = "ftpuser";
  opts["password"] = "secret";
  opts["timeout"] = 30;
  opts["sslOptions"] = sslOpts;

  bool result = ftpDownload("ftps://secureserver.com", "/reports/daily.csv", "C:/temp/daily.csv", opts);
  if (result)
    DebugN("Secure download successful");
  else
    DebugN("Secure download failed");
}

Assignment

FTP functions

Availability

UI, CTRL