FileTransfer Meta Tag

PocketBrowser 3.x API

The FileTransfer Meta Tag is an action tag used to send or receive files between the device filestore and an FTP or HTTP site.

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


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
Copy methods template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

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
Copy parameters template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

Modules return information back to their web pages via retrieval tags, for example the scanner has a retrieval tag called 'DecodeEvent' which is called whenever it decodes a barcode. To register to receive a retrieval tag call the module as follows:

<META HTTP-Equiv="[Module]" content="[RetrievalTag]:url('[URI]')">
So to register to retrieve the Scanner's DecodeEvent the following syntax would be used:
<META HTTP-Equiv="Scanner" content="DecodeEvent:url('Javascript:doScan('%6', '%s', %3, '%2');')">

Retrieval tags return information by replacing the text in place holders, defined as '%s' or '%<number>'. Each place holder represents 1 return value with '%s' being populated sequentially or '%<number>' providing direct acces to the desired value.

If the content for the Scanner's DecodeEvent is:

"url('Javascript:doScan('%6', '%s', %3, '%2');')"

The function would be called as follows:
"Javascript:doScan('Decode', '5449000053879', 0x35, 'SCN:EAN13');"


TransferEvent
The TransferEvent is called when the file has been successfully transfered to the specified destination. When the transfer is via the HTTP protocol 'OK: File Received' is returned followed by the size of the file; 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 relevent 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 Transfer Result Success or failure of the transfer, see note above.
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript



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">
Copy example to clipboard Copy example to clipboard

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">
Copy example to clipboard Copy example to clipboard

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">
var gen = new ActiveXObject("PocketBrowser.Generic");

//  HTTP Functions

//  Download from an HTTP site
function downloadFromHTTP()
{
gen.InvokeMETAFunction("FileTransfer", "Source:url('http://myserver/myfile.txt'); destination:url('file://\\myfile.txt'); Transfer");     
}

//  Download from an HTTP site requiring login credentials
function downloadFromHTTPAuth()
{
gen.InvokeMETAFunction("FileTransfer", "Source:url('http://httpAdmin:httpPassword@myserver/myfile.txt'); destination:url('file://\\myfile.txt'); Transfer");     
}
</script>
Copy example to clipboard Copy example to clipboard

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">
var gen = new ActiveXObject("PocketBrowser.Generic");

//  FTP Functions

//  Upload to an FTP server
function uploadToFTP()
{
gen.InvokeMETAFunction("FileTransfer", "Source:url('file://\\Program Files\\PocketBrowser\\file.txt'); destination:url('ftp://192.168.4.110/file.txt'); Transfer");     
}

//  Upload to an FTP server on port 2500 using username 'ftpadmin' and password 'ftpadminpw'
function uploadToFTPWithAuthentication()
{
gen.InvokeMETAFunction("FileTransfer", "Source:url('file://\\Program Files\\PocketBrowser\\file.txt'); destination:url('ftp://ftpadmin:ftpadminpw@192.168.4.110:2500/Folder/file.txt'); Transfer");     
}

//  Download from an FTP Server using username 'ftpadmin' and password 'ftpadminpw'   
function downloadFromFTP()
{
gen.InvokeMETAFunction("FileTransfer", "Source:url('ftp://ftpadmin:ftpadminpw@192.168.4.110/NewFolder/file.txt'); Destination:url('file://\\sigReceived.bmp'); Transfer");     
}
</script>
Copy example to clipboard Copy example to clipboard
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.

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/myPBapp/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 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 to transfer should be 4MB.

FTP Return Value
FTP does not supply a return code to indicate success, so PocketBrowser may report a successful transfer even though the file may not arrive or be sent


Supported Platforms Windows Mobile, Windows CE
Persistence Tag is page-specific
Min. Requirements None