Skip Headers
Oracle® Java Micro Edition Software Development Kit Developer's Guide
Release 3.2 for Eclipse on Windows
  Go To Table Of Contents
Go To Index


19 JSR 205: Wireless Messaging

The Oracle Java ME SDK supports the Wireless Messaging API (WMA) with a sophisticated simulation environment. WMA 1.1 (JSR 120) enables MIDlets to send and receive Short Message Service (SMS) or Cell Broadcast Service (CBS) messages. WMA 2.0 (JSR 205) includes all this and support for Multimedia Message Service (MMS) messages as well.

This chapter describes the tools you can use to develop WMA applications. It begins by showing how to configure the emulator's support of WMA. Next, it describes the WMA console, a tool for testing WMA applications.

Many of the tasks in this topic can also be accomplished from the command line. See Section 19.3, "Running WMA Tool."

19.1 Using the WMA Console to Send and Receive Messages

The WMA console is a tool that enables you to send messages to and receive messages from applications that use JSR 205. You can, for example, use the WMA console to send SMS messages to a MIDlet running on the emulator.

19.1.1 Launching the WMA Console

Be sure to select the Java ME perspective. Select Window > Open Perspective > Other > Java ME.

To launch the WMA console, select Run > WMA Console. Messages can be sent from the WMA Console to an emulator instance.

The console opens as a tab in the Eclipse documents area. The console phone number is displayed as part of the WMA Console tab label (for example, 987654321).

The WMA console phone number is an editable CLDC property. To edit a property, follow these steps:

  1. In the Device Selector, click the Oracle Java ME Platform SDK 3.2 node.

  2. Type a new value in the WMA Console Phone Number 1 field.

    If the number is available it is assigned to the console immediately. If the number is in use it is assigned to the console the next time you restart the IDE.

19.1.2 WMA Console Interface

To open the WMA Output window, select Run > WMA Console Output. This window displays messages received from an emulator.

Surrounding text describes wmaconsole_g.gif.

19.1.3 Emulator Phone Numbers

Each instance of the emulator has a simulated phone number that is shown in the emulator window. The phone numbers are important because they are used as addresses for WMA messages. The phone number is a device property and it can be changed. In the device selector, right-click a device and view its properties.

19.1.4 Sending a Text or Binary SMS Message

To send a text SMS message, click Send SMS.

  • The To Clients window automatically lists the phone numbers of all running emulator instances. Select one or more destinations and enter a port number (the default is 50000, as described in Section 19.2.1, "WMADemo Push Registry Values."

  • To send a text message, select the Text Message tab, type your message and click Send.

  • To send the contents of a file as a binary message, click the Binary Message tab. Type in the path of a file directly, or click Browse to open a file chooser.


The maximum message length for text and binary messages is 4096 bytes.

To try this yourself see Section 19.2.2, "Sending SMS Messages From WMA Console to an Emulator and Back."

19.1.5 Sending Text or Binary CBS Messages

Sending CBS messages is similar to "Sending a Text or Binary SMS Message" except that recipients are unnecessary because it is a broadcast.

To send a text or binary CBS message, click Send CBS in the WMA console. Specify a message identifier (see Section 19.2.1, "WMADemo Push Registry Values") and enter the text or binary content of your message. The maximum message length for text and binary messages is 4096 bytes.


The emulator displays only the first 160 symbols of a received CBS message.

19.1.6 Sending MMS Messages

MMS messages consist of one or more files, usually images or sounds. An MMS message can be sent to multiple recipients.

To send an MMS message from the WMA console, click the Send MMS button. The window for composing MMS messages has Header and Parts tabs.

  • The header tab addresses the message.

    The To area automatically lists one of the phone numbers from the running emulator instances, and you can click the Add button to select other available phone numbers from the drop-down list.

    To remove a recipient, first select its line, then click Remove.

    When a recipient is removed it must be added back manually. Click the Add button and a new line is added to the recipient table.

  • To add optional media files (Parts) to the message, click the Parts tab and click Add. The maximum message length for text and binary messages is 4096 bytes.

    Most media files have information to fill the Content Location, Content ID, Mime-Type (text/plain for simple MMS), and Encoding fields, but you can edit these fields as well. The default ID for the demo is example.mms.MMSDemo (see Section 19.2.1, "WMADemo Push Registry Values").

    To remove a part, select it and press Remove.

To try this yourself, see Section 19.2.3, "Sending MMS Messages from WMA Console to an Emulator."

19.1.7 Receiving Messages in the WMA Console

To start the WMA console, select Run > WMA Console. The WMA console window has its own phone number displayed on the WMA Console tab. You can send messages from your applications running on the emulator to the WMA console.

Received messages are displayed in the WMA output window.

19.2 Running WMADemo

The WMADemo sample project shows how to send and receive SMS, CBS, and MMS messages. Messages can be exchanged between emulator instances and can be generated or received using the WMA console utility.

19.2.1 WMADemo Push Registry Values

The push registry determines how the demo establishes certain types of connections. This information is set in the Application Descriptor. To view it, right-click on the WMA Demo project and select Properties. In the Properties window, go to Application Description>Optional>Push Registry.

  • For SMS messages the port number is 50000.

  • For CBS Messages, the Message Identifier is 50001.

  • For MMS messages, the application ID is example.mms.MMSDemo.

19.2.2 Sending SMS Messages From WMA Console to an Emulator and Back

In this demo you send messages between the WMA Console and the client demo application running on the emulator. Using the WMA console to send messages to the emulator exercises the push registry.

  1. To launch the WMA console, select Run > WMA Console. To open the WMA Output window, select Run > WMA Console Output. The WMADemo should be running in the emulator.

  2. Click on the Send SMS button in the WMA console window.

    Choose the number that corresponds to the emulator. Typically you check the box in front of 123456789. If you are not sure what number the emulator is using, look for a number above the emulator screen.

    Fill in a port number of 50000. This is required because the demo waits for the SMS on that port.

    Type your text message in the Message field and click Send.

  3. The emulator asks if it is OK if the WMADemo interrupts and if it can be started. You might receive several permission requests based on your firewall settings.

    Choose Yes. The SMSReceive MIDlet is launched and immediately displays the incoming SMS message.

  4. To type a return message, press the Reply soft button. Type a message and select Send from the menu. You might be asked to give permission because there is a cost to your phone number. In the IDE, look in the WMA Output Window to confirm that your reply has been received. (The output window is typically displayed below the WMA Console. Be sure to click the WMA Output Window tab.)

19.2.3 Sending MMS Messages from WMA Console to an Emulator

To send an MMS message from the WMA console to the emulator, follow these steps:

  1. From the WMADemo home screen, choose MMS Receive. The emulator displays: "MMS Receive" and the message "Waiting for MMS on applicationID example.mms.MMSDemo..."

  2. In the WMA console, click Send MMS to open the MMS composition window. The Header tab is open by default. Supply any message subject, the application ID example.mms.MMSDemo, and the telephone number of the running emulator. That number is displayed to the right of the To field by default.

    The Address Type field on the left is a drop-down list from which you can choose To, Cc or Bcc.

    If you do not see the number of a running emulator, click the Add button to add it to the Address field. When you have listed multiple numbers, the Address field becomes a drop-down list.

  3. Click the Parts tab. The WMA console enables you to select files to send as parts of the MMS message. Click Add and use the file browser to find the file you want to send. Click OK.

  4. Click Send to send the message.

    The image and its information are displayed in the emulator.

19.3 Running WMA Tool

WMA Tool is the command line version of the WMA Console. To send and receive SMS, CBS, and MMS messages from the command line, run:

installdir\bin\wma-tool <command> [options]

The device manager must be running before you launch wma-tool.

When the tool is started, it outputs the phone number it is using.


Each protocol has send and receive commands. The requested command is passed to the tool as a first argument. Possibilities are:

The *send commands send the specified message and exit. The *receive commands print incoming messages until they are explicitly stopped.


-o outputDir. Store binary contents to outputDir.

-t timeout. Non-interactive mode, waits the number of timeout seconds for messages.

-f Store text contents as files instead of printing them.

-q Quiet mode.

19.3.1 smsreceive, cbsreceive, and mmsreceive

The syntax for receiving a message is basically the same for all three protocols.

smsreceive [-o outputDir] [-t timeout] [-q]

cbsreceive [-o outputDir] [-t timeout] [-q]

mmsreceive [-o outputDir] [-t timeout] [-q]

19.3.2 smssend

wma-tool smssend target_phone target_port  message_content

  • target_phone

    Phone number of the target phone. Mandatory first argument.

  • target_port

    Port of the target phone. Mandatory second argument.

  • message_content

    Mandatory third argument. Can have one of these two forms:

    • text: text of the text message

    • -f file: sends content of the specified file as a binary message.


    wma-tool smssend 123456789 50000 "smssend message from wma-tool"

19.3.3 cbssend

wma-tool cbssend  message_id  message_content

  • message_id

    ID of the message. Mandatory first argument.

  • message_content

    Mandatory second argument. Can have one of these two forms:

    • text: text of the text message

    • -f file: sends content of the specified file as a binary message.


    wma-tool cbssend 50001 "cbssend message from wma-tool"

19.3.4 mmssend

wma-tool mmssend applicationId subject
     [-to <targetphone>]* [-cc <target phone>]* [-bcc <target phone>]*
     [-part { <part_from_file> | <part_from_text> } ]*

Each part is defined by name=value pairs delimited by a semicolon ";" separator.

Part Variables

To create part_from_file, define the following variables.


The file and the mimeType must be separated by a semicolon.

  • file

    File to send as a message part.

  • mimeType

    Mime type of the file.

To create part_from_text, define the following variables:

  • text

    Text to send as a message part. mimeType is set to text/plain.

  • -to target_phone

    "to" target phone number. You can use any number of these options.

  • -cc target_phone

    "cc" target phone number. You can use any number of these options.

  • -bcc target_phone

    "bcc" target phone number. You can use any number of these options.

Part from Text Options

Separate options with semicolons. For example:

  • -part contentId=content ID; encoding=encoding; text=text

    Appends text part to the message. You can use any number of these options. Contains the following options:

    • content ID: content ID of this message part

    • encoding: Sent text encoding. Only relevant for "text/plain". Mime type defaults to UTF8.

Part from File Options

-part mimeType=mime type; contentId=content ID; file=file name

  • Appends binary part to the message with content loaded from the given file. You can use any number of these options.

    Separate the options with a semicolon.

    • content id: content ID of this message part

    • mime type: mime type of this message part

    • file name: file with content of this message part

    • fileEncoding: Encoding of text in the file, only relevant for "text/plain", only applies if the file argument is present. Defaults to the value of the encoding variable.


wma-tool mmssend example.mms.MMSDemo MySubject -to 123456789 -part file=Duke.png;mimeType=image/png