BlackBerry Application Web Loader

Version 1.0 BlackBerry Application Web Loader Developer Guide

BlackBerry Application Web Loader Version 1.0 Last modified: 22 February 2006 Part number: SWD_X_JDE(EN)-024.000 Send us your comments on product documentation: https://www.blackberry.com/DocsFeedback. 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 295 Phillip Street Waterloo, ON N2L 3W8 Canada Published in Canada

Research In Motion UK Limited Centrum House, 36 Station Road Egham, Surrey TW20 9LF United Kingdom

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
Installing applications from a web page
BlackBerry Application Web Loader overview Install an application from a web page that uses the application web loader Enable the application web loader on a web server Determining the device model and software version number Retrieving the status of the application web loader BlackBerry Application Web Loader web page template

BlackBerry Application Web Loader overview

The BlackBerry Application Web Loader is a Microsoft ActiveX web-based application loader that third party application developers use to create web pages that enable users to install applications directly on a BlackBerry device. The application web loader provides access to the system resources on a users computer. When a user accesses a web page that uses the application web loader and accepts the permission prompt, the web page installs the application web loader on the users computer. The application web loader uses the .jad and .cod files stored on the web server to install an application on a BlackBerry device connected to the users computer. The application web loader supports .cod files only. To install a MIDlet, convert the .jar file to a .cod file. See the BlackBerry Application Developer Guide , Volume 1: Fundamentals for more information on compiling .java and .jar files into the .cod file format.
Note: The application web loader cannot be used to install applications from a web page to a third party manufactured or distributed BlackBerry Connect device.

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

Install an application from a web page that uses the application web loader
Make sure your computer meets the following system requirements: Microsoft Windows 2000, or Windows XP Microsoft Internet Explorer 5.0 or greater ActiveX version 8.0 or greater You also require a BlackBerry enabled device with a USB port. 1. Using a USB connection, connect a BlackBerry device to a computer running Microsoft Windows 2000 or Windows XP. 2. Access the web page using the Microsoft Internet Explorer on the computer. 3. Accept the installation of the application web loader on the computer.
Note: If the user connects to the internet from a non-local or non-intranet domain, the application web loader prompts the user for a user name and password.

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 users computer has a USB driver. If a USB driver is not available, the application web loader instructs the user to install the driver.

Enable the application web loader on a web server

To enable the application web loader on a web page, use any scripting language that works with Internet Explorer and ActiveX. 1. Create a web page. 2. Set up the application .jad file. 3. Transfer the .cab, .jad, and .cod files to a web server. 4. Reference a specific version of the application web loader. 5. Send the BlackBerry device password to the application web loader. 6. Associate the application web loader with an application. For a template of a web page that uses the application web loader, see See BlackBerry Application Web Loader web page template on page 14 for more information.

Installing applications from a web page

.jad .cod

.jad .cod

Create/obtain the application .jad and .cod files.

Place the application .jad and .cod files on the web server that hosts the web page.

Download and install the application web loader on the web server.

.jad

Specify the application web loader version on the web page.

Associate the application web loader with the application .jad file.

Request and send the user device password to the application web loader.

BlackBerry Application Web Loader - Enabling application download from a web page

Set up the application .jad file

Verify that the .jad file for your application references no more than 12 .cod files. If an application .jad file references more than 12 .cod files, the application web loader will be unable to install the application on a BlackBerry device. See the BlackBerry Application Developer Guide, Volume 1: Fundamentals for more information on .jad and .cod files.

Transfer the .cab, .jad, and .cod files to a web server

The .jad and .cod files contain information that the application web loader requires to install an application. 1. Place the AxLoader.cab file in the same directory as the web page .html files.
Note: To place the AxLoader.cab file in a different location, update the <object> element URL information in the .html file to the new location.

2. To enable the application web loader to access the application files, place the application .jad file and .cod files on a web server.

BlackBerry Application Web Loader Developer Guide

Reference a specific version of the application web loader

For the application web loader to install an application on a BlackBerry device, the application web loader on the users computer must be the same version as the application web loader your web page code uses to install the application. If the versions are not the same and the web page begins to install an application on a BlackBerry device, the web page might try to use a method or property that does not exist in the users version of the application web loader. Application installation might fail and users might be unable to install an application from the web page. When you include web page code that specifies an application web loader version number, the Internet Explorer browser uses the version number to determine if the application web loader on a users computer is the same as the version the web page uses. If the versions are not the same, the Internet Explorer will install the version you specify in the OBJECT ID element on the users computer. If the versions are the same, the application web loader proceeds with installing the application on the BlackBerry device. To install a specific version of the application web loader on the users computer, specify the version number using the CODEBASE element within the OBJECT ID tags. The following sample code specifies that the application web loader, version 1.0.0.11, be installed on a users computer:
<OBJECT ID="AxLoader" CLASSID="CLSID:4788DE08-3552-49EA-AC8C-233DA52523B9" CODEBASE='AxLoader.cab#version=1,0,0,11'> </OBJECT>

Send the BlackBerry device password to the application web loader

To install an application on a BlackBerry device with a password set, the device password is required. To determine if a password is set on a BlackBerry device, use the AxLoader.state property. If this property returns a numeric value of 2, the application web loader will require the device password.
if (AxLoader.state == 2) { // The BlackBerry Application Web Loader requires a device password }

If a password is set on the BlackBerry device, use the AxLoaderPassword control to obtain the device password from the user. In your web page code, reference the AxLoaderPassword control in the OBJECT ID tag as follows:
<OBJECT ID="AxLoaderPassword" CLASSID="CLSID:4788DE0A-3552-49EA-AC8C-233DA52523B9"> </OBJECT> Note: The AxLoaderPassword control is included in the AxLoader.cab file.

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'; //Give the AxLoaderPassword object focus AxLoaderPassword.focus();

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); }

Associate the application web loader with an application

Invoke the application web loader loadJad() method to load a .jad file. Use a string parameter that represents one of the following:
.jad file location same location as the AxLoader.cab file different location than the AxLoader.cab file Parameter the .jad filename the relative location address of the .jad file

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 Install multiple applications at once. Procedure 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.

Enabling application upgrades

To use the application web loader to enable users to upgrade to newer versions of your application, make sure the .cod file name of the upgrade version and the older version are the same. If the .cod file names are different, the application web loader installs the upgrade version in addition to the older version; users might have multiple versions of an application.
11

BlackBerry Application Web Loader Developer Guide

Determining the device model and software version number

You might need to know the device model if an application can only be installed on certain BlackBerry devices. You might need to know the device software version number if an application requires a specific version of the device software.

Determine the BlackBerry device model

In your web page code, use the AxLoader.hwid property.
//Load the helloworld.jad file if the hardware id equals 0x04000000. function loadFiles() { var hwid = AxLoader.hwid; if ((hwid & 0x04000000) == 0x04000000) { AxLoader.loadJad("helloworld.jad"); } else { AxLoader.load("helloworld_mono.jad"); } } Device model BlackBerry 5700 Series of wireless handhelds BlackBerry 5800 Series of wireless handhelds BlackBerry 6210 Wireless Handheld BlackBerry 6220 Wireless Handheld BlackBerry 6230 Wireless Handheld BlackBerry 6280 Wireless Handheld BlackBerry 6500 Series of wireless handhelds BlackBerry 6700 Series of wireless handhelds BlackBerry 6750 Wireless Handheld BlackBerry 6750 Wireless Handheld BlackBerry 7100 Series BlackBerry 7100 Series BlackBerry 7100 Series BlackBerry 7200 Series of wireless handhelds BlackBerry 7200 Series of wireless handhelds BlackBerry 7200 Series of wireless handhelds BlackBerry 7290 Wireless Handheld BlackBerry 7510 Wireless Handheld BlackBerry 7520 Wireless Handheld BlackBerry 7700 Series of wireless handhelds BlackBerry 7700 Series of wireless handhelds BlackBerry 8700 Series of wireless handhelds BlackBerry Smart Card Reader 0x00000505 0x80000403 0x00000104 0x00000404 0x94000903 0x04000905 0x04000904 0x94000503 0x1c000504 0x1c000506 0x9c000503 0x04000505 0x1c000505 0x94000403 0x04000404 0x84000b03 0x00000C08 iDEN devices GPRS devices CDMA devices CDMA devices with GPS support color GPRS device iDEN devices color CDMA devices color GPRS devices color CDMA devices color 802.11b devices color GPRS device iDEN device iDEN device color GPRS devices color CDMA devices color GPRS device 0x90000503 GPRS devices Hardware ID 0x00000101 0x80000103 0x80000503 Description MOBITEX devices GPRS devices GPRS devices

12

Installing applications from a web page

Determine the BlackBerry device software version number

Use the AxLoader.version property. The following example uses this property to test whether an application supports the BlackBerry device software.
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 this link to load the Hello World Application to the connected BlackBerry."); break; }

Retrieving the status of the application web loader

> To manage and control the application web loader throughout the application installation process, use the AxLoader.state property.
Description cannot find USB drivers on the BlackBerry device cannot detect the BlackBerry device a user password is required successfully connected to a BlackBerry device loading an application on the BlackBerry device 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 Value 0 1 2 3 4 5

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

// Prompt the user for the device password

BlackBerry Application Web Loader web page template

The following code sample uses HTML and JScript to demonstrate how to create a web page that uses the application web loader.
Example: BlackBerry Application Web Loader sample code
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML><HEAD><TITLE>Loader page for Hello World Application</TITLE></HEAD> <body bgcolor="#FFFFFF" lang=EN-CA link=blue vlink=navy alink="#FF0000" onload="update();"> <p><h1>Hello World Application</h1></p> <p> Hello World Application description. </p> <hr> <center> <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;paddingtop: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 align='center' style='border=2px solid gray'> <br/> <b><h1>Hello World Application</h1></b> <h2 id='title'></h2> <div id='message' align='center'> <br/> </div> <br/> <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

<OBJECT ID="AxLoaderPassword" CLASSID="CLSID:4788DE0A-3552-49EA-AC8C233DA52523B9"></OBJECT> <br/><br/> <a class='bd' onmousedown="providePassword()" onkeydown="if(window.event.keyCode==13){providePassword();}">Enter</a> </div> <div id='load' align='center' style="display:none"> <strong>Note:&nbsp;</strong>Your BlackBerry device might reset after loading.<br/> <br/> <a class='bd' onmousedown="loadFiles()" onkeydown="if(window.event.keyCode==13){loadFiles();}">Load</a> </div> <div id='progress' align='center' style="display='none'"> <span id='progress_bar' style='background-color:#6897C6;width=0;height=10;fontsize=9px;color=white;text-align=center'>0%</span> </div> </div> <br/> <a class='bd' id='retry' style="display:none" onmousedown="releaseHold()" onkeydown="if(window.event.keyCode==13){releaseHold();}">Again</a> <br/> </div> <div style="display:block" id="debugInfo"/> <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); } function show(section, titletext, html) { var count = sections.children.length; for (i=0; i<count; i++) { element = sections.children(i); if (element.id == section) {
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; var state = AxLoader.state; if ("" + state == "undefined") { show('message', 'Unable to create the loader Active X Control', "Please review your security settings and user priviledges on this machine."); return; } 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

show('progress', 'Loading', ""); retry.style.display = 'none'; break; case 5:// An error occurred while connecting to or installing on a BlackBerry device var remedy = "An unspecified error has occurred."; switch(AxLoader.error) { case 1: // ERROR_UNABLE_TO_CONNECT remedy = "Unable to Connect to device. Close any other BlackBerry applications that are running, for example, the BlackBerry Desktop Software. Try again."; break; case 2: // ERROR_DEVICE_IS_FULL remedy = "The device is full. Remove some data and try again."; break; case 3: // ERROR_UNABLE_TO_DOWNLOAD remedy = "Error downloading file. Check your Internet connection and try again."; break; case 4: // ERROR_UNABLE_TO_CREATE_LOCAL_COPY remedy = "Unable to create a local copy of files. Verify that space is available for temporary files on your computer."; break; case 5: // ERROR_INVALID_FILE rememdy = "Attempt to load an invalid file. Try again."; break; case 6: // ERROR_LOAD_FAILED remedy = "Error loading file. Try again."; break; case 7: // ERROR_OUT_OF_MEMORY remedy = "Out of Memory. Close some applications and try again."; break; } show('message', 'Error', remedy); retry.style.display = 'block'; break; case 6:// The BlackBerry Application Web Loader successfully installed an application on a BlackBerry device. show('message', 'Done', "Hello World Application has been loaded."); retry.style.display = 'block'; break; } } 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.