Developer Resources

FileTransfer

Overview

FileTransfer allows the user to communicate with SFTP and FTP. Both the normal FTP and the secure SFTP protocols are supported.

Constructor

FileTransfer()

Events

FileTransfer.finished

Fired when asynchronous file transfers are finished

Methods

FileTransfer.cancel

Cancels an asynchronous transfer

FileTransfer.download

Downloads a file from an FTP or SFTP server

FileTransfer.getBytesTransferred

Returns the total number of bytes received or sent.

FileTransfer.isDone

Returns a value indicating whether the request is done

FileTransfer.rename

Renames a filename on a remote FTP or SFTP server

FileTransfer.setAsync

Turns asynchronous mode on or off

FileTransfer.upload

Uploads a file to an FTP or SFTP server

Example

var file = "index.html";
var ftp = new BasicFtpRequest;
var result = ftp.download(file);

Application.run();  // necessary to process events


class BasicFtpRequest
{
    function BasicFtpRequest()
    {
        // initialize the member variables
        m_secure     = false;                   // if true, use sftp; otherwise use ftp
        m_username   = "anonymous";             // username
        m_password   = "anonymous";             // password
        m_server_dir = "ftp-test.mozilla.org/"; // server directory; e.g. "www.domain.com/"
        m_local_dir  = "c:/";                   // local directory; e.g. "c:/temp/"
        m_file       = "";                      // file to download/upload; set later

        // create the ftp transfer object, set the file
        // transfer option to async, and connect the
        // finished event
        m_ftp_transfer = new FileTransfer;
        m_ftp_transfer.setAsync(true);
        m_ftp_transfer.finished.connect(this, onFinished);
    }

    function onFinished()
    {
        // when we're finished, return an alert message
        alert("Finished transfering " + m_file + " to " + m_local_dir + m_file);
    }

    function download(file)
    {
        // set the file member
        m_file = file;

        // create the full source path
        var source = (m_secure ? 's' : '') + 'ftp://'
            + (m_username ? m_username + ":" + m_password + "@" : '')
            + m_server_dir
            + m_file;

        // create the full destination path
        var destination = m_local_dir + m_file;

        // issue the download request
        return m_ftp_transfer.download(source, destination);
    }

    function upload(file)
    {
        // set the file member
        m_file = file;

        // create the full source path
        var source = m_local_dir + m_file;

        // create the full destination path
        var destination = (m_secure ? 's' : '') + 'ftp://'
            + (m_username ? m_username + ":" + m_password + "@" : '')
            + m_server_dir
            + m_file;

        // issue the upload request
        return m_ftp_transfer.upload(source, destination);
    }

    // member variables
    var m_secure;
    var m_username;
    var m_password;
    var m_server_dir;
    var m_local_dir;
    var m_file;
    var m_ftp_transfer;
}

FileTransfer.cancel

function FileTransfer.cancel()

Description

Calling this method causes an asynchronous transfer to abort.

FileTransfer.download

function FileTransfer.download(url : String, destination_filename : String) : Boolean

Arguments

url

The remote location to download

destination_filename

The filename to save, with full path name.

Returns

Returns true upon successful completion, otherwise false if an error occurred.

Description

Calling this method downloads a file from an FTP or an SFTP server onto the local computer. The url specified in the url parameter takes the following format: sftp://username:password@servername.domain.com/path/to/filename.ext -- If you wish to use the ftp protocol, change the protocol identifier before the first colon in the url string.

FileTransfer.getBytesTransferred

function FileTransfer.getBytesTransferred() : Number

Returns

Total number of transferred bytes

Description

A call to this method returns the total number of bytes received or sent. This function may also be called during asynchronous transfers.

FileTransfer.isDone

function FileTransfer.isDone() : Boolean

Returns

True if the file transfer is finished, false if it is still running

Description

Returns a boolean value indicating whether the most recent file transfer operation is finished.

FileTransfer.rename

function FileTransfer.rename(source_url : String, new_name : String) : Boolean

Arguments

source_url

The file to rename on the remote server

new_name

The new name the file should take

Returns

Returns true upon successful completion, otherwise false if an error occurred.

Description

Calling this method renames a file on a remote FTP or SFTP server The source url specified in source_url parameter takes the following format: sftp://username:password@servername.domain.com/path/to/filename.ext -- If you wish to use the ftp protocol, change the protocol identifier before the first colon in the url string. The filename specified in the new_name parameter indicates the new name that the file will take. It should be specified as a simple filename, without a qualifying path name.

FileTransfer.setAsync

function FileTransfer.setAsync(value : Boolean)

Arguments

value

Specifying true turns on asynchronous mode and false turns it off

Description

Turns asynchronous mode on or off. If asynchronous mode is on, requests will return immediately and the processing will be done in the background. Upon completion of the request, the finished event is fired.

FileTransfer.upload

function FileTransfer.upload(source_filename : String, destination_url : String) : Boolean

Arguments

source_filename

The filename to upload

destination_url

The destination location of the upload

Returns

Returns true upon successful completion, otherwise false if an error occurred.

Description

Calling this method uploads a file from the local computer to an FTP or an SFTP server. The destination url specified in the destination_url parameter takes the following format: sftp://username:password@servername.domain.com/path/to/filename.ext -- If you wish to use the ftp protocol, change the protocol identifier before the first colon in the url string.