FTP Actions Plugin

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:

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:

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:

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:

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:

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