Overview
The FileTransfer Module is used to send or receive files between the device filestore and an FTP or HTTP site.
Enabling the API
In order to use this API you must include reference to the following JavaScript file that is included with the Enterprise Browser installation:
- elements.js
Note - this file either needs to be on the device in a relative folder from where your HTML page is, or it must be copied to your web server appropriately.
<script type="text/javascript" charset="utf-8" src="elements.js"></script>;
API Usage
This API does not use the EB namespace. It is simply referenced using the API name:
function downloadFromHTTP()
{
fileTransfer.source = "url('http://myserver/myfile.txt')";
fileTransfer.destination = "url('file://\\myfile.txt')";
fileTransfer.transfer();
}
Events
To handle events, you assign a string value to the event name that represents a function name or javascript statement to execute.
transferEvent
Provided the source and destination parameters were valid, the TransferEvent is fired after the transfer has been made.
Callback Parameters
- transferResult - Success or failure of the transfer
Using the HTTP protocol:
- 'OK: File Received' is returned;
- 'destination server message' for HTTP uploads
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.
Using the FTP protocol:
- 'OK: File Sent'
- 'OK: File Received'
- 'Error': If there is an error during the transfer and may be followed by the relevant Windows error code; see the log file for more information on the error.
Usage
function downloadFromHTTP()
{
fileTransfer.source = "url('http://myserver/myfile.txt')";
fileTransfer.destination = "url('file://\\myfile.txt')";
fileTransfer.transferEvent = "url('JavaScript:handleResult(%json);')";
fileTransfer.transfer();
}
function handleResult(params){
alert('Download Result:' + params['transferResult']);
}
Methods
transfer()
Sends or receives the file according to the configured properties.
Returns
- Void
Platforms
- Android
- Windows Mobile/CE
Properties
destination
Type
STRING
Description
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.
Possible Values
- URL or a path
Platforms
- Android
- Windows Mobile/CE
source
Type
STRING
Description
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.
Possible Values
- URL or a path
Platforms
- Android
- Windows Mobile/CE
username
Type
STRING
Description
The username for the HTTP or FTP server if required.
Platforms
- Android
- Windows Mobile/CE
password
Type
STRING
Description
The password for the HTTP or FTP server if required.
Platforms
- Android
- Windows Mobile/CE
createFolders
Type
STRING
Description
On a filetransfer that results in local file storage, createFolders can automatically create the directory path. Value must be set to "True" if destination folder does not exist. See Remarks.
Possible Values
- True
- False
Platforms
- Android
- Windows Mobile/CE
overWrite
Type
STRING
Description
On a filetransfer that results in local file storage, OverWrite will overwrite the destination file if it already exists.
Possible Values
- True
- False
Platforms
- Android
- Windows Mobile/CE
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
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 dependent 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
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
CreateFolders
The CreateFolder method must be set to "True" if one or more destination folders are to be created to receive transferred file(s). Failure to do so could result in an incorrect "File Received" message.