Download  Print this page

Motorola C381P J2ME Technical Manual

J2me developer guide
Hide thumbs

Advertisement

Technical Manual
Motorola C381p Handset
J2ME™ Developer Guide
Version 01.00

Advertisement

Table of Contents
loading

  Related Manuals for Motorola C381P J2ME

  Summary of Contents for Motorola C381P J2ME

  • Page 1 Technical Manual Motorola C381p Handset J2ME™ Developer Guide Version 01.00...
  • Page 2: Table Of Contents

    Table of Contents Table of Contents TABLE OF CONTENTS ..........................2 TABLE OF FIGURES..........................6 INDEX OF TABLES ............................ 7 TABLE OF CODE SAMPLES........................9 1 INTRODUCTION ............................ 10 ..............................10 URPOSE ..............................10 UDIENCE .............................. 10 ISCLAIMER .............................. 11 EFERENCES ..........................
  • Page 3 Table of Contents ..........................29 JAVA LANG SUPPORT 8 NETWORK APIS ............................ 30 ..........................30 ETWORK ONNECTIONS ............................ 32 ERMISSION ..........................32 HTTPS C ONNECTION 9 JSR 135 MOBILE MEDIA API......................35 API....................... 35 JSR 135 M OBILE EDIA ............................36 ONTROL .............................
  • Page 4 Table of Contents ........................... 65 ANVAS UNCTIONALITY ..........................67 ARDWARE APPING 16 ONE-CLICK APPLICATION ACCESS .................... 71 ......................... 71 PPLICATION ESOURCES ..........................71 PPLICATION ..........................71 PPLICATION CONS ............................72 OFTKEY ABELS ..................72 FFECT OF ASTER LEAR OR ASTER ESET ....................
  • Page 5 Table of Contents 27 JAVA SYSTEM MENU........................103 ......................... 103 ANAGER View MIDlet Suite Information..................104 ........................104 ELETING UITES 28 INVISIBLE NET FOR J2ME ......................107 ............................107 NTRODUCTION ......................107 J2ME I NET O NVISIBLE PTIONS J2ME Component Options ....................... 107 J2ME Context-Sensitive Menu Options.................
  • Page 6: Table Of Figures

    Table of Figures 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) ..
  • Page 7: Index Of Tables

    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 Function Describes................103 Table 24 Midlet Manager Menu Description..........
  • Page 8 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 ......................
  • Page 9: Table Of Code Samples

    Table of Code Samples 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 ................
  • Page 10: Introduction

    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...
  • Page 11: References

    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.
  • Page 12: Revision History

    Introduction Revision History Version Date Name Reason 00.01 November 09, 2004 C.E.S.A.R. Initial Draft Definitions, Abbreviations, Acronyms Acronym Description Application Management Software Application Program Interface. CLDC Connected Limited Device Configuration Global Positioning System Integrated Development Environment International Telecommunication Union Java Application Descriptor Java Application Loader Java Archive.
  • Page 13: Document Overview

    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 emulation environments. It also describes how to package a J2ME application, how to package a MIDlet, and generate JAR and JAD files properly.
  • Page 14 Appendix A – Key Mapping: this appendix describes the key mapping 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.
  • Page 15: J2Me Introduction

    This chapter of the guide presents a quick overview of the J2ME environment and the tools that can be used to develop applications for the Motorola C381p handset. The Java 2 Platform, Micro Edition (J2ME) The J2ME platform is a new, very small application environment.
  • Page 16: The Motorola J2Me Platform

    J2ME Introduction The Configuration Layer used in the Motorola C381p handset is the Connected Limited Device Configuration 1.1 (CLDC 1.1) and the 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.
  • Page 17: Resources And Api's Available

    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 •...
  • Page 18: Developing And Packaging J2Me Applications

    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...
  • Page 19 For a look at such environments, review the “Motorola 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.
  • Page 20: 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. To use the OTA method, the developer will have a connection through a wireless network to a content server.
  • Page 21: Error Logs

    Downloading Applications 904 JAR Size Mismatch 905 Attribute Mismatch 906 Invalid Descriptor 907 Invalid JAR 908 Incompatible Configuration or Profile 909 Application Authentication Failure 910 Application Authorization Failure 911 Push Registration Failure 912 Deletion Notification 913 Required package not supported by device 999 Other errors Please be aware that the method used by the handset, as per the specifications, is POST.
  • Page 22: Ota And Download

    Downloading Applications Mismatch . Download match the size indicated in JAD 902 User OTA JAR User cancelled download Cancelled: Cancelled. Download <Icon> <Filename> 903 Loss of OTA JAR Browser lost connection with server Installation Failed Service. Download 901 Insufficient OTA JAR Insufficient space to install the Insufficient Storage Memory.
  • Page 23: Table 2 Jad File Information

    Downloading Applications 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 •...
  • Page 24: Application Management

    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 begins.
  • Page 25: Installation And Deletion Status Reports

    Application Management If the user decides to save the data from the current MIDlet, the data will be preserved during the upgrade and the data will 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, upgrade, or deletion of a MIDlet suite will be sent to the server according to the JSR 118 specification.
  • Page 26: Table 4 Java System Menu

    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 data used by the applications, i.e.
  • Page 27: Jad Attributes

    Allows configuration-specific attributes (parameters) to be supplied to the MIDlet(s) without modifying the JAR file. Motorola has implemented the following 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.
  • Page 28: Table 5 Midlet Attributes, Descriptions, And Jad And/Or Jar

    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...
  • Page 29: Java.lang Implementation

    Java.lang Implementation java.lang support Motorola implementation for the java.lang.System.getProperty 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 accessed by trusted MIDlets.
  • Page 30: Network Apis

    Network APIs 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 • HTTP connection • HTTPS connection • Socket connection •...
  • Page 31: Table 6 Network Api Feature/Class Support For Midp 2.0

    Network APIs 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 UDPDatagramConnection interface in the Supported javax.microedition.io.package Table 6 Network API feature/class support for MIDP 2.0 The Code Sample 2 shows the implementation of Socket Connection: Socket Connection import javax.microedition.io.*;...
  • Page 32: User Permission

    The user of the handset will explicitly grant permission to add additional network connections. HTTPS Connection Motorola implementation supports a HTTPS connection on the Motorola C381p handset. Additional protocols that will be supported are the following: • TLS protocol version 1.0 as defined in http://www.ietf.org/rfc/rfc2246.txt...
  • Page 33 Network APIs try { is[i] = hc[i].openInputStream(); byteCounts[i] = 0; readLengths[i] = hc[i].getLength(); System.out.println("readLengths = " + readLengths[i]); if (readLengths[i] == -1) readLengths[i] = BUFFER_SIZE; int bytes_read = 0; int offset = 0; int bytes_left = (int)readLengths[i]; bytes_read = is[i].read(buffer, offset, bytes_left);...
  • Page 34: Code Sample 3 Https Connection

    Network APIs } catch (Exception ex) { } hc[i] = null; Code Sample 3 HTTPS Connection...
  • Page 35: Jsr 135 Mobile Media Api

    JSR 135 Mobile Media API JSR 135 Mobile Media API JSR 135 Mobile Media API The JSR 135 Mobile Media APIs feature sets are defined for five different types of media. The media defined is as follows: • Tone Sequence •...
  • Page 36: Tonecontrol

    JSR 135 Mobile Media API catch (MediaException e) System.out.println("FAILED: exception for realize: " + e.toString()); // Acquire exclusive resources, fill buffers with media data player.prefetch(); catch (MediaException e) System.out.println("FAILED: exception for prefetch: " + e.toString()); // Start the media playback player.start();...
  • Page 37: Guicontrol

    JSR 135 Mobile Media API A tone sequence is specified as a list of non-tone duration pairs and user-defined sequence blocks and is packaged as an array of bytes. The setSequence() method is used to input the sequence to the ToneControl. The following is the available method for ToneControl: -setSequence (byte[] sequence): Sets the tone sequence GUIControl...
  • Page 38: Stoptimecontrol

    JSR 135 Mobile Media API StopTimeControl StopTimeControl allows a specific preset sleep timer for a player. The JSR 135 Mobile Media API will implement public interface StopTimeControl. The following is a list of available methods with regards to StopTimeControl: Gets the last value successfully by setStopTime. getStopTime Sets the media time at which you want the setStopTime...
  • Page 39: Table 8 List Of Audio Mime Types

    JSR 135 Mobile Media API Tone Sequences Audio/x-tone-sequence Audio Table 8 List of audio MIME types Refer to the Table 9 for multimedia feature/class support for JSR 135: Feature/Class Implementation Media package found Supported Media control package Supported Media Protocol package Supported Control interface in javax.microedition.media Supported...
  • Page 40 JSR 135 Mobile Media API Note: If two wave plays have the same frequency, they can mix. See Appendix A – mix audio table. Player number limitation <=4 and MIDI size limitation is 150K MP3 stream size has the limitation...
  • Page 41: Jsr 120 - Wireless Messaging Api

    JSR 120 – Wireless Messaging Wireless Messaging API (WMA) Motorola has implemented certain features that are defined in the Wireless Messaging API (WMA) 1.0. The complete specification document is defined in JSR 120. The JSR 120 specification states that developers can be provided access to send (MO –...
  • Page 42: Sms Port Numbers

    JSR 120 – Wireless Messaging API (MessageConnection)Connector.open("sms://:6000"); Messages received with this identifier will then be delivered to the application by this connection. A server mode connection can be used for both sending and receiving messages. A client mode connection is opened by providing a URL which points to another device.
  • Page 43: Sms Message Types

    Also, for sending, support for a minimum of three messages is supported. Motorola advises that developers should not send messages that will take up more than three SMS protocol messages unless the recipient’s device is known to support more.
  • Page 44: Table 10 Messaging Features/Classes Supported

    JSR 120 – Wireless Messaging API Feature/Class Implementation JSR-120 API. Specifically, APIs defined in the Supported javax.wireless.messaging package will be implemented with regards to the GSM SMS Adaptor All fields, methods, and inherited methods for the Connector Class in Supported the javax.microedition.io package All methods for the BinaryMessage interface in the Supported...
  • Page 45 JSR 120 – Wireless Messaging API byte[] newBin = new byte[size]; for (int i = 0; i < size; i++) { nextByte = (rand.nextInt()); newBin[i] = (byte)nextByte; if ((size > 4) && (i == size / 2)) { newBin[i-1] = 0x1b; newBin[i] = 0x7f;...
  • Page 46 JSR 120 – Wireless Messaging API Setting of address without port number: message.setAddress("sms://+18473297274"); Sending of message: messageConnection.send(message); Receiving of message: Message receivedMessage = messageConnection.receive(); Getting of address: String address = ((TextMessage)message).getAddress(); Getting of timestamp for the message: Message message; System.out.println("Timestamp: " + message.getTimestamp().getTime());...
  • Page 47 JSR 120 – Wireless Messaging API byte[] newBin = createBinary(msgLength); binMsg.setPayloadData(newBin); int num = connClient.numberOfSegments(binMsg); Setting of MessageListener and receiving of notifications about incoming messages: public class JSR120Sample1 extends MIDlet implements CommandListener { … JSR120Sample1Listener listener = new JSR120Sample1Listener(); … // open connection messageConnection = (MessageConnection)Connector.open("sms://:9532");...
  • Page 48: Code Sample 5 Jsr 120 Wireless Messaging Api

    JSR 120 – Wireless Messaging API " + e.toString()); Code Sample 5 JSR 120 Wireless Messaging API...
  • Page 49: Phonebook Access Api

    The primary goal of the Phonebook Access API is to be simple and thin to fit in resource- limited devices like the Motorola C381p handset. This API will specify a base storage class for all types of contacts items presented in the vCard specification (RFC2426 –...
  • Page 50 Phonebook Access API In the Motorola C381p, Phonebook API permissions have been added to the MIDP 2.0 security framework “com.motorola.phonebook.” The behavior is up to the domain setting where the MIDlet falls in. For an untrusted MIDlet, the permission for the API is “Oneshot”.
  • Page 51 Phonebook Access API Sample of code for calling of ‘getNumberRecords(int device)’ method: // get total number of records int numberRecsInPhone = PhoneBookRecord.getNumberRecords(PhoneBookRecord.PHONE_MEMORY); int numberRecsInSim = PhoneBookRecord.getNumberRecords(PhoneBookRecord.SIM_MEMORY); int numberRecsAll = PhoneBookRecord.getNumberRecords(PhoneBookRecord.ALL_MEMORY); Sample of code for calling of ‘getAvailableRecords(int device)’ method: // get number of available records int numberRecsAvalPhone = PhoneBookRecord.getAvailableRecords(PhoneBookRecord.PHONE_MEMORY);...
  • Page 52 Phonebook Access API int maxTelNoLengthSim = PhoneBookRecord.getMaxTelNoLength(PhoneBookRecord.SIM_MEMORY); int maxTelNoLengthAll = PhoneBookRecord.getMaxTelNoLength(PhoneBookRecord.ALL_MEMORY); Sample of code for calling of ‘getMaxEmailLength ()’ method: int maxEmailLength = PhoneBookRecord.getMaxEmailLength(); Sample of code for calling of ‘getIndexBySpeedNo(int speedNo, int sortOrder)’ method: int speedNo = 1; index = PhoneBookRecord.getIndexBySpeedNo(speedNo, PhoneBookRecord. SORT_BY_NAME);...
  • Page 53: Code Sample 6 Phonebook Api

    Phonebook Access API buffer = new String("BEGIN:VCARD\r\nN:;" + new String(name) + "\r\nTEL;TYPE=WORK:1\r\nEND:VCARD\r\n"); int num = PhoneBookRecord.fromVFormat((InputStream)(new ByteArrayInputStream(buffer.getBytes())), PhoneBookRecord.PHONE_MEMORY); Sample of code for calling of ‘toVFormat(OutputStream out, int index, int outFormat, int sortOrder)’ method: int index = 1; ByteArrayOutputStream outStream = new ByteArrayOutputStream(); PhoneBookRecord.toVFormat(outStream, index, PhoneBookRecord.VCARD_3_0, PhoneBookRecord.SORT_BY_NAME);...
  • Page 54: Telephony Api

    Telephony API Telephony API The Telephony API allows a MIDlet to make a voice call, however, the user needs to confirm the action before any voice call is made. The reason for the confirmation is to provide a measure of security from rogue applications overtaking the handset. Unlike standard TAPI, the wireless Telephony API provide simple function and simple even listener: startCall (), send ExtNo (), and endCall (), DialerListener.
  • Page 55: Table 13 Field Summary

    Telephony API Summary static byte PHONE_VOICECALL_CONNECT Phone call was connected event static byte PHONE_VOICECALL_DISCONNECT Phone call was disconnected event static byte PHONE_VOICECALL_DTMF_FAILURE Send extension number error event static byte PHONE_VOICECALL_FAILURE start phone call error event static byte PHONE_VOICECALL_HOLD Current java phone call was held by native phone event static byte PHONE_VOICECALL_INIT Phone start dial-up event static byte PHONE_VOICECALL_TIMEOUT...
  • Page 56: Class Dialer

    Telephony API PHONE_VOICECALL_CONNECT public static final byte Phone call PHONE_VOICECALL_CONNECT connected event PHONE_VOICECALL_DISCONNECT public static final byte Phone call PHONE_VOICECALL_DISCONNECT disconnect ed event PHONE_VOICECALL_TIMEOUT public static final byte Phone PHONE_VOICECALL_TIMEOUT process timeout event PHONE_VOICECALL_HOLD public static final byte Current PHONE_VOICECALL_HOLD java phone call was held by...
  • Page 57: Getdefaultdialer

    Telephony API sendExtNo(String extNumber) void send extension number. void setDialerListener(DialerListener listener) Registers a DialerListener object. void startCall(String telenumber) start a phone call using given telephone number. void startCall(String teleNumber, String extNo) start a phone call using given telephone number and extension number. Table 16 Method Summary The following methods are inherited from java.lang.object: •...
  • Page 58: Startcall

    Telephony API startCall public void startCall( telenumber) String throws IOException start a phone call using given telephone number. Parameters: - the telephone number to be call. telenumber - the extension number to be send. extNo Throws: - if the call could not be created or because of network failure IOException - if the parameter is null NullPointerException...
  • Page 59: Endcall

    Sample DialerListener Implementation Dialer listener program import java.io.IOException; import javax.microedition.midlet.*; import javax.microedition.io.*; import com.motorola.*; public class Example extends MIDlet implements DialerListener { Dialer dialer; // Initial tests setup and execution. public void startApp() { try { dialer = Dialer.getDefaultDialer();...
  • Page 60: Code Sample 7 Dialerlistener Implementation

    Telephony API Asynchronous callback for receive phone call event public void notifyDialerEvent(Dialer dialer, byte event) { switch (event) { case DialerEvent.PHONE_VOICECALL_INIT: // your process break; case DialerEvent.PHONE_VOICECALL_FAILURE: // your process break; case DialerEvent.PHONE_VOICECALL_CONNECT: // your process break; case DialerEvent.PHONE_VOICECALL_DISCONNECT: // your process break;...
  • Page 61: Notifydialerevent

    Parameters: - the Dialer where the TAPI voice call event has arrived dialer - the TAPI voice call event type. event Class Hierarchy • class java.lang.Object o class com.motorola.phone.Dialer o class com.motorola.phone.DialerEvent Interface Hierarchy • interface com.motorola.phone.DialerListener...
  • Page 62: Serial Port Access

    Serial Port Access Serial Port Access The Serial Port RS232 API is incorporated into any J2ME device allowing connection to the J2ME serial port communication stream. Opening the port requires the form Connector.open("comm:/name;parameters) where name is the name of the serial port. (A comma separated list of supported names can be obtained by calling System.getProperty("serialport.name");) The API should allow the J2ME application to query for the available device connections (data cable), as well as the available data speeds.
  • Page 63: Sms Messaging As Gsm Extension

    SMS Messaging as GSM Extension SMS Messaging as GSM Extension The SMS APIs for J2ME environment enable the following functionality: • Creating an SMS message • Sending an SMS message • Viewing an SMS message • Deleting an SMS message The SMS APIs support the following contents to be sent over SMS: •...
  • Page 64: Viewing A Message

    SMS Messaging as GSM Extension Viewing a Message The APIs should provide a way to get a list of messages that is associated with a specific application and to view the messages. Deleting a Message The API should provide a way to delete SMS messages.
  • Page 65: User Display Interface

    User Display Interface User Display Interface The J2ME standard allows specific Canvas, Hardware Mapping and External Event Interaction functionality. Canvas Functionality The J2ME standard specifies that the Canvas class is available to the J2ME application. The J2ME Canvas functionality controls the rendering of objects on the entire display. In addition, the J2ME Canvas requirements a minimum display size and functional soft key area for use by the application.
  • Page 66 User Display Interface All color types are supported, although the appearance of the image will be dependent on the capabilities of the device's screen. Color types that include alpha channel data are supported; however, the implementation may ignore all alpha channel information and treat all pixels as opaque.
  • Page 67: Hardware Mapping

    In addition, if other hardware keys are available, it is left to the manufacturer to determine the functionality of these keys. The following sections detail the standard J2ME required keys and the Motorola proprietary reserved key sets.
  • Page 68: Table 17 Key Ranking Priority

    User Display Interface The handset controls the rendering and positioning of these global commands, but the J2ME application determines the actual availability and functionality of these commands. For example, J2ME application1 may indicate to the KVM that only four of the global commands are to be used/displayed, where as J2ME application2 may indicate that all nine global commands are to be used/displayed.
  • Page 69: Figure 2 Active Global Commands - Back, Cancel, Ok, Help & Stop

    User Display Interface Figure 2 Active Global Commands - Back, Cancel, OK, Help & Stop Example 2: Upon start-up, the J2ME application indicates that the following global commands are active: SCREEN, CANCEL, HELP, OK, and STOP. The handset display would look like this: Figure 3 Active Global Commands - Cancel, Screen, OK, Help &...
  • Page 70 User Display Interface Volume Key Volume keys will not be supported in the first release of J2ME, Java 1.0. In following releases, when the Volume key (s) is pressed and held down, it should always control the speaker/ accessory volume regardless of application. Game Key Mapping Games require the use of UP/DOWN/LEFT/RIGHT and FIRE as a basic set of keys in order to play.
  • Page 71: One-Click Application Access

    One-Click Application Access One-Click Application Access The one-click access to J2ME applications Implementation allows the user to more readily access frequently used Java applications via the soft keys, navigation keys or smart keys. The key requirement is to allow MIDlets to behave as if they were Main Menu applications.
  • Page 72: Softkey Labels

    One-Click Application Access • Large Icons - Until a better solution can be implemented, a generic large animated icon must be created for display on the idle screen. • Small Icons - A 15 x 15 pixels (Must be used in the Personalize list views). The MIDlet-icon JAD attribute specifies the directory name for the icon(PNG image) MIDlets with the MIDlet-icon attribute have the capability to display a...
  • Page 73: Download Midlet Through Browser

    Download MIDlet Through Browser Download MIDlet Through Browser The Download MIDlet Through Browser requires the browser to be connected before performing any downloads on the handset. The example shows How user may access the Browser application by any of the following methods: •...
  • Page 74: Star Active Browser Session From Main Menu

    Download MIDlet Through Browser Star Active Browser Session from Main Menu The Figure 4 describes Staring Active Browser Session from Main Menu: Figure 4 Starting Active Browser Session from Main Menu GetJavaApps is a feature that allows an operator to insert a WAP designated URL that links to a J2ME site with MIDlet suites.
  • Page 75: Downloading Midlets

    Download MIDlet Through Browser Downloading MIDlets The Figure 5 represents J2ME Application (MIDlets) Download and Installation. Figure 5 Downloading and Installing J2ME Application (MIDlets) Steps to Download and Install J2ME Application: • BACK shows previous screen to the user. • If the SELECT softkey is selected, the handset shows display the application size, time to install and version.
  • Page 76 Download MIDlet Through Browser • If the DOWNLD softkey is selected, the handset starts downloading the application. The handset displays “Downloading...% Complete” along with the percentage of downloading completed at a time. “Downloading...% Complete” shall use static dots, not dynamic. •...
  • Page 77: Different Error Checks

    MIDlet. The JAD of the MIDlet has two attributes, Mot-Data- Space-Requirements and Mot-Program-Space-Requirements. If an application developer adds these attributes to their JAD file, a Motorola device can determine if enough memory exists on the phone before the MIDlet is downloaded. These attributes may or may not be...
  • Page 78 Download MIDlet Through Browser provided in all MIDlets. Two separate prompts will be displayed depending on whether these attributes are present. In cases where there is not enough memory to download the application, the user MUST be given a message to delete existing applications in order to free additional memory. The following messages and screen flows will be displayed depending on whether specific JAD attributes are present or not:...
  • Page 79: Figure 7 Memory Full Error

    Download MIDlet Through Browser Figure 7 Memory full error Rules: • If Mot-Data-Space-Requirements and Mot-Program-Space-Requirements attributes are present in the JAD, the above noted prompt should be displayed. This value takes into account the memory requirements of the MIDlet and the current memory usage on the phone, in order to tell the user exactly how much memory to free.
  • Page 80: Memory Full During Installation Process

    Download MIDlet Through Browser Figure 8 Mot-Data-Space & Mot-Program-Space attributes are not present or are incorretct Rules: • If Mot-Data-Space-Requirements and Mot-Program-Space-Requirements JAD attributes are not present in the JAD file, the handset can not determine how much memory to free and will display the above help dialog. •...
  • Page 81: Application Version Already Exists

    Download MIDlet Through Browser Figure 9 Memory Full help message during installation process Rules: • The installation process is canceled when this error condition occurs. • The Memory Full error will no longer be a transient prompt but a dialog screen with a Help softkey and a Back softkey will be displayed.
  • Page 82: Newer Application Version Exists

    Download MIDlet Through Browser Figure 10 Same Version of Application already exists on the handset Rules: • Handset checks for MIDlet-Name, MIDlet-vendor, and version number. If they are the same, a dialog “Application Already Exists” is displayed. • To know more about this error, select the DETAILS softkey. •...
  • Page 83: Figure 11 Latest (Newer) Version Of Application Exists

    Download MIDlet Through Browser Figure 11 Latest (Newer) Version of Application exists Rules: • If the latest or newer version of application is already present on the handset, it cannot be downloaded...
  • Page 84: Lightweight Windowing Toolkit

    Lightweight Windowing Toolkit Lightweight Windowing Toolkit LWT integrate with the LCDUI API within the MIDP and enhance the capabilities to include a component-level API through which developers can control the contents and layout of their screens. These components are graphical user interface elements such as buttons, check boxes, text fields, images, etc.
  • Page 85: Udp Support

    UDP Support UDP Support This functionality is to enable J2ME applications access to Generic UDP Transport Service. • This enhancement allows for J2ME applications to utilize the UDP header compression format for data applications over IP. • The API should follow the guidelines of the User Datagram Protocol standard, IETF RFC 768, J.
  • Page 86: Shared Jad Urls

    This allows the user to send messages to friends, telling them where to download the application. Upon receipt of a Tell-A-Friend message, a Motorola handset user should be able to use the browser’s GOTO functionality. Selecting GOTO will cause the download of JAD to...
  • Page 87: Accessing Tell-A-Friend From Smm

    Shared JAD URLs Accessing Tell-A-Friend from SMM The MIDlet Manager menu lets the user perform certain actions on the selected MIDlet suites. The Table 18 describes the various actions that can be performed on a suite. Action Description Tell-A-Friend Populates a message with the link to the application’s JAD URL inserted into the message body, following messaging standard behavior for pre-populated messages.
  • Page 88: Downloading Through Browser

    Shared JAD URLs Figure 12 the MIDlet Manager and the context-sensitive menus Downloading through Browser Rules: • When downloading a J2ME application, the browser shall provide JAM with the URL of the JAD file. This URL shall override the URL specified by Mot- Midlet-URL attribute in case of conflict.
  • Page 89: Downloading Through Mms

    Shared JAD URLs Downloading through MMS Rules: • When downloading an application via MMS, JAM shall use the JAD attribute Mot-Midlet- URL if present to get the JAD URL.
  • Page 90: Get Url From Flex Api

    Get URL from Flex API Get URL from Flex API Overview This feature allows accessing URL stored in FLEX by a Java application. Carriers flex the URL, which is used for content download, into the phone just like any invisible net URL. So, this feature would allow Java applications to read and display the URL stored in flex for users that would like to download new levels of Game.
  • Page 91: Security Policy

    Get URL from Flex API Security Policy Only trusted applications will be granted permission to access this property.
  • Page 92: Multiple Key Press

    Left Pressed + Fire Pressed. In the same way, when the 2 keys are released, Java object (e.g. Canvas) will receive Left Released + Fire Released. The following sets of keys will support multi-button press support on the Motorola C381p handset. Multi-button press within each set will be supported, while multi-button press across these sets or with other keys will not be supported.
  • Page 93: Table 19 Gaming And Keypad Feature/Class

    Multiple Key Press key. Map the DOWN_PRESSED field in Supported javax.microedition.lcdui.GameCanvas to the bottom position of the key Map the LEFT_PRESSED field in Supported javax.microedition.lcdui.GameCanvas to the left position of the key Map the RIGHT_PRESSED field in Supported javax.microedition.lcdui.GameCanvas to the right position of the key All methods and inherited methods for the Layer class in Supported javax.microedition.lcdui.game...
  • Page 94: Itap

    iTAP iTAP Intelligent Keypad Text Entry API When users are using features such as SMS (short message service), or “Text Messaging”, they can opt for a predictive text entry method from the handset. The J2ME environment has the ability to use SMS in its API listing. The use of a predictive entry method is a compelling feature to the MIDlet.
  • Page 95: Lcdui

    LCDUI LCDUI LCDUI API The Table 21 lists the specific interfaces supported by Motorola implementation: Interface Description Choice Choice defines an API for user interface components implementing selection from a predefined number of choices. CommandListener This interface is used by applications which need to receive high-level...
  • Page 96: Table 22 Specific Classes Supported By Motorola Implementation

    Form. Ticker Implements a “ticker-tape”, a piece of text that runs continuously across the display. Table 22 Specific classes supported by Motorola implementation Refer to Table 23 for LCDUI feature/class support for MIDP 2.0: Feature/Class Implementation All fields, constructors, methods, and inherited methods for the Alert Supported class in the javax.microedition.lcdui package...
  • Page 97 LCDUI Will provide and play an audible sound when the play Sound() method Supported is called with an AlertType of WARNING Will provide and play an audible sound when the play Sound() method Supported is called with an AlertType of CONFIRMATION Will provide and play an audible sound when the play Sound() method Supported is called with an AlertType of INFO...
  • Page 98 LCDUI package All fields, methods, and inherited methods for the Display class in the Supported javax.microedition.lcdui package Maximum colors for the numColors() method in 64K colors javax.microedition.lcdui.Display supported All methods and inherited methods for the Displayable class in the Supported javax.microedition.lcdui package Adding commands to soft buttons before placing it in a menu for the Supported...
  • Page 99: Table 23 Lcdui Feature/Class

    LCDUI All fields, constructors, methods, inherited fields, and inherited Supported methods for the TextField class in the javax.microedition.lcdui package Visual indication with UNEDITABLE field set will be provided Supported All constructors, methods, and inherited methods for the Ticker class Supported in the javax.microedition.lcdui package OEM Lights API providing control to the lights present on the handset Supported, Fun Lights API...
  • Page 100: Auto Launch Of Midlets

    Auto Launch of Midlets Auto Launch of Midlets The Java framework on the device must provide a mechanism to automatically launch midlets based on specific message. The message may be generated by several clients including a push message coming from the network. Once the KVM received the message, it takes the appropriate action of launching the midlet the message is intended for.
  • Page 101: Background Applications

    Background Applications Background Applications Background Attribute A Motorola specific JAD attribute called background exists. MIDlets with JAD file containing Background = True can run in the background mode. Background Java Application Lifecycle A MIDlet with background attributes will continue running when not in focus (in the background mode) or when the flip is closed if the MIDlet is flip insensitive.
  • Page 102: Flip Behaviors

    Java icon will be displayed in the status bar. Flip Behaviors A Motorola specific JAD attribute called FlipInsensitive exists. When a MIDlet is running and the flip is closed by the user, the MIDlet will follow one of the following behaviors: •...
  • Page 103: Java System Menu

    Java System Menu Java System Menu The Java System menu allows the user to see what version of MIDP and CLDC is being used in the phone. It also shows the user the free data space available, program space available, and the heap size being used. The Table 24 describes each function in detail. Action Description CLDC Version...
  • Page 104: View Midlet Suite Information

    Java System Menu View MIDlet Suite Information To view information on any MIDlet suite, the user brings up the MIDlet Manager menu. The user highlights the Details option and SELECTs it to view the information. The information presented includes MIDlet suite name, vendor, version, number of apps in suite, and flash usage, both data and program space.
  • Page 105: Figure 15 Deleting Midlet Suites

    Java System Menu highlights the Delete option and SELECTs it to delete the suite. This brings up a confirmation dialog. Upon confirmation by the user, the suite and all persistent data is deleted from the device. The figure 15 illustrates this. Figure 15 Deleting MIDlet Suites Rules: •...
  • Page 106 Java System Menu • If the application name is longer than 12 characters, it must be truncated. The “Delete Entire Suite and All data?” text should be displayed after the above information. • While the MIDlet suit is being deleted, a dialog box will display, “Please Wait...” The dialog box will remain on the display until the application has been completely delete •...
  • Page 107: Invisible Net For J2Me

    J2ME context-sensitive menus, such as Games & Apps, and Java Tools, as listed in the following sections. J2ME Component Options A product utilizing the Motorola J2ME solution should be able to use the “Invisible Net” functionality to embed URLs within the following J2ME menus: •...
  • Page 108 Invisible Net for J2ME • URLs associated with J2ME menus or components will be launched using one of the following methods: o HTTP download with the following exceptions: Launch shall be directly to the URL associated with the J2ME menu item. If flexed on, retrieve the URL from the HTTP client.
  • Page 109: J2Me Context-Sensitive Menu Options

    Invisible Net for J2ME o CxD media team will provide or approve any J2ME menu icons or graphics. o Rendering guidelines for J2ME menu prompt items or J2ME menu list items with associated URLs shall be outlined in CxD NES: SYN2_NES_058 documentation.
  • Page 110 Invisible Net for J2ME • A developer may embed a URL within a context-sensitive menu. Because the prompts and URLs in this MRS are variable and flexible and must be approved by the product groups, regions and customers, these items must be validated by as accepted.
  • Page 111: Download Midlet Through Pc

    Download Midlet through PC Download Midlet through PC To download MIDlets through a PC, make a connection to a PC through IrDA, Bluetooth, USB or Serial Cable (RS 232). This content considers only the RS232 connection using JAL. Establishing Connection When a successful connection to a PC is made, an application can be downloaded.
  • Page 112: Operator Apps Provisioning

    Operator Apps Provisioning Operator Apps Provisioning The application provisioning feature uses the existing functionality to deliver a trigger pull of Java applications. The following steps are performed to achieve this functionality. • The operator sets up a URL with the applications that they want to be pushed.
  • Page 113: Midp 2.0 Security Model

    MIDP 2.0 Security Model MIDP 2.0 Security Model The following sections describe the MIDP 2.0 Default Security Model for the Motorola C381p handset. The chapter discusses the following topics: • Untrusted MIDlet suites and domains • Trusted MIDlet suites and domains •...
  • Page 114: Untrusted Midlet Suites

    MIDP 2.0 Security Model MIDletStateChangeException class in the javax.microedition.midlet package All constructors and inherited methods for the Supported MIDletStateChangeException class in the javax.microedition.midlet package Table 26 Security feature/class support for MIDP 2.0 Please note the domain configuration is selected upon agreement with the operator. Untrusted MIDlet Suites A MIDlet suite is untrusted when the origin or integrity of the JAR file cannot be trusted by the device.
  • Page 115: Trusted Midlet Suites

    API or function. User Permission Interaction Mode User permission for the Motorola C381p handsets is designed to allow the user the ability to either deny or grant access to the protected API or function using the following interaction modes (bolded term(s) is prompt displayed to the user): •...
  • Page 116: Implementation Based On Recommended Security Policy

    Policy The required trust model, the supported domain, and their corresponding structure will be contained in the default security policy for Motorola’s implementation for MIDP 2.0. Permissions will be defined for MIDlets relating to their domain. User permission types, as well as user prompts and notifications, will also be defined.
  • Page 117: Trusted Midlet Suites Using X.509 Pki

    MIDP 2.0 Security Model Dial a call “Make Phone Call?” “Use CBS?” Receive CBS “Receive CBS?” Table 27 Protected Functionality fot top line of prompt The radio button messages will appear as follows and mapped to the permission types as shown in the Table 28: MIDP 2.0 Permission Types Dialog Prompts...
  • Page 118: Signer Of Midlet Suites

    MIDP 2.0 Security Model operator, or certificate authority. Only root certificates stored on the handset will be supported by the Motorola C381p handset. Signer of MIDlet Suites The signer of a MIDlet suite can be the developer or an outside party that is responsible for distributing, supporting, or the billing of the MIDlet suite.
  • Page 119: Inserting Certificates Into Jad

    MIDP 2.0 Security Model Inserting Certificates into JAD When inserting a certificate into a JAD, the certificate path includes the signer certificate and any necessary certificates while omitting the root certificate. Root certificates will be found on the device only. Each certificate is encoded using base 64 without line breaks, and inserted into the application descriptor as outlined below per MIDP 2.0.
  • Page 120: Verifying The Midlet Suite Jar

    MIDP 2.0 Security Model attribute with this name. The value of each attribute is abase64 encoded certificate that will need to be decoded and parsed. 2. Validate the certification path using the basic validation process as described in RFC2459 using the protection domains as the source of the protection domain root certificates.
  • Page 121: Table 30 Midlet Suite Verification

    MIDP 2.0 Security Model The Table 30 is a summary of MIDlet suite verification including dialog prompts: Initial State Verification Result JAD not present, JAR downloaded Authentication can not be performed, will install JAR. MIDlet suite is treated as untrusted. The following error prompt will be shown, “Application installed, but may have limited functionality.”...
  • Page 122: Appendix A: Audio Mix Table

    Appendix A: Audio Mix Table Appendix A: Audio Mix Table Single Tone- MIDI Video Video tons Sequence w/audio audio Single tone Tone- sequence Partly MIDI Video w/audio Video w/o audio Table 31 Audio Mix NOTE: If two wave plays have the same frequency, they can mix...
  • Page 123: Appendix B: Key Mapping

    SCROLL UP SCROLL DOWN DOWN SOFTKEY 1 SOFT1 SOFTKEY 2 SOFT2 MENU SOFT3 (MENU) SEND SELECT Also, call placed if pressed on lcdui.TextField or lcdui.TextBox with PHONENUMBER constraint set. CENTER SELECT SELECT Handled according to Motorola specification: Pause/End/Resume/Background menu invoked.
  • Page 124 Appendix B: Key Mapping The following table identifies keys that will be assigned to game actions defined in GameCanvas class of MIDP 2.0. Action First Set Second Set Third Set Non-simultaneous keys Left Nav (LEFT) Right Nav (RIGHT) Nav (UP) Down Nav (DOWN) Game_A...
  • Page 125: Appendix C: Memory Management Calculation

    Appendix C: Memory Management Calculation Appendix C: Memory Management Calculation Available Memory The available memory on the Motorola C381p handset is the following: • Shared memory for MIDlet storage and removable memory • 800k Bytes Heap size...
  • Page 126: Appendix D: Faq

    The MOTOCODER developer program is online and able to provide access to Frequently Asked Questions around enabling technologies on Motorola products. Access to dynamic content based on questions from the Motorola J2ME developer community is available at the URL listed below.
  • Page 127: Appendix E: Http Range

    Appendix E: HTTP Range Appendix E: HTTP Range Graphic Description The following is a graphic description of HTTP Range: Figure 16 Description of HTTP Range...
  • Page 128: Appendix F: Spec Sheet

    Appendix F: Spec Sheet Appendix F: Spec Sheet C381p Spec Sheet Listed below is the spec sheet for the Motorola C381p handset. The spec sheet contains information regarding the following areas: • Technical Specifications • Key Features • J2ME Information •...
  • Page 129 J2ME™ specifications: http://www.java.sun.com/j2me MIDP v2.0 specifications: http://www.java.sun.com/products/midp Tools: CLDC v1.0 specifications: http://www.java.sun.com/products/cldc J2ME™ SDK version v4.0 WAP forum: http://www.wap.org Motorola Messaging Suite v1.1 Purchase: Documentation: Visit the Motocoder Shop at http://www.motocoder.com/ Creating Media for the Motorola C381p Handset Accessories: http://www.motorola.com/consumer...
  • Page 130 Appendix F: Spec Sheet MOTOROLA and the Stylized M Logo are registered in the U.S. Patent & Trademark Office. All other product or service names are the property of their respective owners. Java and all other Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.