ftpUpload()

The function ftpUpload uploads a file to an FTP or FTPS server.

Synopsis

bool ftpUpload(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 that should be uploaded.
options

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

Return Value

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

Error

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

Description

The function ftpUpload uploads a local file to an FTP or FTPS server. 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 Upload

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

FTPS Upload 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 = ftpUpload("ftps://secureserver.com", "/uploads/daily.csv", "C:/data/daily.csv", opts);
  if (result)
    DebugN("Secure upload successful");
  else
    DebugN("Secure upload failed");
}

Assignment

FTP functions

Availability

UI, CTRL