Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

FileTransfer Module

The FileTransfer Module is used to send or receive files between the local filestore and either an FTP or HTTP site.

Syntax

fileTransfer (Module) <META> Syntax

<META HTTP-Equiv="FileTransfer" content="[Method | Parameter]">

<META HTTP-Equiv="FileTransfer" content="TransferEvent:url('[jsFunction | url]')">

FileTransfer JavaScript Object Syntax:
By default the JavaScript Object 'fileTransfer' will exist on the current page and can be used to interact directly with the fileTransfer.
To Invoke fileTransfer methods via JavaScript use the following syntax: filetransfer.method();

e.g. fileTransfer.transfer();
To Set fileTransfer parameters via JavaScript use the following syntax: filetransfer.parameter = 'value'; remembering to enclose your value in quotes where appropriate.

e.g. fileTransfer.destination = 'value';
To Set fileTransfer return events via JavaScript use the following syntax: filetransfer.event = Javascript Function;

e.g. fileTransfer.transferEvent = 'doFunction(%json)';

For more details on the event syntax and parameters see the Retrieval Events page.
To set multiple EMML parameters / events on a single line use the following syntax: filetransfer.setEMML("[Your EMML Tags]");

e.g. fileTransfer.setEMML("destination:value;transferEvent:url('JavaScript:doFunction(%json)');transfer");
FileTransfer Ruby Object Syntax:
By default the Ruby Object 'FileTransfer' will exist on the current page and can be used to interact directly with the FileTransfer. All Methods, Parameters and Events are the same as Javascript, however, notice 'FileTransfer' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()'
To Invoke FileTransfer methods via Ruby use the following syntax: FileTransfer.method()

e.g. FileTransfer.transfer
To Set FileTransfer parameters via Ruby use the following syntax: FileTransfer.parameter = 'value' remembering to enclose your value in quotes where appropriate.

e.g. FileTransfer.destination = 'value'
To Set FileTransfer return events via Ruby use the following syntax: FileTransfer.event = url_for(:action => :event_callback)

e.g. FileTransfer.transferEvent = url_for(:action => :filetransfer_event_callback)

For more details on the event syntax and parameters see the Retrieval Events page.

To access the event parameters in a Ruby callback function, you reference the @params object within the callback function. This object is simply a ruby hash {"parameter1 name" => "parameter1 value", "parameter2 name" => "parameter2 value", ...}

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description Default Value
transfer Sends or receives the file according to the configured properties. N/A

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Name Possible Values Description Default Value
destination:[Value] URL or a path Sets the destination path and name of the file to be transferred. If specifying a URL this should be fully qualified with protocol, port and optionally username and password. N/A
source:[Value] URL or a path Sets the source path and name of the file to be transferred. If specifying a URL this should be fully qualified with protocol, port and optionally username and password. N/A
username:[Value] String The username for the HTTP or FTP server if required No username
password:[Value] String The password for the HTTP or FTP server if required No password
createFolders:[Value] 'True' or 'False' On a filetransfer that results in local file storage, createFolders can automatically create the directory path. False
overWrite:[Value] 'True' or 'False' On a filetransfer that results in local file storage, OverWrite will overwrite the destination file if it already exists. False

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a Javascript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or javascript arrays. Event parameters can be accessed either directly or via JSON objects.


transferEvent

Provided the source and destination parameters were valid, the TransferEvent is fired after the transfer has been made. When the transfer is via the HTTP protocol ‘OK: File Received’ is returned; for HTTP uploads the destination server message is returned. When the transfer is via FTP either ‘OK: File Sent’, ‘OK: File Received’. If there is an error during the transfer ‘Error:’ will be returned and may be followed by the relevant Windows error code; see the log file for more information on the error. Note when downloading from an HTTP server if the requested file does not exist you may receive ‘OK: File received’ and the server 404 string placed in your destination file.

ID Name Description
1 transferResult Success or failure of the transfer, see note above.

Remarks

Default Ports

The default port settings are 80 for HTTP and 21 for FTP.

Common mistakes

Remember that in Javascript the ‘\’ character is the escape character so to use a backslash in the URL use ‘\’. This is not the case when specifying the URL via a meta tag where a single ‘\’ will suffice. See the examples above.

Setting up a Transfer

File transfer is designed to be configured before any transfer() is made. Once a transfer hs been initiated the parameters can not be guaranteed to be the same for the next transfer, therefore set all non default parameters before starting the transfer.

Creating a fully qualified URL

The protocol, port number, username (optional) and password (optional) are all derived from the URL string and should be specified in the following manner: [protocol]://[username]:[password@]Server[:Port]FileNameAndPath. FTP Example: ftp://admin:root@192.168.1.1:2500/Folder/file.txt. HTTP Example: http://admin:root@192.168.1.1:8080/Folder/upload.aspx

Relative URLs

The FileTransfer meta tag also supports relative URLs, for example if the current page’s path is ‘http://192.168.0.1/myElementsApp/index.html and you specify <META HTTP-Equiv=“FileTransfer” Content=“Source:url(’../file.xls')”> then the source file will be ‘http://192.168.0.1/file.xls’. This notation can also be used for FTP upload and file URLs. Note that the relative URL must start with a ‘.’ so to specify a file in the same directory as your application page use Source:url(‘./file.xls’)

Maximum File Size

The maximum file size which can be transferred is about 4MB but is also dependant on the memory available to the device and the transport protocol selected. For file sizes above 2MB on lower memory devices alternate methods for transferring files should be considered.

Platform differences

Although the file transfer functionality has the same behavior on all supported platforms the vast majority of the times, there might be scenarios where the Android version may return different error codes when compared to the Windows (CE, Mobile) version.

File transfer result code received in Javascipt or JASON events

If an invalid username or password are used on an FTP transfer to a remote server the response returned is 0 instead of the expected 12014

Requirements

RhoElements Version 1.0.0 or above
Supported Devices All supported devices.
Minimum Requirements None.
Persistence Transient - any changes made by changing parameters will be lost when navigating to a new page or initiating a transfer.

HTML/Javascript Examples

The following example shows how to move the file ‘myfile.txt’ from the device’s root to a folder off the root:

<META HTTP-Equiv="FileTransfer" Content="Source:url('file://\myfile.txt')">
<META HTTP-Equiv="FileTransfer" Content="Destination:url('file://\MyFolder\myfile.txt')">
<META HTTP-Equiv="FileTransfer" Content="Overwrite:True">
<META HTTP-Equiv="FileTransfer" Content="CreateFolders:True">
<META HTTP-Equiv="FileTransfer" Content="Transfer">

The following example sets up a protocol, destination and source file and sends the file via HTTP. Upon a successful transfer, the server message (if any) is sent to ‘mypage.asp.’:

<META HTTP-Equiv="FileTransfer" Content="TransferEvent:url('mypage.asp?Data=%s')">
<META HTTP-Equiv="FileTransfer" Content="Destination:url('HTTP://192.168.1.1/accounts/upload.aspx')">
<META HTTP-Equiv="FileTransfer" Content="Source:url('file://\temp/accounts.xls')">
<META HTTP-Equiv="FileTransfer" Content="Transfer">

The following example shows how to download a file from an HTTP server.

<META HTTP-Equiv="FileTransfer" Content="TransferEvent:url('Javascript:alert('%s')'); Transfer">

<script type="text/javascript">
   //  HTTP Functions

   //  Download from an HTTP site
   function downloadFromHTTP()
   {
      fileTransfer.source = "url('http://myserver/myfile.txt')";
      fileTransfer.destination = "url('file://\\myfile.txt')";
      fileTransfer.transfer();     
   }

   //  Download from an HTTP site requiring login credentials
   function downloadFromHTTPAuth()
   {
      fileTransfer.source = "url('http://httpAdmin:httpPassword@myserver/myfile.txt')";
      fileTransfer.destination = "url('file://\\myfile.txt')";
      fileTransfer.transfer();
   }
</script>

The following example shows to transfer a file via FTP. After each transfer the result (OK or Error) is given in an alert box.

<META HTTP-Equiv="FileTransfer" Content="TransferEvent:url('Javascript:alert('%s')'); Transfer">

<script type="text/javascript">
   //  FTP Functions

   //  Upload to an FTP server
   function uploadToFTP()
   {
        fileTransfer.source = "url('file://\\Program Files\\RhoElements\\file.txt')";
        fileTransfer.destination = "url('ftp://192.168.4.110/file.txt')";
        fileTransfer.transfer();     
   }

   //  Upload to an FTP server on port 2500 using username 'ftpadmin' and password 'ftpadminpw'
   function uploadToFTPWithAuthentication()
   {
        fileTransfer.source = "url('file://\\Program Files\\RhoElements\\file.txt')"; 
        fileTransfer.destination = "url('ftp://ftpadmin:ftpadminpw@192.168.4.110:2500/Folder/file.txt')";
        fileTransfer.transfer();    
   }

   //  Download from an FTP Server using username 'ftpadmin' and password 'ftpadminpw'   
   function downloadFromFTP()
   {
        fileTransfer.source = "url('ftp://ftpadmin:ftpadminpw@192.168.4.110/NewFolder/file.txt')"; 
        fileTransfer.destination = "url('file://\\sigReceived.bmp')";
        fileTransfer.transfer();
   }
</script>

Ruby Examples

The following example moves a file ‘myfile.txt’ from the root of the device to the ‘myFolder’ folder inside of the root. The folder does not need to be created.

def transferLocally
    FileTransfer.source="url('file://\\myfile.txt')"
    FileTransfer.destination="url('file://\\MyFoder\\myfile.txt')"
    FileTransfer.overWrite='true'
    FileTransfer.createFolders='true'
    FileTransfer.transfer
end

To call the this function from HTML, use the following code:

<li onclick="tranferLocal(); ">Transfer file locally</li>

Where ‘transferLocal()’ is a JavaScript function which looks like:

function tranferLocal() {
    $.get('/app/FileTransfer/transferLocally', { });
    return false;
}

The following example sets up a protocol, destination and source file and sends the file via HTTP. It also attaches a listener to the ‘transferEvent’ to display the server message, if any. The ‘transferEventListener’ function is described at the end of this document.

def transferToHttp
    FileTransfer.transferEvent=url_for(:action => :transferEventListener)
    FileTransfer.destination="url('HTTP://192.168.1.1/accounts/upload.aspx')"
    FileTransfer.source="url('file://myfile.txt')"
    FileTransfer.transfer
end

The following example shows how to download a file via HTTP when there are no login credentials required:

def downloadFile
    FileTransfer.transferEvent=url_for(:action => :transferEventListener)
    FileTransfer.source="url('http://myserver/myfile.txt')"
    FileTransfer.destination="url('fil://myfile.txt')"
    FileTransfer.transfer
end

The following example shows how to download a file via HTTP with login credentials:

def downloadFileWithCredentials
    FileTransfer.transferEvent=url_for(:action => :transferEventListener)
    FileTransfer.source="url('http://myusername:mypassword@myserver/myfile.txt')"
    FileTransfer.destination="url('fil://myfile.txt')"
    FileTransfer.transfer
end

The following example shows how to upload a file via FTP without login credentials required:

def uploadFileViaFTP
    FileTransfer.transferEvent=url_for(:action => :transferEventListener)
    FileTransfer.destination="url('ftp://192.168.4.110/file.txt')"
    FileTransfer.transfer  
end

The following example shows how to upload a file via FTP on port 2500 where login is required:

def uploadFileViaFTPWithCredentials
    FileTransfer.transferEvent=url_for(:action => :transferEventListener)
    FileTransfer.destination="url('ftp://ftpusername:ftppasswor@192.168.4.110:2500/file.txt')"
    FileTransfer.transfer  
end  

All the examples above can be called via HTTP in a manner similar to that described for the ‘transferLocally’ function above. The ‘transferEventListener’ method is given below. It simply sets the transfer result to an HTML div via JavaScript.

def transferEventListener
    WebView.execute_js("setFieldValue('"+@params['transferResult']+"');")
end
Back to Top