Motorola C381P User Manual

Technical Manual

Motorola C381p Handset J2ME™ Developer Guide

Version 01.00

Table of Contents

TABLE OF CONTENTS ............................................................................................................................... 2

TABLE OF FIGURES.................................................................................................................................. 6

INDEX OF TABLES....................................................................................................................................7

TABLE OF CODE SAMPLES...................................................................................................................... 9

1 INTRODUCTION .................................................................................................................................... 10

PURPOSE.................................................................................................................................................... 10

AUDIENCE .................................................................................................................................................. 10

DISCLAIMER .............................................................................................................................................. 10

REFERENCES .............................................................................................................................................. 11

REVISION HISTORY .................................................................................................................................. 12

DEFINITIONS, ABBREVIATIONS, ACRONYMS........................................................................................... 12

DOCUMENT OVERVIEW ................................................................................................................................13

2 J2ME INTRODUCTION......................................................................................................................... 15

THE JAVA 2 PLATFORM, MICRO EDITION (J2ME).............................................................................. 15

THE MOTOROLA J2ME PLATFORM............................................................................................................. 16

MIDP 1.0 ............................................................................................................................................... 16

RESOURCES AND API’S AVAILABLE........................................................................................................ 17

3 DEVELOPING AND PACKAGING J2ME APPLICATIONS............................................................. 18

GUIDE TO DEVELOPMENT IN J2ME.......................................................................................................... 18

4 DOWNLOADING APPLICATIONS........................................................................................................ 20

METHOD OF DOWNLOADING......................................................................................................................... 20

ERROR LOGS.............................................................................................................................................. 21

OTA AND DOWNLOAD ................................................................................................................................. 22

5 APPLICATION MANAGEMENT............................................................................................................. 24

DOWNLOADING A JAR FILE WITHOUT A JAD.......................................................................................... 24

MIDLET UPGRADE ..................................................................................................................................... 24

INSTALLATION AND DELETION STATUS REPORTS.................................................................................... 25

SYSTEM MENU............................................................................................................................................ 25

6 JAD ATTRIBUTES................................................................................................................................27

JAD / MANIFEST ATTRIBUTE IMPLEMENTATIONS .................................................................................. 27

7 JAVA.LANG IMPLEMENTATION........................................................................................................ 29

Table of Contents

JAVA.LANG SUPPORT................................................................................................................................. 29

8 NETWORK APIS .................................................................................................................................... 30

NETWORK CONNECTIONS............................................................................................................................. 30

USER PERMISSION .................................................................................................................................... 32

HTTPS CONNECTION ................................................................................................................................32

9 JSR 135 MOBILE MEDIA API........................................................................................................ 35

JSR 135 MOBILE MEDIA API............................................................................................................... 35

TONECONTROL............................................................................................................................................ 36

GUICONTROL............................................................................................................................................. 37

VOLUMECONTROL ........................................................................................................................................37

STOPTIMECONTROL.................................................................................................................................... 38

MANAGER CLASS ........................................................................................................................................38

AUDIO MEDIA............................................................................................................................................ 38

10 JSR 120 – WIRELESS MESSAGING API .................................................................................. 41

WIRELESS MESSAGING API (WMA)........................................................................................................ 41

SMS CLIENT MODE AND SERVER MODE CONNECTION.............................................................................. 41

SMS PORT NUMBERS................................................................................................................................. 42

SMS MESSAGE TYPES............................................................................................................................... 43

SMS MESSAGE STRUCTURE ....................................................................................................................... 43

SMS NOTIFICATION ................................................................................................................................. 43

11 PHONEBOOK ACCESS API............................................................................................................... 49

PHONEBOOK ACCESS API ......................................................................................................................... 49

PHONEBOOK ACCESS API PERMISSIONS.................................................................................................. 49

12 TELEPHONY API................................................................................................................................54

DIALER CLASS.......................................................................................................................................... 54

CLASS DIALEREVENT................................................................................................................................54

CLASS DIALER.......................................................................................................................................... 56

getDefaultDialer........................................................................................................................ 57

setDialerListener ..................................................................................................................... 57

startCall ........................................................................................................................................ 58

sendExtNo ........................................................................................................................................ 58

endCall............................................................................................................................................. 59

INTERFACE DIALERLISTENER................................................................................................................... 59

SAMPLE DIALERLISTENER IMPLEMENTATION ........................................................................................... 59

notifyDialerEvent ..................................................................................................................... 61

CLASS HIERARCHY .................................................................................................................................... 61

INTERFACE HIERARCHY............................................................................................................................. 61

13 SERIAL PORT ACCESS.................................................................................................................... 62

14 SMS MESSAGING AS GSM EXTENSION ....................................................................................... 63

CREATING A MESSAGE............................................................................................................................... 63

SENDING A MESSAGE ................................................................................................................................63

VIEWING A MESSAGE ................................................................................................................................64

DELETING A MESSAGE............................................................................................................................... 64

15 USER DISPLAY INTERFACE .......................................................................................................... 65

Table of Contents

ANVAS FUNCTIONALITY........................................................................................................................... 65

HARDWARE MAPPING .................................................................................................................................. 67

16 ONE-CLICK APPLICATION ACCESS............................................................................................ 71

APPLICATION RESOURCES......................................................................................................................... 71

APPLICATION KEYS .................................................................................................................................. 71

APPLICATION ICONS ................................................................................................................................71

SOFTKEY LABELS ...................................................................................................................................... 72

EFFECT OF MASTER CLEAR OR MASTER RESET....................................................................................... 72

DELETING THE MIDLET/APPLICATION.................................................................................................... 72

17 DOWNLOAD MIDLET THROUGH BROWSER..................................................................................... 73

STAR ACTIVE BROWSER SESSION FROM MAIN MENU............................................................................... 74

FIND A LOCATION WITH J2ME APPLICATION ........................................................................................ 74

DOWNLOADING MIDLETS............................................................................................................................ 75

DIFFERENT ERROR CHECKS ...................................................................................................................... 77

Memory Full.................................................................................................................................... 77

Memory Full during installation process................................................................ 80

Application version already exists:........................................................................... 81

Newer Application Version Exists: ............................................................................... 82

18 LIGHTWEIGHT WINDOWING TOOLKIT.......................................................................................... 84

19 UDP SUPPORT .................................................................................................................................... 85

20 SHARED JAD URLS........................................................................................................................... 86

OVERVIEW .................................................................................................................................................. 86

TELL-A-FRIEND OPTION......................................................................................................................... 86

Accessing Tell-A-Friend from SMM.................................................................................. 87

Downloading through Browser.............................................................................................. 88

Downloading from PC (Via serial/USB)........................................................................ 88

Downloading through MMS....................................................................................................... 89

21 GET URL FROM FLEX API............................................................................................................. 90

OVERVIEW .................................................................................................................................................. 90

FLEXIBLE URL FOR DOWNLOADING FUNCTIONALITY................................................................................ 90

SECURITY POLICY .................................................................................................................................... 91

22 MULTIPLE KEY PRESS.................................................................................................................... 92

23 ITAP.....................................................................................................................................................94

INTELLIGENT KEYPAD TEXT ENTRY API................................................................................................ 94

24 LCDUI................................................................................................................................................... 95

LCDUI API............................................................................................................................................. 95

25 AUTO LAUNCH OF MIDLETS ........................................................................................................ 100

SCENARIOS INVOLVED IN LAUNCHING MIDLET....................................................................................... 100

26 BACKGROUND APPLICATIONS...................................................................................................... 101

BACKGROUND ATTRIBUTE......................................................................................................................... 101

BACKGROUND JAVA APPLICATION LIFECYCLE ....................................................................................... 101

BACKGROUND MIDLET.............................................................................................................................. 101

FLIP BEHAVIORS .................................................................................................................................... 102

Table of Contents

27 JAVA SYSTEM MENU....................................................................................................................... 103

MIDLET MANAGER MENU ......................................................................................................................... 103

View MIDlet Suite Information....................................................................................... 104

DELETING MIDLET SUITES.................................................................................................................... 104

28 INVISIBLE NET FOR J2ME ........................................................................................................ 107

INTRODUCTION ........................................................................................................................................ 107

J2ME INVISIBLE NET OPTIONS.......................................................................................................... 107

J2ME Component Options ....................................................................................................... 107

J2ME Context-Sensitive Menu Options......................................................................... 109

29 DOWNLOAD MIDLET THROUGH PC............................................................................................... 111

ESTABLISHING CONNECTION................................................................................................................... 111

30 OPERATOR APPS PROVISIONING............................................................................................... 112

31 MIDP 2.0 SECURITY MODEL...................................................................................................... 113

UNTRUSTED MIDLET SUITES.................................................................................................................. 114

UNTRUSTED DOMAIN ................................................................................................................................114

TRUSTED MIDLET SUITES ..................................................................................................................... 115

PERMISSION TYPES CONCERNING THE HANDSET .................................................................................... 115

USER PERMISSION INTERACTION MODE................................................................................................. 115

IMPLEMENTATION BASED ON RECOMMENDED SECURITY POLICY............................................................. 116

TRUSTED 3

PARTY DOMAIN.................................................................................................................. 116

TRUSTED MIDLET SUITES USING X.509 PKI................................................................................... 117

SIGNING A MIDLET SUITE.................................................................................................................... 117

SIGNER OF MIDLET SUITES.................................................................................................................. 118

MIDLET ATTRIBUTES USED IN SIGNING MIDLET SUITES.................................................................. 118

CREATING THE SIGNING CERTIFICATE ................................................................................................. 118

INSERTING CERTIFICATES INTO JAD .................................................................................................. 119

CREATING THE RSA SHA-1 SIGNATURE OF THE JAR ........................................................................ 119

AUTHENTICATING A MIDLET SUITE ...................................................................................................... 119

VERIFYING THE SIGNER CERTIFICATE ................................................................................................. 119

VERIFYING THE MIDLET SUITE JAR................................................................................................... 120

APPENDIX A: AUDIO MIX TABLE.................................................................................................... 122

APPENDIX B: KEY MAPPING............................................................................................................. 123

KEY MAPPING FOR THE C381P ............................................................................................................. 123

APPENDIX C: MEMORY MANAGEMENT CALCULATION.................................................................. 125

AVAILABLE MEMORY ................................................................................................................................125

APPENDIX D: FAQ................................................................................................................................126

ONLINE FAQ........................................................................................................................................... 126

APPENDIX E: HTTP RANGE ............................................................................................................... 127

GRAPHIC DESCRIPTION........................................................................................................................... 127

APPENDIX F: SPEC SHEET ............................................................................................................... 128

C381P SPEC SHEET .............................................................................................................................. 128

Table of Figures

Figure 1 Java Platform.........................................................................................15

Figure 2 Active Global Commands - Back, Cancel, OK, Help & Stop

........................................................................................................................................69

Figure 3 Active Global Commands - Cancel, Screen, OK, Help & Stop

........................................................................................................................................69

Figure 4 Starting Active Browser Session from Main Menu .................74

Figure 5 Downloading and Installing J2ME Application (MIDlets) ..75 Figure 6 Application does not have Mandatory Attributes in ADF ..77

Figure 7 Memory full error................................................................................79

Figure 8 Mot-Data-Space & Mot-Program-Space attributes are not

present or are incorretct ..................................................................................80

Figure 9 Memory Full help message during installation process.....81

Figure 10 Same Version of Application already exists on the

handset.........................................................................................................................82

Figure 11 Latest (Newer) Version of Application exists....................83

Figure 12 the MIDlet Manager and the context-sensitive menus.......88

Figure 13 Java service menu for a MIDlet with background

attributes.................................................................................................................102

Figure 14 Viewing MIDlet Suite Information............................................104

Figure 15 Deleting MIDlet Suites.................................................................105

Figure 16 Description of HTTP Range...........................................................127

Index of Tables

Table 1 Error Logs .................................................................................................22

Table 2 JAD file information............................................................................23

Table 3 Application management feature/class support for MIDP 2.0

........................................................................................................................................25

Table 4 Java System menu ....................................................................................26

Table 5 MIDlet Attributes, descriptions, and JAD and/or JAR

location.......................................................................................................................28

Table 6 Network API feature/class support for MIDP 2.0....................31

Table 7 Multimedia File formats .....................................................................38

Table 8 List of audio MIME types...................................................................39

Table 9 Multimedia feature/class support for JSR 135........................39

Table 10 Messaging features/classes supported.......................................44

Table 11 Interface Summary................................................................................54

Table 12 Class Summary.........................................................................................54

Table 13 Field Summary.........................................................................................55

Table 14 Constructor Summary............................................................................55

Table 15 Field Details.........................................................................................56

Table 16 Method Summary ......................................................................................57

Table 17 Key Ranking Priority..........................................................................68

Table 18 Performed on a suite..........................................................................87

Table 19 Gaming and keypad feature/class..................................................93

Table 20 ITAP feature/class..............................................................................94

Table 21 Interfaces supported by Motorola implementation ...............95

Table 22 Specific classes supported by Motorola implementation ..96

Table 23 LCDUI feature/class............................................................................99

Table 24 Function Describes..........................................................................103

Table 25 Midlet Manager Menu Description..............................................103

Index of Tables

Table 26 Security feature/class support for MIDP 2.0...................... 114

Table 27 Protected Functionality fot top line of prompt ...............117

Table 28 Dialog Prompts for MIDP 2.0 Permission Types....................117

Table 29 Actions performed upon completion of signer certificate

verification ............................................................................................................120

Table 30 MIDlet suite verification.............................................................121

Table 31 Audio Mix ...............................................................................................122

Table of Code Samples

Code Sample 1 Java.lang support .....................................................................29

Code Sample 2 Socket Connection .....................................................................32

Code Sample 3 HTTPS Connection .......................................................................34

Code Sample 4 JSR 135 Mobile Media API ......................................................36

Code Sample 5 JSR 120 Wireless Messaging API .........................................48

Code Sample 6 Phonebook API..............................................................................53

Code Sample 7 DialerListener Implementation ...........................................60

1 Introduction

Purpose

Introduction

This document describes the applicat ion program interfaces used to develop Motorola compliant Java™ 2 Platform, Micro Edition (J2ME™) applications for the C381p handset.

Audience

This document is intended for premium J2ME developers and specific carriers involved with the development of J2ME applications for the C381p handset.

Disclaimer

Motorola reserves the right to make changes without notice to any products or services described herein. “Typical” parameters, which may be provided in Motorola Data sheets and/or specifications can and do vary in different a pplications and actual performance may vary. Customer’s technical experts will validate all “Typicals” for each customer application.

Motorola makes no warranty with regard to the products or services contained herein. Implied warranties, including without limitation, the implied warranties of merchantability and fitness for a particular purpose, are given only if specifically required by applicable law. Otherwise, they are specifically excluded.

No warranty is made as to coverage, availability, or grade of service provided by the products or services, whether through a service provider or otherwise.

No warranty is made that the software will meet your requir ements or will work in combination with any hardware or applications software products provided by third parties, that the operation of the software products will be uninterrupted or error free, or that all defects in the software products will be corrected.

In no event shall Motorola be liable, whether in contract or tort (including negligence), for any damages resulting form use of a product or service described herein, or for any indirect, incidental, special or consequential damages of any kind, or loss of revenue or profits, loss of business, loss of information or data, or othe r financial loss arising out of or

1 Introduction

in connection with the ability or inability to use the Products, to the full extent these damages may be disclaimed by law.

Some states and other jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, or limitation on t he length of an implied warranty, so the above limitations or exclusions may not apply to you.

This warranty gives you specific legal rights, and you ma y also have other rights, which vary from jurisdiction to jurisdiction.

Motorola products or services are not designed, i ntended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the Motorola product or service could create a situation where personal injury or death may occur.

Should the buyer purchase or use Motorola products or services for any such unintended or unauthorized application, buyer shall release, indemnify and hold Motorola and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that Motorola was negligent regarding the designing or manufacture of the product or service.

Motorola recommends that if you are not the sole author or creator of the graphics, video, or sound, you obtain sufficient license rights, including the rights under all patents, trademarks, trade names, copyrights, and other third party proprietary rights.

References

Reference Link

RFC 2068 http://ietf.org/rfc/rfc2068.txt SAR http://www.wapforum.org MIDP 2.0 http://java.sun.com/products/midp/ JSR 118 http://www.jcp.org JSR 120 http://www.jcp.org JSR 135 http://www.jcp.org Sun MIDP 2.0 SDK http://java.sun.com/products/midp/ TLS protocol version 1.0 http://www.ietf.org/rfc/rfc2246.txt SSL protocol version 3.0 http://home.netscape.com/eng/ssl3/draft302.txt GSM 03.38 standard http://www.etsi.org GSM 03.40 standard http://www.etsi.org RFC 2437 http://ietf.org/rfc/rfc2437.txt Sun J2ME http://java.sun.com/j2me/).

1 Introduction

Revision History

Version Date Name Reason

00.01 November 09, 2004 C.E.S.A.R. Initial Draft

Definitions, Abbreviations, Acronyms

Acronym

AMS Application Management Software API Application Program Interface. CLDC Connected Limited Device Configuration GPS Global Positioning System IDE Integrated Development Environment ITU International Telecommunication Union JAD Java Application Descriptor JAL Java Application Loader JAR Java Archive. Used by J2ME applications for compression and packaging. J2ME Java 2 Micro Edition JSR 120 Java Specification Request 120 defines a set of optional APIs that provides

JVM Java Virtual Machine KVM Kilo Virtual Machine LWT Lightweig ht Windowing Toolkit

Description

standard access to wireless communicatio n resources.

MIDP Mobile Information Device Profile MMA Multimedia API MT Mobile Terminated OEM Original Equip m ent Manufacturer OTA Over The Air RMS Record Management System

1 Introduction

RTOS Real Time Operating System SDK Software Development Kit SMS Short Message Service SMSC Short Messaging Service Center SU Subscribe Unit UI User Interface URI Unified Resource Identifier VM Virtual Machine WMA Wireless Messaging API

Document Overview

This developer’s guide is organized int o the following chapters and appendixes: Chapter 1 – Introduction: this chapter has general information about th is document,

including purpose, scope, references, and def initions. Chapter 2 – J2ME Introduction: this chapter describes the J2ME platform and the

available resources on the Motorola C381p handset. Chapter 3 – Developing and Packaging J2ME Applications: this chapter describes

important features to look for when selecting tools and emu lation environments. It also describes how to package a J2ME application, how to package a MIDlet, and generate JAR and JAD files properly.

Chapter 4 – Downloading Applications: this chapter describes the process for downloading applications.

Chapter 5 – Application Management: this chapter describes the lifecycle, installation/de-installation, and updatin g process for a MIDlet suite.

Chapter 6 – JAD Attributes: this chapter describes what attributes are supported. Chapter 7 – Java.lang Implementation: this chapter describes the java.lang

implementation.

Chapter 8 – Networking APIs: this chapter describes the Java Networking API. Chapter 9 – JSR 135 Mobile Media: this chapter describes image types and supported

formats. Chapter 10 – JSR 120 Wireless Messaging API: this chapter describes JSR 120

implementation. Chapter 11 -- Phonebook Access API: this chapter describes the Phonebook Access

API.

Chapter 12 – Telephony API: this chapter describes the Telephony API. Chapter 13 – Serial Port Access: this chapter describes the Serial Port Access.

1 Introduction

Chapter 14 – SMS Messaging as GSM Extension: this chapter describes the SMS Access API.

Chapter 15 – User Display Interface: this chapter describes the J2ME specific Canvas, Hardware Mapping and External Event Interaction functionality.

Chapter 16 – One-Click Application Access: this chapter describes the used Java applications via the soft keys, navigation keys or smart keys

Chapter 17 – Download MIDlet Through Browser: this chapter describes the performing any downloads on the hands et.

Chapter 18 – Lightweight Windowing Toolkit: this chapter describes the capabilities to include a component-level API through which developers can control the co i ntents and layout of their screens.

Chapter 19 – UDP Support: this chapter describes how to enable J2ME applications access to Generic UDP Transport Service.

Chapter 20 – Shared JAD URLS: this chapter describes briefly a new fea ture that allows users to share their downloaded J2ME ap plication URLs with others.

Chapter 21 – Get URL from Flex API: this chapter describes the way to access URL stored in FLEX by a java application.

Chapter 22 – File System Access API: this chapter describes the File System API. Chapter 23 – Multiple Key Press: this chapter describes the Multiple Key Press. Chapter 24 – ITAP: this chapter describes iTAP support. Chapter 25 – LCDUI: this chapter describes the LCDUI. Chapter 26 – Auto Launch of Midlet: this chapter describes the Auto Lanch of Mid let. Chapter 27 – Background Applications: this chapter describes the. Chapter 28 – Java System Menu: this chapter describes the Java System Menu. Chapter 29 – Invisible net for J2ME: this chapter describes the Invisible net for J2ME. Chapter 30 – Download MIDlet Through PC: this chapter describes the any downloads

on the handset. Chapter 31 – MIDP 2.0 Security Model: this chapter describes the MIDP 2.0 default

security model. Appendix A – Key Mapping: this appendix describes the key map ping of the Motorola

C381p handset, including the key name, key code, and game action of all Motorola keys.

Appendix B –

Memory Management Calculation: this appendix describes the memory

management calculations.

Appendix C – FAQ: this appendix provides a link to the dynamic online FAQ. Appendix D – HTTP Range: this appendix provides a graphic description of HTTP

Range. Appendix E – Spec Sheet: this appendix provide s the spec sheet for the Motorola C381p

handset.

2 J2ME Introduction

J2ME Introduction

The Motorola C381p handset includes the Java™ 2 Platform, Micro Edition, also known as the J2ME platform. The J2ME platform enables developers to easily create a variety of Java applications ranging from business ap plications to games. Prior to its inclusion, services or applications residing on small consumer devices like cell phones could not be upgraded or added to without significant effort. By implementing the J2ME platform on devices like the Motorola C381p handset, servic e providers, as well as customers, can easily add and remove applications allowing for quick and easy personalization of each device. This chapter of the guide presents a quick overview of the J2ME environment and the tools that can be used to develop applic ations for the Motorola C381p handset.

The Java 2 Platform, Micro Edition (J2ME)

The J2ME platform is a new, very small application environment. It is a framework for the deployment and use of Java technology in small devices such as cell phones and pagers. It includes a set of APIs and a virtual machine that is designed in a modular fashion allowing for scalability among a wide range of devices.

The J2ME architecture contains three layers cons isting of the Java Virtual Machine, a Configuration Layer, and a Profile Layer. Th e Virtual Machine (VM) supports the Configuration Layer by providing an interface to the host operating system. Above the VM is the Configuration Layer, which can be thought of as the lowest common denominator of the Java Platform available across devices of the same “horizontal market.” Built upon this Configuration Layer is the Profile Layer, typically encompassing the presentation layer of the Java Platform.

Native

MIDP-Compliant

Apps

MIDP

CLDC

CLDC Native System Software

Native System Software

OEM

OEM Apps

Apps

OEM

OEM Classes

Classes

Native Apps

Apps

Mobile Information Device

Figure 1 Java Platform

2 J2ME Introduction

The Configuration Layer used in the Motorola C381p handset is the Connected Limited Device Configuration 1.1 (CLDC 1.1) and th e Profile Layer used is the Mobile Information Device Profile 2.0 (MIDP 2.0). Together, the CLDC and MIDP provide common APIs for I/O, simple math functionality, UI, and more.

For more information on J2ME, see the Sun™ J2ME documentation (http://java.sun.com/j2me/).

The Motorola J2ME Platform

Functionality not covered by the CLDC and MIDP APIs is left for individual OEMs to implement and support. By adding to the standard APIs, manufacturers can allow developers to access and take advantage of the unique functionality of their handsets. The Motorola C381p handset contains OEM APIs for extended functionality ranging from enhanced UI to advanced data security. While the Motorola C381p handset can run any application written in standard MIDP, it can also run applications that take advantage of the unique functionality provided by these APIs. These OEM APIs are described in this guide.

MIDP 1.0

J2ME is the version of Java that the mobile device will support. It was developed to support devices with limited memory, i.e mobile devices, pagers, SIM cards. J2ME maintains the qualities that Java technology has become famous for:

• built-in consistency across products in terms of running anywhere, any time, over any device

• portability of the code

• leveraging of the same Java programming langua ge

• safe network delivery

• applications written with J2ME are upwardly scalable to work with J2SE and

J2EE.

J2ME enables device manufacturers, service providers, and content creators to deploy compelling new applications and servic es to their customers rapidly and cost-effectively while capitalizing on new revenue streams. In using J2ME, the handset must be MIDP 1.0 and CLDC 1.0 compliant. To assure this compliance, the handset must pass the Technology Certification K it, TCK, provided by Sun.

2 J2ME Introduction

Resources and API’s Available

MIDP 2.0 will provide support to the following functional areas on the Motorola C381p handset:

MIDP 2.0

• Application delivery and billing

• Application lifecycle

• Application signing model and privileged security model

• End-to-end transactional security (HTTPS)

• Networking

• Persistent storage

• Sounds

• Timers

• User Interface

• File Image Support (.PNG, .JPEG, .GIF)

Additional Functionality

• WMA (JSR 120)

• MMA (JSR 135)

• Phonebook API

• Telephony API

3 Developing and Packaging J2ME Applications

Developing and Packaging

J2ME Applications

Guide to Development in J2ME

Introduction to Development

This appendix assumes the reader has previous experience in J2ME development and can appreciate the development process for Java MIDlets. This appendix will provide some information that a beginner in devel op m ent can use to gain an understanding of MIDlets for J2ME handsets.

There is a wealth of material on this subject on websites maintained by Motorola, Sun Microsystems and others. Please refer to the following URLs for more information:

 http://www.motocoder.com

http://www.java.sun.com/j2me



http://www.corej2me.com/



http://www.javaworld.com/



As an introduction, brief details of J2ME are explaine d below.

The MIDlet will consist of two core specifications, namely Connected, Limited Device Configuration (CLDC) and Mobile Informat ion Device Profile (MIDP). Both of these specifications (Java Specification Reque s ts) can be located at the reading.

 For MIDP 1.0; JSR 37 should be reviewed.  For MIDP 2.0; JSR 118 should be reviewed.  For CLDC 1.0.4; JSR 30 should be reviewed.

http://www.jcp.org/ site for

 For CLDC 1.1; JSR 139 should be reviewed.

To determine what implementation is on Motorola handset, review the “Jav a System” details through the menu on the Motorola handset (located under Java Settings).

For beginning development, key points to remember are memory size, processing power, screen capabilities and wireless networ k characteristics. These all play an important part

3 Developing and Packaging J2ME Applications

in development of a MIDlet. The specifications listed above are designed to work upon devices that have these characteristics.

Network conditions would only apply for n etworked applications such as streaming tick ers, email clients, etc.

In addition to the specifications, an array of tools is available to assist the development cycle. These range from the command line tools provided with Software Development Kits (SDK) from Sun (as of writing 1.4.1_04) to Integrated Develo pment Environments (IDEs) which can be free or purchased. These IDEs come from a range of sources such as Sun, IBM, Metrowerks and Borland to name a few.

For a look at such environments, review the “M otorola T720 Handset Developer Guide” which is available from the MOTOCODER website.

In addition to the IDEs and Sun SDK for development, Motorola offers access to our own SDK which contains Motorola device emulators. From here, a MIDlet can be built and then deployed onto an emulated target handset. This will enable debugging and validation of the MIDlet before deployment to a real, physical hands et. The latest Motorola SDK can be downloaded from the MOTOCODER website.

Please refer to the product specifications at the back of this guide for detailed information on each handset.

4 Downloading Applications

Downloading Applications

Method of Downloading

The option open to the developer for deploying the MIDlet to a physical Motorola device is OTA (over -the-air) downloading.

OTA

To use the OTA method, the developer will have a connection through a wireless network to a content server. This content server could be, for example, Apache

(http://httpd.apache.org) which is free to use, deployable on multiple operating systems,

and has extensive documentatio n on how to configure the platform.

The required file will be downloaded (eith er .jad and/or .jar) by issuing a direct URL request to the file in question or it could be a URL r equest to a WAP page and a hyperlink on that page to the target file. This request will be made through the OPERA Browser. In MIDP 2.0, the need for a JAD file before download is not required, so the JAR file can be downloaded directly. The information about the MI Dlet will be pulled from the manifest file.

The transport mechanism used to download the file will be one of two depending on the support from the network operators WAP Gateway and the size of file requested.

 HTTP Range – see specification RFC 2068 at http://www.rfc-editor.org/rfc.html

content greater than 30k in size. Below is a ladder diagram showing the flow through HTTP range transfer, although recall use of the .JA D is optional.

 SAR (Segmentation & Reassembly) – see specification of wireless transaction

protocol at the http://www.wapforum.org

During a download of the application, the use r will see the OPERA browser displaying a progress dialog.

A complete guide for setting up an OTA server can be obtained through the MOTOCODER website (http://www.motocoder.com the server and also example WAP pages.

The following error codes are supported:

 900 Success  901 Insufficient Memory  902 User Cancelled  903 Loss Of Service

if less than 100k in size.

). This includes details of configuring

4 Downloading Applications

 904 JAR Size Mismatch  905 Attribute Mismatch  906 Invalid Descriptor  907 Invalid JAR  908 Incompatible Configuration or Profile  909 Application Authentication Failur e  910 Application Authorization Failure  911 Push Registration Failure  912 Deletion Notification  913 Required package not supporte d by device  999 Other errors

Please be aware that the method used by the handset, as per the specifications, is POST. Using a GET (URL encoding) style for the URL will fail. This is not the correct use of the MIDlets JAD parameters.

Possible Screen Messages Seen With Downloading:

 If JAR -file size does not match with specified size, it will display a dialog stating

 When downloading is done, the handset displays a transient notice “Download

 Upon completing installation, the handset displays a dialog “Install complete”. To

 If the MANIFEST file is wrong, the handset displays a dialog stating “Installation

 If JAD does not contain mandatory attributes, “Installation failed. Package

“Installation failed. Package in valid.” To dismiss this dialog, press “O K”.

Completed” and starts to install the application.

dismiss this dialog, press “OK”.

failed. Package invalid.” To dismiss this dialog, press “OK”.

invalid.” notice appears.

Error Logs

The Table 1 represents the error logs associ ated with downloading applications.

Error Logs Scenario Possible Cause Error Dialog

906 Invalid Descriptor.

904 JAR Size OTA JAR The received JAR size does not Download Failed

JAD Download Missing or incorrectly formatted

mandatory JAD attributes Mandatory: MIDlet-Name (up to 32 symbols) MIDlet-Version MIDlet-Vendor (up to 32 symbols) MIDlet-JAR-URL (up to 256 symbols) MIDlet-JAR_Size JAD signature verification failed Unknown error during JAD validation

Failed: Invalid File

4 Downloading Applications

Mismatch . Download match the size indicated in JAD 902 User Cancelled. 903 Loss of Service. 901 Insufficient Memory. 905 Attribute Mismatch 901 Insufficient Memory.

OTA JAR

User cancelled download Cancelled: Download OTA JAR

Browser lost connection with server Installation Failed Download OTA JAR Download

Insufficient space to install the

MIDlet suite Installation Mandatory attributes are not identical

in JAD & Manifest Installation Insufficient Space to install MIDlet

suite

907 Invalid JAR. Installation Class references non-existent class

or method

Security Certificate verification failure

Checksum of JAR file is not equal to

Checksum in MIDlet-JAR-SHA

attribute

Application not authorized

MIDlet

Launching

MIDlet

Execution

Security Certificates expired or

removed

Authorization failure during MIDlet

execution

Incorrect MIDlet

Table 1 Error Logs

Insufficient Storage Installation failed.

Package invalid. Insufficient Storage

Installation failed. Package invalid.

Application Expired Application Error

OTA and Download

• Comply with “OTA User Initiated Provisioning Specifications” in MIDP 2.0.

• The user MUST be prompted if the midlet is char geable.

• Terminals should compare and predict the application program that will be

downloaded is

• the latest or old versions and give indicatio n to users.

• Check the available memory before any downloads.

• Users should be able to terminate the download process any time by pressing

END key.

• Before downloading the following JAD file information must be displayed first:

Contents Maximum

Application program name (Midlet name) 32 Bytes Max Application program version number 16 Bytes Max Vendor Name 32 Bytes Max

length

4 Downloading Applications

• End user should be able to delete the appl ications downloaded.

URL of JAR file Not specified Size of JAR file 8 Bytes Max Applicable Terminal Type not specified Application program introduction (Midlet

512 Bytes Max description) Information Fee (Media price). 32 Bytes Max

Table 2 JAD file information

5 Application Management

Application Management

The following sections describe the application management scheme for the Motoro la C381p handset. This chapter will discuss the following

• Downloading a JAR without a JAD

• MIDlet upgrade

• Installation and Deletion Status Reports

• System Menu

Downloading a JAR file without a JAD

In Motorola’s MIDP 2.0 implementation, a JAR file can be downloaded without a JAD. In this case, the user clicks on a link for a JAR file, the file is downloaded, and a confirmation will be obtained before the installation begi ns. The information presented is obtained from the JAR manifest instead of the JAD.

MIDlet Upgrade

Rules from the JSR 118 will be followed to help determine if the data from an old MIDlet should be preserved during a MIDlet upgrade. When th ese rules cannot determine if the RMS should be preserved, the user will be given an option to preserve the data.

The following conditions are used to determine if data can be saved:

• If the cryptographic signer of the new MIDlet suite and the original MIDlet suite are identical, then the RMS record stores MUST be r etained and made available to the new MIDlet suite.

• If the URL of the new MIDlet suite is identical to the URL the original MIDlet suite was downloaded from, then the RMS MUST be retained and made available to the new MIDlet suite.

• If the above statements are false, then the dev ice MUST ask the user whether the data from the original MIDlet suite should be ret ained and made available to the new MIDlet suite.

5 Application Management

If the user decides to save the data from the current MIDlet, the d ata will be preserved during the upgrade and the data wil l be made available for the new application. In any case, an unsigned MIDlet will not be allowed to update a signed MIDlet.

Installation and Deletion Status Reports

The status (success or failure) of an installation, upgra de, or deletion of a MIDlet suite will be sent to the server according to the JSR 118 specification. If the status report cannot be sent, the MIDlet suite will still be enabled and the user will be allowed to use it. Upon successful deletion, the handset will send the status code 912 to the MIDlet-Delete-Notify URL. If this notification fails, the MIDlet suite will still be deleted. If this notification cannot be sent due to lack of network connectivity, the notification will be sent at the next available network connection.

Refer to the Table 3 for application management feature/class support for MIDP 2.0:

Feature/Class

Application upgrades performed directly through the AMS When removing a MIDlet suite, the user will be pr ompted to confirm the entire MIDlet suite will be removed Prompt for user approval when the user has chos en to download an application that is identical to, or an different version of an application currently in the handset Unauthorized MIDlets will not have access to any restricted function call AMS will check the JAD for security indicated every time a installation is initiated Application descriptor or MIDlet fails the security check, the AMS will prevent the installation of that application and notify the user that the MIDlet could not be installed Application descriptor and MIDlet pa ss the security check , the AMS will install the MIDlet an d grant it the permissions specified in the JAD A method for launching Java application that mainta ins the same look and feel as other features on the device will be provided User will be informed of download and installation w ith progress indicator and will be given an opportunity to cancel the process User will be prompted to launch the MIDlet after installation A no forward policy on DRM issues, included but not limited to transferring the application over-the-air, IRDA, Bluetooth, I/O Cables, External storage devices, etc until further guidance is provided

Table 3 Application management feature/class support for MIDP 2.0

System Menu

The Java System Menu can be found under the Java Settings menu under the Main Menu. The Java System menu allows the user to see what version of MIDP and CLDC is being used in the handset. It also shows the user th e free data space available, program space available, and the heap size being used. The following table describes each function in detail.

5 Application Management

Refer to the Table 4 Java System menu:

Action

Description

CLDC Version This displays the CLDC version that is being used in the handset. MIDP Version This displays the MIDP version that is being used in the handset. Data Space This displays the amount of free memory available for d ata used by the

applications, i.e. phone book entries, g ame high scores..

Program Space This displays the amount of free memory available for a pplications. Heap Size This is the amount of runtime memory availabl e in the handset for J2ME

applications.

Table 4 Java System menu

6 JAD Attributes

JAD Attributes

JAD / Manifest Attribute Implementations

The JAR manifest defines attributes to be used by the application management software (AMS) to identify and install the MIDlet suite. These attributes may or may not be found in the application descriptor.

The application descriptor is used, in conjunction with the JAR manifest, by the application management software to manage the MIDlet. The application descriptor is also used for the following:

• By the MIDlet for configuration specific attributes

• Allows the application management software on the handset to verify the MIDlet

is suited to the handset before loading the JAR file

• Allows configuration-specific attributes (parameters) to be supplied to the MIDlet(s) without modifying the JAR file.

Motorola has implemented the follo wing support for the MIDP 2.0 Java Application Descriptor attributes as outlined in the JSR-118. The Table 5 ists all MIDlet attributes, descriptions, and its location in the JAD and/or JAR manifest that are supported in the Motorola implementation.

Attribute Name Attribute Description JAR Manifest JAD

MIDlet-Name The name of the MIDlet suite that identifies

the MIDlets to the user

MIDlet-Version The version number of the MIDlet suite Yes Yes

Yes Yes

MIDlet-Vendor The organization that provides the MIDlet

suite.

MIDlet-Icon The case-sensitive absolute name of a

PNG file within the JAR used to represent the MIDlet suite.

MIDlet-Description The description of the MIDlet suite.

Yes Yes

6 JAD Attributes

MIDlet-Info-URL A URL for information further describing

the MIDlet suite.

MIDlet-<n> The name, icon, and class of the nth

MIDlet in the JAR file. Name is used to identify this MIDlet to the

Yes, or no if included in the JAD.

Yes, or no if included in the JAR Manifest.

user. Icon is as stated above. Class is the name of the class extending the javax.microedition.midlet.MIDletclass.

MIDlet-Jar-URL The URL from which the JAR file can be

Yes

loaded. MIDlet-Jar-Size The number of bytes in the JAR file. Yes MIDlet-Data-Size The minimum number of bytes of

persistent data required by the MIDlet. MicroEdition-Profile The J2ME profiles required. If any of the

profiles are not implemented the

installation will fail. MicroEdition-Configuration The J2ME Configuration required, i.e

CLDC 1.0

MIDlet-Permissions Zero or more permissions that are critical

Yes, or no if included in the JAD.

Yes, or no if included in the JAR Manifest.

to the function of the MIDlet suite. MIDlet-Permissions-Opt Zero or more permissions that are non-

critical to the function of the MIDlet suite. MIDlet-Push-<n> Register a MIDlet to handle inbound

connections MIDlet-Install-Notify The URL to which a POST request is sent

to report installation status of the MIDlet

suite. MIDlet-Delete-Notify The URL to which a POST request is sent

to report deletion of the MIDlet suite. MIDlet-Delete-Confirm A text message to be provided to the user

when prompted to confirm deletion of the

MIDlet suite. Background MIDlets with this Motorola specific attribute

will continue to run when not in focus.

Table 5 MIDlet Attributes, descriptions, and JAD and/or JAR location

7 Java.lang Implementation

Java.lang Implementation

java.lang support

Motorola implementation for the java.lang.System.g etProperty method will support additional system properties beyond what is outlined in the JSR 118 specification and is controlled by a flex bit. These additional system properties can only be access ed by trusted MIDlets.

The additional system properties are as follows:

• Cell ID: The current Cell ID of the device will be returned during implementation.

• IMEI: The IMEI number of the device will be returned during implementation.

The Code Sample 1 shows java.lang support:

System.getProperty("phone.mcc") System.getProperty("phone.mnc") System.getProperty("phone.imei") System.getProperty("phone.cid") System.getProperty(“phone.lai”) System.getProperty(“phone.ta”)

Code Sample 1 Java.lang support

8 Network APIs

Network Connections

The Motorola implementation of Networking APIs will support several network connections. The network connections necessary for Motorola implementation are the following:

• CommConnection for serial interface

Network APIs

• HTTP connection

• HTTPS connection

• Socket connection

• SSL

Refer to the Table 6 for Network API feature/class support for MIDP 2.0:

Feature/Class Implementation

All fields, methods, and inherited methods for the Connector class in the javax.microedition.io package Mode parameter for the open () method in the Connector class the javax.microedition.io package The timeouts parameter for the open () method in the Connector clas s of the javax.microedition.io package HttpConnection interface in the javax.microedition.io p ackage Supported HttpsConnection interface in the javax.microeditio n.io package Supported SecureConnection interface in the javax.microedition.io package Supported SecurityInfo interface in the javax.microedition.io package Supported ServerSocketConnection interface in the javax.microedition.io package Supported UDPDDatagramConnection interface in the javax.microedition.io package Connector class in the javax.microedition.io.package Supported Dynamic DNS allocation through DHCP Supported

HttpConnection interface in the javax.microedition.io.package. Supported

Supported READ, WRITE, READ_WRITE Supported

Supported

HttpsConnection interface in the javaxmicroedition.io.package Supported

+ 100 hidden pages