# FTP Actions Plugin

Online Help

## Description

The FTP actions plugin allows you to connect to and navigate an ftp server within your application, either behind the scenes, or with user input.

Whether creating your own FTP client, or simply offering the option of downloading from a pre-specified FTP server, this plugin is an excellent addition to your toolbox. Shipping with actions to connect, navigate, upload and download, this is a full-function plugin. As well, the FTP plugin supports resumed downloads.

Both 32-bit and 64-bit versions of the FTP action plugin are available in supported products. Action names and categories are identical, however when adding them to projects the 32-bit plugin is named "FTP" while the 64-bit version is named "FTP (64-bit)." Choose the appropriate version of the plugin based on whether the runtime using the plugin is a 32-bit or 64-bit executable.

## Actions

FTP.CdUp
FTP.ChangeDir
FTP.ClearLog
FTP.Command
FTP.Connect
FTP.Delete
FTP.Disconnect
FTP.Download
FTP.GetConnectTimeout
FTP.GetControlPort
FTP.GetCurrentDir
FTP.GetDataPort
FTP.GetFileInfo
FTP.GetHelp
FTP.GetLastResponse
FTP.GetLog
FTP.GetPassiveMode
FTP.GetTransferType
FTP.IsConnected
FTP.IsValidHostname
FTP.List
FTP.ListFiles
FTP.ListFolders
FTP.MakeDir
FTP.NoOp
FTP.RemoveDir
FTP.Rename
FTP.Resume
FTP.SetCommandCallback
FTP.SetConnectTimeout
FTP.SetControlPort
FTP.SetDataPort
FTP.SetPassiveMode
FTP.SetResponseCallback
FTP.SetTransferType
FTP.Upload

### FTP.CdUp ();

#### Description:

Moves up one directory level on the FTP server.

#### Returns:

Nothing.

#### Example:

    -- navigate to /web/images
    FTP.ChangeDir("/web/images");

    -- move "up" from /web/images to /web
    FTP.CdUp();

### FTP.ChangeDir (string Path);

#### Description:

Changes the current directory on the FTP server.

#### Path:

(string) The path to the directory on the FTP server that you want to navigate to.

#### Returns:

Nothing.

#### Example:

    -- navigate to /web/misc
    FTP.ChangeDir("/web/misc");

    -- navigate to /web/misc/files
    FTP.ChangeDir("files");

### FTP.ClearLog ();

#### Description:

Clears (empties) the command/response log. Use this to "reset" the log of commands sent to the FTP server and the response messages received from it.

Note: The command/response log is for information only. Clearing the log has no effect on the FTP server.

#### Returns:

Nothing.

#### Example:

    -- reset the log
    FTP.ClearLog();

### FTP.Command (string Command);

#### Description:

Performs a custom FTP command on the FTP server.

#### Command:

(string) Any valid FTP command or any server-specific command.

#### Returns:

Nothing.

#### Example:

    -- set access permissions for foo.txt
    -- so the owner can read+write, but everyone else can only read
    -- note: this is a server-specific command, it may not work on all servers
    FTP.Command("SITE CHMOD 644 foo.txt");

### FTP.Connect (string Hostname, string Username = "anonymous", string Password = "anonymous@anonymous.com", string Account = "", boolean HidePassword = true);

#### Description:

Connects to an FTP server.

#### Hostname:

(string) The hostname or IP address of the FTP site you want to connect to.

#### Username:

(string) The username you want to login as, or "anonymous" to initiate an anonymous login.

#### Password:

(string) The password for the given username.

#### Account:

(string) An additional "account" name for systems which require it (usually used for access control).

#### HidePassword:

(boolean) Whether to include the password in the FTP log as plain text or replace it with "****".

true - Replace the password with **** in the command/response log.
false - Don't hide the password in the command/response log.

#### Returns:

Nothing.

#### Example 1:

    -- make an anonymous connection to ftp.cdrom.com
    FTP.Connect("ftp.cdrom.com");

    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

#### Example 2:

    -- connect to NASA's space image server
    -- note: the username and password won't work, this is just an example :)
    FTP.Connect("explorer.arc.nasa.gov", "neil_armstrong", "EagleHasLanded");

    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

### FTP.Delete (string Filename);

#### Description:

Deletes a file in the current directory on the FTP server.

#### Filename:

(string) The name of the file that you want to delete.

#### Returns:

Nothing.

#### Example:

    -- connect to myftp.com and delete foo.txt from the /pub/uploads folder

    -- step 1: connect to the site
    FTP.Connect("ftp.myftp.com", "myusername", "mypassword");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 2: navigate to the desired directory
    FTP.ChangeDir("/pub/uploads");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 3: delete the file
    FTP.Delete("foo.txt");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

### FTP.Disconnect ();

#### Description:

Disconnects from the FTP server.

#### Returns:

Nothing.

#### Example:

    -- log off
    FTP.Disconnect();

### FTP.Download (string Source, string Destination, function CallbackFunction);

#### Description:

Downloads a file from the current directory on the FTP server.

#### Source:

(string) The name of the file that you want to download.

#### Destination:

(string) The full path and filename of the destination file that you want to download to.

#### CallbackFunction:

(string) The name of a function that will be called whenever progress is made in the download operation. (You can use this callback function to display the progress of the download operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

##### Bytes:

(number) The number of bytes that have been transferred so far.

##### TotalBytes:

(number) The total number of bytes to transfer, or 0 if the total number of bytes is not known.

The callback function should return a boolean value (true or false) indicating whether the download should continue:

true - Continue downloading the file.
false - Abort the download.

#### Returns:

Nothing.

#### Example 1:

    -- download the Project Gutenberg edition of Hamlet

    -- step 1: connect anonymously to cdrom.com
    FTP.Connect("ftp.cdrom.com");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 2: change to the directory where the text file is located
    FTP.ChangeDir("/.1/gutenberg/etext97");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 3a: enable the status dialog's cancel button
    StatusDlg.ShowCancelButton();

    -- step 3b: show the status dialog
    StatusDlg.Show();

    -- step 3c: download the file as <temp>\Hamlet.txt
    FTP.Download("1ws2610.txt", _TempFolder .. "\\Hamlet.txt");
    err = Application.GetLastError();

    -- step 3d: hide the status dialog
    StatusDlg.Hide();

    -- step 4: log off
    FTP.Disconnect();

    -- ...now check whether FTP.Download generated an error
    if err == FTP.OK then
        Dialog.Message("Success!", _TempFolder.."\\Hamlet.txt was downloaded successfully!");
    else
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

#### Example 2:

    -- download the Project Gutenberg edition of Hamlet
    -- using a custom progress display

    -- display the progress in an AutoPlay Media Studio paragraph object named "Progress"
    -- (note: the paragraph object must already exist on the page)
    function cbDownload(nBytes, nTotal)
        if nTotal == 0 then
            Paragraph.SetText("Progress", nBytes .. " bytes downloaded!")
        else
            Paragraph.SetText("Progress", nBytes / nTotal * 100 .. "% downloaded!")
        end
    end

    -- step 1: connect anonymously to cdrom.com
    FTP.Connect("ftp.cdrom.com");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 2: change to the directory where the text file is located
    FTP.ChangeDir("/.1/gutenberg/etext97");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 3: download the file as <temp>\Hamlet.txt
    FTP.Download("1ws2610.txt", _TempFolder .. "\\Hamlet.txt", cbDownload);
    err = Application.GetLastError();

    -- step 4: log off
    FTP.Disconnect();

    -- ...now check whether FTP.Download generated an error
    if err == FTP.OK then
        Dialog.Message("Success!", _TempFolder.."\\Hamlet.txt was downloaded successfully!");
    else
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

### number FTP.GetConnectTimeout ();

#### Description:

Returns the number of seconds that the application will wait while attempting to establish a connection with the FTP server.

#### Returns:

(number) The current connection timeout, in seconds.

#### Example:

    -- get the current timeout value
    nConnectTimeout = FTP.GetConnectTimeout();

### number FTP.GetControlPort ();

#### Description:

Returns the control port being used for communication with the FTP server.

#### Returns:

(number) The current control port.

#### Example:

    -- get the current control port
    nControlPort = FTP.GetControlPort();

### string FTP.GetCurrentDir ();

#### Description:

Returns the path to the current directory on the FTP server.

#### Returns:

(string) The path to the current directory on the FTP server.

#### Example:

    -- get the current directory
    strDir = FTP.GetCurrentDir();

### number FTP.GetDataPort ();

#### Description:

Returns the data port being used for communication with the FTP server.

#### Returns:

(number) The current data port.

#### Example:

    -- get the current data port
    nDataPort = FTP.GetDataPort();

### table FTP.GetFileInfo (string Filename);

#### Description:

Returns a table containing information about a specific file in the current directory on the FTP server.

#### Filename:

(string) The name of a file in the current directory on the FTP server.

#### Returns:

(table) A table containing information about the file. If an error occurs (for example, if the file doesn't exist), this action returns nil.

If successful, the following information will be stored in the table:

Name:
(string) The name of the file.

Size:
(number) The size of the file, in bytes.

Year:
(number) The year from the file's creation date, e.g. 2003.

Month:
(number) The month from the file's creation date, e.g. 12.

Day:
(number) The day from the file's creation date, e.g. 25.

Hour:
(number) The hour from the file's creation date, e.g. 16.

Minute:
(number) The minute from the file's creation date, e.g. 57.

Date:
(string) The file's creation date in "<weekday>, <month> <day>, <year>" format, e.g. Thursday, Dec 25, 2003.

DateISO:
(string) The file's creation date in ISO format, e.g. 2003-12-25T16:57:00.

#### Example:

    -- get the size and creation date of the Project Gutenberg version of Hamlet

    -- step 1: connect anonymously to cdrom.com
    FTP.Connect("ftp.cdrom.com");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 2: change to the directory where the text file is located
    FTP.ChangeDir("/.1/gutenberg/etext97");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- step 3: get the size of the Hamlet text file
    tbInfo = FTP.GetFileInfo("1ws2610.txt");
    if tbInfo then
        nHamletFileSize = tbInfo.Size;
        strHamletFileDate = tbInfo.Date;
        Dialog.Message("File Information:", "Size: " .. nHamletFileSize .. " bytes\r\nDate: "..strHamletFileDate);
    end

    -- step 4: log off
    FTP.Disconnect();

### string FTP.GetHelp ();

#### Description:

Returns the help text for a command from the FTP server.

#### Command:

(string) The command whose help text you want to retrieve. (On some servers you can use "" to get a list of all commands.)

#### Returns:

(string) The help text (i.e. syntax) returned by the server for that command.

#### Example:

    -- get the syntax of the MODE command
    strHelp = FTP.GetHelp("MODE");

### string FTP.GetLastResponse ();

#### Description:

Returns the text received from the FTP server as a result of the most recent FTP action.

Note: Some FTP actions don't generate any response from the server. In such cases, GetLastResponse() will return an empty string ("").

#### Returns:

(string) The FTP server's response to the last FTP action that was performed.

#### Example:

    -- connect anonymously to the NASA image server
    FTP.Connect("explorer.arc.nasa.gov");

    -- get the server's responses to the commands sent by the FTP.Connect action
    strResponse = FTP.GetLastResponse();

    -- display the response in an AutoPlay Media Studio paragraph object named "Response"
    -- (note: the paragraph object must already exist on the page)
    Paragraph.SetText("Response", strResponse);

### string FTP.GetLog ();

#### Description:

Returns a log of the interaction with the FTP server, including commands sent to the server and responses received from it.

Note: The log will contain every FTP command and reponse since your application started, or the last time the FTP.ClearLog action was used.

#### Returns:

(string) The current contents of the command/response log.

#### Example:

    -- this function checks the last error code and
    -- displays the appropriate error message if an error occurred
    local function check_error()
        err = Application.GetLastError();
        if err ~= FTP.OK then
            Dialog.Message("Error", _tblErrorMessages[err]);
        end

        -- returns true if OK, false if error
        return (err == FTP.OK);
    end

    -- empty the log
    FTP.ClearLog();

    -- connect anonymously to the NASA image server
    FTP.Connect("explorer.arc.nasa.gov");
    if check_error() then
        -- connected okay

        -- navigate to the /pub/SPACE directory
        FTP.ChangeDir("/pub/SPACE");
        if check_error() then
            -- made it to /pub/SPACE

            -- get a list of the files and folders here
            tbContents = FTP.List();

            -- log off
            FTP.Disconnect();
        end
    end

    -- display a log of all the commands and responses that just transpired
    -- in an AutoPlay Media Studio paragraph object named "Log"
    -- (note: the paragraph object must already exist on the page)
    Paragraph.SetText("Log", FTP.GetLog() );

### boolean FTP.GetPassiveMode ();

#### Description:

Returns true if the FTP actions will communicate with the server in passive mode (where control and data connections are both originated by the client).

#### Returns:

(boolean) Whether the FTP actions will use passive mode:

true - Passive (firewall-friendly) mode enabled.
false - Normal FTP communication will be used.

#### Example:

    -- display a message if passive mode is enabled
    if FTP.GetPassiveMode() then
        Dialog.Message("Status", "Passive Mode Enabled");
    end

### number FTP.GetTransferType ();

#### Description:

Returns the transfer type (FTP.ASCII or FTP.BINARY) being used for data transfer and storage.

#### Returns:

(number) The transfer type:

0: (FTP.ASCII) - ASCII (type A) transfer type.
1: (FTP.BINARY) - Binary (type I) transfer type.

#### Example:

    -- display the current transfer type
    if FTP.GetTransferType() == FTP.ASCII then
        Dialog.Message("Current Transfer Type", "ASCII");
    else
        Dialog.Message("Current Transfer Type", "Binary");
    end

### boolean FTP.IsConnected ();

#### Description:

Returns true if there is currently a connection with an FTP server.

#### Returns:

(boolean) Whether there is an FTP connection:

true - Connected to an FTP server.
false - Not connected.

#### Example:

    -- check for a connection and log off (if required) before exiting the application
    if FTP.IsConnected() then
        FTP.Disconnect();
    end

    Application.Exit();

### boolean FTP.IsValidHostname (string Hostname);

#### Description:

Returns true if the given hostname or IP address is valid (formatted properly).

#### Hostname:

(string) The hostname or IP address whose format you want to validate.

#### Returns:

(boolean) Whether there is an FTP connection:

true - Hostname/IP address is formatted properly.
false - Invalid hostname/IP address format.

#### Example:

    -- ask user for a hostname/IP address
    strHostname = Dialog.Input("What site do you want to connect to?", "Hostname/IP Address:")

    -- does it look valid?
    if FTP.IsValidHostname(strHostname) then
        Dialog.Message("", "'"..strHostname.."' looks valid to me.");
    else
        Dialog.Message("", "'"..strHostname.."' is not valid!");
    end

### table FTP.List ();

#### Description:

Returns a numerically indexed table of tables with information about each file or folder in the current directory on the FTP server.

#### Returns:

(table) A numerically indexed table containing one table of information for every file and folder in the current directory.

The total number of files and folders (i.e. the number of directory entries) is stored in a key named Count. You can use this value to determine how many "sub-tables" are in the main table.

Note: The information about the files and folders is stored in the table in the same order as it is returned from the server. It often won't be sorted in any way.

If successful, the following information will be stored for each file or folder in the directory:

Name:
(string) The name of the file or folder.

Size:
(number) The size of the file, in bytes. (For folders, this is usually a fixed value, like 1024 or 4096. The actual value is server specific.)

Year:
(number) The year from the file (or folder) date, e.g. 2003.

Month:
(number) The month from the file (or folder) date, e.g. 12.

Day:
(number) The day from the file (or folder) date, e.g. 25.

Hour:
(number) The hour from the file (or folder) date, e.g. 16.

Minute:
(number) The minute from the file (or folder) date, e.g. 57.

Date:
(string) The file (or folder) date in "<weekday>, <month> <day>, <year>" format, e.g. Thursday, Dec 25, 2003.

DateISO:
(string) The file (or folder) date in ISO format, e.g. 2003-12-25T16:57:00.

Type:
(number) The type of entry. Either 0 (FTP.FOLDER) or 1 (FTP.FILE).

#### Example:

    -- display the name, size and date for every file and folder in the current directory
    -- in an AutoPlay Media Studio listbox object named "DirList"
    -- (note: the listbox object must already exist on the current page)

    -- empty the listbox
    ListBox.DeleteItem("DirList",LB_ALLITEMS);

    tbEntries = FTP.List();

    -- add each item to the listbox in this format:
    -- <name> (<size>) (<date>)
    for i = 1, tbEntries.Count do
        local name = tbEntries[i].Name;
        local size = tbEntries[i].Size;
        local date = tbEntries[i].Date;

        if tbEntries[i].Type == FTP.FOLDER then
            -- add a [ ] prefix to make the folders stand out in the listbox
            ListBox.AddItem("DirList","[ ] "..name.."("..size.." bytes) ("..date..")");
        else
            ListBox.AddItem("DirList",name.."("..size.." bytes) ("..date..")");
        end
    end

### table FTP.ListFiles ();

#### Description:

Returns a numerically indexed table of tables with information about each file in the current directory on the FTP server.

#### Returns:

(table) A numerically indexed table containing one table of information for every file in the current directory.

The total number of files is stored in a key named Count. You can use this value to determine how many "sub-tables" are in the main table.

If successful, the following information will be stored for each file in the directory:

Name:
(string) The name of the file.

Size:
(number) The size of the file, in bytes.

Year:
(number) The year from the file date, e.g. 2003.

Month:
(number) The month from the file date, e.g. 12.

Day:
(number) The day from the file date, e.g. 25.

Hour:
(number) The hour from the file date, e.g. 16.

Minute:
(number) The minute from the file date, e.g. 57.

Date:
(string) The file date in "<weekday>, <month> <day>, <year>" format, e.g. Thursday, Dec 25, 2003.

DateISO:
(string) The file date in ISO format, e.g. 2003-12-25T16:57:00.

#### Example:

    -- display the name, size and date for every file in the current directory
    -- in an AutoPlay Media Studio listbox object named "DirList"
    -- (note: the listbox object must already exist on the current page)

    -- empty the listbox
    ListBox.DeleteItem("DirList",LB_ALLITEMS);

    tbFiles = FTP.ListFiles();

    -- add each item to the listbox in this format:
    -- <name> (<size>) (<date>)
    for i = 1, tbFiles.Count do
        local name = tbFiles[i].Name;
        local size = tbFiles[i].Size;
        local date = tbFiles[i].Date;

        ListBox.AddItem("DirList",name.."("..size.." bytes) ("..date..")");
    end

### table FTP.ListFolders ();

#### Description:

Returns a numerically indexed table of tables with information about each folder in the current directory on the FTP server.

#### Returns:

(table) A numerically indexed table containing one table of information for every folder in the current directory.

The total number of folders is stored in a key named Count. You can use this value to determine how many "sub-tables" are in the main table.

If successful, the following information will be stored for each folder in the directory:

Name:
(string) The name of the folder.

Size:
(number) Possibly the size of the folder, in bytes...but this is usually a fixed value, like 1024 or 4096. (The actual value is server specific.)

Year:
(number) The year from the folder date, e.g. 2003.

Month:
(number) The month from the folder date, e.g. 12.

Day:
(number) The day from the folder date, e.g. 25.

Hour:
(number) The hour from the folder date, e.g. 16.

Minute:
(number) The minute from the folder date, e.g. 57.

Date:
(string) The folder date in "<weekday>, <month> <day>, <year>" format, e.g. Thursday, Dec 25, 2003.

DateISO:
(string) The folder date in ISO format, e.g. 2003-12-25T16:57:00.

#### Example:

    -- display the name, size and date for every folder in the current directory
    -- in an AutoPlay Media Studio listbox object named "DirList"
    -- (note: the listbox object must already exist on the current page)

    -- empty the listbox
    ListBox.DeleteItem("DirList",LB_ALLITEMS);

    tbFolders = FTP.ListFolders();

    -- add each item to the listbox in this format:
    -- <name> (<size>) (<date>)
    for i = 1, tbFolders.Count do
        local name = tbFolders[i].Name;
        local size = tbFolders[i].Size;
        local date = tbFolders[i].Date;

        ListBox.AddItem("DirList",name.."("..size.." bytes) ("..date..")");
    end

### FTP.MakeDir (string DirName);

#### Description:

Creates a new folder in the current directory on the FTP server.

#### DirName:

(string) The name of the folder you want to create.

#### Returns:

Nothing.

#### Example:

    -- create a folder named "yippee" in the current directory
    FTP.MakeDir("yippee");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

### FTP.NoOp ();

#### Description:

Performs a "no-op" operation (a NOOP command).

Note: This action doesn't do anything beyond triggering a response from the server. It's usually used as part of a "keep-alive" routine to prevent a server from breaking a connection due to inactivity.

#### Returns:

Nothing.

#### Example:

    -- tickle the server to keep it awake
    FTP.NoOp();

### FTP.RemoveDir (string DirName);

#### Description:

Deletes a specific folder in the current directory on the FTP server.

#### DirName:

(string) The name of the folder you want to delete.

#### Returns:

Nothing.

#### Example:

    -- delete a folder named "yippee" in the current directory
    FTP.RemoveDir("yippee");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

### FTP.Rename (string Oldname, string Newname);

#### Description:

Renames a file in the current directory on the FTP server.

#### Oldname:

(string) The name of the file you want to rename.

#### Newname:

(string) The new name for the file.

#### Returns:

Nothing.

#### Example:

    -- rename a file named "jekyll.doc" to "hyde.txt" in the current directory
    FTP.Rename("jekyll.doc", "hyde.txt");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

### FTP.Resume (string Source, string Destination, function CallbackFunction);

#### Description:

Resumes downloading a file from the current directory on the FTP server. (Continues downloading a file whose download was interrupted.)

#### Source:

(string) The name of the file that you want to download.

#### Destination:

(string) The full path and filename of the destination file that you want to download to. If a file by that name already exists, and its size is less than the total size of the source file, the download will be "resumed" and the data will be added to the end of the file. If the file doesn't exist, it will be downloaded and created normally (i.e. just like FTP.Download).

#### CallbackFunction:

(string) The name of a function that will be called whenever progress is made in the download operation. (You can use this callback function to display the progress of the download operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

##### Bytes:

(number) The number of bytes that have been transferred so far.

##### TotalBytes:

(number) The total number of bytes to transfer, or 0 if the total number of bytes is not known.

The callback function should return a boolean value (true or false) indicating whether the download should continue:

true - Continue downloading the file.
false - Abort the download.

#### Returns:

Nothing.

#### Example:

    -- resume a previously interruped download
    FTP.Resume("jekyll.txt", _TempFolder .. "\\jekyll.txt");
    err = Application.GetLastError();
    if err == FTP.OK then
        Dialog.Message("Success!", _TempFolder.."\\jekyll.txt was downloaded successfully!");
    else
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

### FTP.SetCommandCallback (function CallbackFunction);

#### Description:

Registers a callback function to be called whenever a command is sent to the server.

#### CallbackFunction:

(string) The name of a function that will be called whenever a command is sent to the server.

Note: Set CallbackFunction to nil to "unregister" an existing command callback (i.e. to stop the function from being called whenever a command is sent).

The callback function must be able to receive the following parameter:

##### Command:

(string) The command that was sent to the server.

The callback function should not return anything.

#### Returns:

Nothing.

#### Example 1:

    -- this function displays the command strings in an AutoPlay Media Studio paragraph object named "Log"
    -- (note: the paragraph object must already exist on the current page)
    function cbCommand(strCommand)

        -- make sure we don't display the login password
        if String.Left(strCommand, 4) == "PASS" then
            -- replace the command string with a safe (phony) string
            -- note: this only changes the contents of the strCommand variable
            --       within this function; it has no effect on the command that
            --       was sent to the server.
            strCommand = "PASS ****\r\n";
        end

        -- append the command string to the existing text in the paragraph object
        local strLog = Paragraph.GetText("Log");
        Paragraph.SetText("Log",strLog..strCommand);

        -- scroll the paragraph to the bottom
        Paragraph.SetScrollPos("Log",9999999999);
    end

    -- register our command callback function so it gets called for every FTP command
    FTP.SetCommandCallback(cbCommand);

#### Example 2:

    -- this function displays the command strings in a debug window
    function cbCommand(strCommand)

        -- make sure we don't display the login password
        if String.Left(strCommand, 4) == "PASS" then
            -- replace the command string with a safe (phony) string
            -- note: this only changes the contents of the strCommand variable
            --       within this function; it has no effect on the command that
            --       was sent to the server.
            strCommand = "PASS ****\r\n";
        end

        -- open the debug window if it isn't already open
        Debug.ShowWindow(true);

        -- output the command to the debug window
        Debug.Print(strCommand);

        -- note: the debug window may not update while the plugin is communicating with the server
        --       so you'll only see the commands in the window after the interaction is complete
    end

    -- register our command callback function so it gets called for every FTP command
    FTP.SetCommandCallback(cbCommand);

### FTP.SetConnectTimeout (number Timeout);

#### Description:

Sets the number of seconds that the application will wait while attempting to establish a connection with the FTP server.

#### Timeout:

(number) The connection timeout, in seconds.

#### Returns:

Nothing.

#### Example 1:

    -- wait 15 seconds before giving up when trying to connect
    FTP.SetConnectTimeout(15);

#### Example 2:

    -- increase the current connection timeout by 5 seconds
    FTP.SetConnectTimeout( FTP.GetConnectTimeout() + 5 );

### FTP.SetControlPort (number ControlPort);

#### Description:

Sets the control port that will be used for communication with the FTP server.

#### ControlPort:

(number) The control port to use for communication with the FTP server.

#### Returns:

Nothing.

#### Example:

    -- set the control port to 21
    FTP.SetControlPort(21);

### FTP.SetDataPort (number DataPort);

#### Description:

Sets the data port that will be used for communication with the FTP server.

#### DataPort:

(number) The data port to use for communication with the FTP server.

#### Returns:

Nothing.

#### Example:

    -- set the data port to 1050
    FTP.SetDataPort(1050);

### FTP.SetPassiveMode (boolean PassiveMode);

#### Description:

Sets the data transfer mode to use when communicating with the server.

#### PassiveMode:

(boolean) Whether to communicate with the server in passive mode:

true - Turn on passive mode (where control and data connections are both originated by the client).
false - Turn off passive mode.

#### Returns:

Nothing.

#### Example:

    -- turn passive mode on
    FTP.SetPassiveMode(true);

### FTP.SetResponseCallback (function CallbackFunction);

#### Description:

Registers a callback function to be called whenever a command response is received from the server.

#### CallbackFunction:

(string) The name of a function that will be called whenever a command response is received from the server.

Note: Set CallbackFunction to nil to "unregister" an existing response callback (i.e. to stop the function from being called whenever a response is received).

The callback function must be able to receive the following parameter:

##### Response:

(string) The response that was received from the server.

The callback function should not return anything.

#### Returns:

Nothing.

#### Example:

    -- this function displays the server responses in an AutoPlay Media Studio paragraph object named "Log"
    -- (note: the paragraph object must already exist on the current page)
    function cbResponse(strResponse)

        -- append the response string to the existing text in the paragraph object
        local strLog = Paragraph.GetText("Log");
        Paragraph.SetText("Log",strLog..strResponse);

        -- scroll the paragraph to the bottom
        Paragraph.SetScrollPos("Log",9999999999);
    end

    -- register our response callback function
    FTP.SetResponseCallback(cbResponse);

### FTP.SetTransferType (number TransferType);

#### Description:

Sets the data transfer mode to use when communicating with the server.

#### TransferType:

(number) The transfer type to use for uploads and downloads:

0: (FTP.ASCII) - ASCII (type A) transfer type.
1: (FTP.BINARY) - Binary (type I) transfer type.
2: (FTP.AUTO) - Automatically choose the appropriate transfer type based on the file extension.

Note: When set to FTP.AUTO, the transfer type will default to FTP.BINARY, unless the file extension is found in the special FTP.ASCII_Extensions string.

Tip: You can control which files will be recognized as ASCII files by modifying the value of FTP.ASCII_Extensions.

#### Returns:

Nothing.

#### Example:

    -- switch to binary transfer type
    FTP.SetTransferType(FTP.BINARY);

### FTP.Upload (string Source, string Destination, function CallbackFunction);

#### Description:

Uploads a file to the current directory on the FTP server.

#### Source:

(string) The full path and filename of the file that you want to upload.

#### Destination:

(string) The name that you want the uploaded file to have.

#### CallbackFunction:

(string) The name of a function that will be called whenever progress is made in the upload operation. (You can use this callback function to display the progress of the upload operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

##### Bytes:

(number) The number of bytes that have been transferred so far.

##### TotalBytes:

(number) The total number of bytes to transfer, or 0 if the total number of bytes is not known.

The callback function should return a boolean value (true or false) indicating whether the upload should continue:

true - Continue uploading the file.
false - Abort the upload.

#### Returns:

Nothing.

#### Example 1:

    -- upload a file to the current directory
    -- (note: assumes already connected to an FTP server)

    FTP.ChangeDir("/uploads");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- enable the status dialog's cancel button
    StatusDlg.ShowCancelButton();

    -- show the status dialog
    StatusDlg.Show();

    -- upload the file
    FTP.Upload("c:\\myfolder\\myfile.txt", "myfile.txt");
    err = Application.GetLastError();

    -- hide the status dialog
    StatusDlg.Hide();

    -- ...and check whether FTP.Upload generated an error
    if err == FTP.OK then
        Dialog.Message("Success!", "myfile.txt was uploaded successfully!");
    else
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

#### Example 2:

    -- upload a file to the current directory
    -- using a custom progress display
    -- (note: assumes already connected to an FTP server)

    -- display the progress in an AutoPlay Media Studio paragraph object named "Progress"
    -- (note: the paragraph object must already exist on the page)
    function cbUpload(nBytes, nTotal)
        if nTotal == 0 then
            Paragraph.SetText("Progress", nBytes .. " bytes uploaded!")
        else
            Paragraph.SetText("Progress", nBytes / nTotal * 100 .. "% uploaded!")
        end
    end

    FTP.ChangeDir("/uploads");
    err = Application.GetLastError();
    if err ~= FTP.OK then
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

    -- enable the status dialog's cancel button
    StatusDlg.ShowCancelButton();

    -- show the status dialog
    StatusDlg.Show();

    -- upload the file
    FTP.Upload("c:\\myfolder\\myfile.txt", "myfile.txt", cbUpload);
    err = Application.GetLastError();

    -- hide the status dialog
    StatusDlg.Hide();

    -- ...and check whether FTP.Upload generated an error
    if err == FTP.OK then
        Dialog.Message("Success!", "myfile.txt was uploaded successfully!");
    else
        Dialog.Message("Error", _tblErrorMessages[err]);
    end

## Error Codes

0 | (FTP.OK) | - | (no error)
31000 | (FTP.ERR_BAD_HOSTNAME) | - | Invalid hostname.
31001 | (FTP.ERR_NO_RESPONSE) | - | No response from server.
31002 | (FTP.ERR_INVALID_RESPONSE) | - | Negative response received from server.
31003 | (FTP.ERR_USER_NOT_ACCEPTED) | - | Username not accepted.
31004 | (FTP.ERR_PASSWORD_NOT_ACCEPTED) | - | Password not accepted.
31005 | (FTP.ERR_ACCOUNT_NOT_ACCEPTED) | - | Account string not accepted.
31006 | (FTP.ERR_CONNECT_FAILED) | - | Could not connect to FTP site.
31007 | (FTP.ERR_REQUEST_DENIED) | - | Request denied by server.
31008 | (FTP.ERR_INVALID_TRANSFER_TYPE) | - | Invalid transfer type. Valid values are 0, 1 and 2 (FTP.ASCII, FTP.BINARY or FTP.AUTO).
31009 | (FTP.ERR_INVALID_TIMEOUT_VALUE) | - | Invalid timeout value.
31010 | (FTP.ERR_SET_CONTROL_PORT_FAILED) | - | Could not set the control port.
31011 | (FTP.ERR_SET_DATA_PORT_FAILED) | - | Could not set the data port.
31012 | (FTP.ERR_INVALID_COMMAND) | - | FTP command cannot be an empty string.
31013 | (FTP.ERR_RENAME_FROM_SOURCE_FAILED) | - | Could not rename the file - problem with the "from" file (RNFR command failed).
31014 | (FTP.ERR_RENAME_TO_TARGET_FAILED) | - | Could not rename the file - problem with the "to" file (RNTO command failed).
31015 | (FTP.ERR_DATA_CONNECT_FAILED) | - | Data port could not be opened.
31016 | (FTP.ERR_PORT_REQUEST_FAILED) | - | Request to set data port rejected (PORT command failed).
31017 | (FTP.ERR_RETRIEVE_FAILED) | - | Unable to download file (RETR command failed).
31018 | (FTP.ERR_STORE_FAILED) | - | Unable to upload file (STOR command failed).
31019 | (FTP.ERR_CONNECTION_TERMINATED) | - | Connection was terminated before data transfer was complete.
31020 | (FTP.ERR_ABORTED) | - | Operation aborted by user.
31021 | (FTP.ERR_UNKNOWN_ERROR) | - | An unknown error occurred.
31022 | (FTP.ERR_INVALID_ADDRESS) | - | Invalid address.

## Change Log

### 2.0.1.0

- Compiled the 32-bit FTP action plugin using a newer compiler.
- Added a 64-bit version of the FTP action plugin (FTPx64.lmd) and plugin template file (_plugin_template.xml).

### 2.0.0.0

- Updated to version 2.0 of the plugin SDK.

### 1.0.1.0

- Updated version resource information.

### 1.0.0.1

- Removed test for no dots and more than 3 dots in the hostname validation routine to allow for unlimited sub-domains and Unix HOSTALIASES (e.g. ftp.pwp.blueyonder.co.uk works now)
- No longer crashes if you call FTP.Download on a file that doesn't exist and there is no callback function defined
- F1 help now works if you have Mozilla Firefox installed
- New error code: XML.ERROR_INVALID_ADDRESS

### 1.0.0.0

- Initial release

## Additional Information

### Author:

Indigo Rose Corporation
http://www.indigorose.com/support/

### Copyright:

The FTP Actions Plugin is copyright © 2003-2015 Indigo Rose Software Design Corporation.

### Website:

http://www.indigorose.com

Copyright © 2015 Indigo Rose Software Design Corporation.
All Rights Reserved.