Blackberry Application Web Loader Developer Guide
Blackberry Application Web Loader Developer Guide
Version 1.0
©2006 Research In Motion Limited. All Rights Reserved. The BlackBerry and RIM families of related marks, images, and symbols are the
exclusive properties of Research In Motion Limited. RIM, Research In Motion, “Always On, Always Connected”, the “envelope in motion”
symbol, BlackBerry, and BlackBerry Enterprise Server are registered with the U.S. Patent and Trademark Office and may be pending or
registered in other countries.
Microsoft, ActiveX, JScript, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or
other countries. iDEN is a registered trademark of Motorola, Inc. countries. All other brands, product names, company names, trademarks, and
service marks are the properties of their respective owners. The BlackBerry device and/or associated software are protected by copyright,
international treaties and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470;
6,073,318; D445,428; D433,460; D416,256. Other patents are registered or pending in various countries around the world. Visit
www.rim.com/patents.shtml for a list of RIM [as hereinafter defined] patents.
This document is provided “as is” and Research In Motion Limited and its affiliated companies (“RIM”) assume no responsibility for any
typographical, technical or other inaccuracies in this document. RIM reserves the right to periodically change information that is contained in
this document; however, RIM makes no commitment to provide any such changes, updates, enhancements or other additions to this document
to you in a timely manner or at all. RIM MAKES NO REPRESENTATIONS, WARRANTIES, CONDITIONS OR COVENANTS, EITHER EXPRESS OR
IMPLIED (INCLUDING WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED WARRANTIES OR CONDITIONS OF FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, MERCHANTABILITY, DURABILITY, TITLE, OR RELATED TO THE PERFORMANCE OR NON-PERFORMANCE OF
ANY SOFTWARE REFERENCED HEREIN OR PERFORMANCE OF ANY SERVICES REFERENCED HEREIN). IN CONNECTION WITH YOUR USE OF
THIS DOCUMENTATION, NEITHER RIM NOR ITS RESPECTIVE DIRECTORS, OFFICERS, EMPLOYEES OR CONSULTANTS SHALL BE LIABLE TO
YOU FOR ANY DAMAGES WHATSOEVER BE THEY DIRECT, ECONOMIC, COMMERCIAL, SPECIAL, CONSEQUENTIAL, INCIDENTAL,
EXEMPLARY OR INDIRECT DAMAGES, EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, INCLUDING WITHOUT
LIMITATION, LOSS OF BUSINESS REVENUE OR EARNINGS, LOST DATA, DAMAGES CAUSED BY DELAYS, LOST PROFITS, OR A FAILURE TO
REALIZE EXPECTED SAVINGS.
This document might contain references to third party sources of information, hardware or software, products or services and/or third party
web sites (collectively the “Third-Party Information”). RIM does not control, and is not responsible for, any Third-Party Information, including,
without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any
other aspect of Third-Party Information. The inclusion of Third-Party Information in this document does not imply endorsement by RIM of the
Third Party Information or the third party in any way. Installation and use of Third Party Information with RIM's products and services may
require one or more patent, trademark or copyright licenses in order to avoid infringement of the intellectual property rights of others. Any
dealings with Third Party Information, including, without limitation, compliance with applicable licenses and terms and conditions, are solely
between you and the third party. You are solely responsible for determining whether such third party licenses are required and are responsible
for acquiring any such licenses relating to Third Party Information. To the extent that such intellectual property licenses may be required, RIM
expressly recommends that you do not install or use Third Party Information until all such applicable licenses have been acquired by you or on
your behalf. Your use of Third Party Information shall be governed by and subject to you agreeing to the terms of the Third Party Information
licenses. Any Third Party Information that is provided with RIM's products and services is provided "as is". RIM makes no representation,
warranty or guarantee whatsoever in relation to the Third Party Information and RIM assumes no liability whatsoever in relation to the Third
Party Information even if RIM has been advised of the possibility of such damages or can anticipate such damages.
Research In Motion Limited Research In Motion UK Limited
295 Phillip Street Centrum House, 36 Station Road
Waterloo, ON N2L 3W8 Egham, Surrey TW20 9LF
Canada United Kingdom
Published in Canada
Contents
1 Installing applications from a web page ........................................................................................................... 7
BlackBerry Application Web Loader overview ........................................................................................................ 7
Install an application from a web page that uses the application web loader ........................................... 8
Enable the application web loader on a web server............................................................................................. 8
Set up the application .jad file............................................................................................................................. 9
Transfer the .cab, .jad, and .cod files to a web server................................................................................... 9
Reference a specific version of the application web loader.....................................................................10
Send the BlackBerry device password to the application web loader ..................................................10
Associate the application web loader with an application ......................................................................11
Enabling application upgrades..........................................................................................................................11
Determining the device model and software version number ........................................................................12
Determine the BlackBerry device model ........................................................................................................12
Determine the BlackBerry device software version number ....................................................................13
Retrieving the status of the application web loader ..........................................................................................13
BlackBerry Application Web Loader web page template..................................................................................14
1
To view a web page code sample that uses the BlackBerry Application Web Loader, on the taskbar, click Start >
Programs > Research In Motion > BlackBerry Application Web Loader 1.0 > BlackBerry Application Web
Loader Sample.
To access the BlackBerry Application Web Loader Release Notes, on the taskbar, click Start > Programs >
Research In Motion > BlackBerry Application Web Loader 1.0 > Release Notes.
To uninstall the BlackBerry Application Web Loader, on the taskbar, click Start > Programs > Research In
Motion > BlackBerry Application Web Loader 1.0 > Uninstall BlackBerry Application Web Loader.
BlackBerry Application Web Loader Developer Guide
Once installed, the application web loader communicates with the BlackBerry device connected to the computer
and downloads to the device the required .cod files from the web server that hosts the application web loader.
Users do not require the BlackBerry Desktop software to download and install the .cod files.
Note: The user requires a USB driver on the computer. When the application web loader connects to a BlackBerry device, the application
web loader determines if the user’s computer has a USB driver. If a USB driver is not available, the application web loader instructs the
user to install the driver.
8
Installing applications from a web page
.jad
BlackBerry Application Web Loader - Enabling application download from a web page
2. To enable the application web loader to access the application files, place the application .jad file and .cod
files on a web server.
9
BlackBerry Application Web Loader Developer Guide
Use the AxLoaderPassword control to display a password dialog box to the user and store the device password.
//Prompt the user for the device password
show('password', 'Connected', "Enter the BlackBerry Password to continue.<br/>(" +
AxLoader.passwordRetries + ") attempts remaining.");
retry.style.display = 'none';
10
Installing applications from a web page
Create code that sends the device password to the application web loader when the user presses the Enter key.
//Listen for the user to press the Enter key
function AxLoaderPassword::onEnter() {
providePassword();
}
Create code that invokes the AxLoader object submitPassword() method using the AxLoaderPassword object
as a parameter. The AxLoader object obtains the password from the AxLoaderPassword object from shared
memory (both controls are loaded in the same process). The application web loader uses the device password to
access and install an application on the BlackBerry device.
//Submit the device password the user entered
function providePassword() {
AxLoader.submitPassword(AxLoaderPassword);
}
AxLoader.loadJad("helloworld.jad");
Your web page code should only call the loadJad() method once. Calling the loadJad() method might cause
the BlackBerry device to reset.
If you want to use the application web loader to install multiple applications, perform one of the following
actions:
Action Procedure
Install multiple applications at once. 1. On the same web page, list the information for all the applications in the same .jad
file.
2. Associate the .jad file with the application web loader.
Install one application at a time. 1. Set up a web page for each application.
2. Enable the application web loader on each web page.
3. On each web page, associate the .jad file for an application with the application web
loader.
11
BlackBerry Application Web Loader Developer Guide
12
Installing applications from a web page
Value Description
0 cannot find USB drivers on the BlackBerry device
1 cannot detect the BlackBerry device
2 a user password is required
3 successfully connected to a BlackBerry device
4 loading an application on the BlackBerry device
5 an error occurred while connecting to a BlackBerry device or loading an application:
1 - ERROR_UNABLE_TO_CONNECT
2 - ERROR_DEVICE_IS_FULL
3 - ERROR_UNABLE_TO_DOWNLOAD
4 - ERROR_UNABLE_TO_CREATE_LOCAL_COPY
5 - ERROR_INVALID_FILE
6 - ERROR_LOAD_FAILED
7 - ERROR_OUT_OF_MEMORY
6 successfully installed an application on a BlackBerry device
Create code that performs actions based on the status of the application web loader:
switch(AxLoader.state) {
case 0:
// The BlackBerry Application Web Loader cannot find USB drivers on the BlackBerry device
// Tell the user to obtain USB drivers
case 1:
// The BlackBerry Application Web Loader does not detect the BlackBerry device.
// Inform the user that the application web loader cannot find the BlackBerry device
case 2:
// The BlackBerry Application Web Loader requires a device password
13
BlackBerry Application Web Loader Developer Guide
<div>
<style>
TABLE {margin-left:1.5em; font:x-small 'Tahoma'; margin-right:1.5em; align:center}
TD {vertical-align:center; align:center; font-weight:bold}
TR {padding:0}
BODY {font:x-small 'Tahoma'; margin-right:1.5em; color:#000099}
H2 {text-size:large; color:#000099}
.bd {border:2px solid gray;padding-left:5px;padding-right:5px;padding-
top:2px;padding-bottom:2px;cursor:hand}
</style>
<!-- Use this element to specify the required version of the BlackBerry Application Web
Loader -->
<OBJECT ID="AxLoader"
CLASSID="CLSID:4788DE08-3552-49EA-AC8C-233DA52523B9"
CODEBASE='AxLoader.cab#version=1,0,0,11'>
</OBJECT>
<div id='sections'>
<div id='password' align='center' style="display:'none'">
<!-- Use this element to provide a user password to the BlackBerry Application Web
Loader. The web page does not handle the password directly. -->
14
Installing applications from a web page
</div>
<br/>
<a class='bd' id='retry' style="display:none" onmousedown="releaseHold()"
onkeydown="if(window.event.keyCode==13){releaseHold();}">Again</a>
<br/>
</div>
<script language=JScript>
function AxLoader::progressUpdate() {
progress_bar.innerText = AxLoader.progress.toString() + "%";
progress_bar.style.width = AxLoader.progress * 120 / 100;
}
function AxLoader::stateChanged() {
update();
}
function AxLoaderPassword::onEnter() {
providePassword();
}
function releaseHold() {
AxLoader.reset();
}
function providePassword() {
AxLoader.submitPassword(AxLoaderPassword);
}
15
BlackBerry Application Web Loader Developer Guide
element.style.display = 'block';}
else {
element.style.display = 'none';}
}
title.innerHTML = titletext;
message.innerHTML = html;
}
function update() {
debugInfo.innerText = AxLoader.debugInfo;
switch(AxLoader.state) {
case 0:// The BlackBerry Application Web Loader cannot find the BlackBerry USB driver.
show('message', 'No Driver', "The BlackBerry USB Driver is not installed.");
retry.style.display = 'none';
break;
case 1:// The BlackBerry Application Web Loader does not detect the BlackBerry device.
show('message', 'No BlackBerry Found', "To install the Hello World Application,
connect your BlackBerry to the USB port on this computer.");
retry.style.display = 'none';
break;
case 2:// The BlackBerry Application Web Loader requires a user password
show('password', 'Connected', "Type the BlackBerry device password to continue.<br/
>(" + AxLoader.passwordRetries + ") attempts remaining.");
retry.style.display = 'none';
AxLoaderPassword.focus();
break;
case 3:// The BlackBerry Application Web Loader successfully connected to a BlackBerry
device.
<!-- The BlackBerry Application Web Loader determines if supported BlackBerry device
software versions exist.-->
var version = AxLoader.version;
if (version.indexOf("3.6") != 0 &&
version.indexOf("3.7") != 0 &&
version.indexOf("3.8") != 0 &&
version.indexOf("4.0") != 0 &&
version.indexOf("4.1") != 0) {
show('load', 'Connected', "Click the link to install the Hello World Application on
your BlackBerry device.");
break;
}
show('load', 'Connected', "Click the link to install the Hello World Application on
the BlackBerry device(Version " + version + ").");
retry.style.display = 'none';
break;
case 4:// The BlackBerry Application Web Loader is installing an application on a
BlackBerry device
16
Installing applications from a web page
function loadFiles() {
<!-- Load the appropriate .jad file based on the hardware ID and version number-->
var hwid = AxLoader.hwid;
// loadJad accepts either a relative URL for the .jad file or the actual .jad file
contents as a string
// The BlackBerry Web Application Loader supports BlackBerry .jad files only.
Convert MIDlets to .cod files.
if ((hwid & 0x04000000) == 0x04000000) {
AxLoader.loadJad("helloworld.jad");
}
else {
AxLoader.load("helloworld_mono.jad");
}
}
</script>
17
BlackBerry Application Web Loader Developer Guide
</div>
</body>
</HTML>
18
©2006 Research In Motion Limited
Published in Canada.