22 JSRs 120 and 205: Wireless Messaging

The 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 support for 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.

22.1Using 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 JSRs 120 or 205. You can, for example, use the WMA console to send SMS messages to a MIDlet running on the emulator.

22.1.2 WMA Console Interface

The console has a phone number, and it is displayed as part of the WMA Console tab label (for example, 987654321).

The WMA Console user interface has a tab for sending messages and an output window that displays incoming messages.

To set the phone number, select Tools > Options > Miscellaneous. On the WMA Console tab, edit the Assigned Phone Number field and click OK. 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 SDK.

22.1.3 Emulator Phone Numbers

Each running 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.

22.1.4 Sending a Text or Binary SMS Message

To send a text SMS message, click Send SMS. The send window appears. The window automatically lists the phone numbers of all running emulator instances. Select one or more destinations and enter a port number if you wish (the default is 50000). Type your message and click Send.

To send the contents of a file as a binary message, click Send SMS to bring up the send window. Click the Binary SMS tab. Selecting recipients is the same as for sending text SMS messages. You can type in the path of a file directly, or click Browse to open a file chooser.

22.1.5Sending Text or Binary CBS Messages

Sending CBS messages is similar to sending SMS messages except that you don't need to choose recipients. To send a text or binary CBS message, click Send CBS in the WMA console. Specify a message identifier and enter the content of your message.

22.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 two tabs, one for recipients and one for content. On the Header tab, begin by filling in a subject and recipient.

To add more recipients, click the Add button. For example, to send a message to a running emulator whose number is 5550001, type 5550001 in the To field.

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

To add optional media files (Parts) to the message, click the Parts tab and click Add. Most media files will 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.

To remove a part, select it and press Remove.

22.1.7 Receiving Messages in the 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.

22.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.

22.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, select the Application Description category and view the Push Registry tab.

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.

22.2.2 Running WMADemo OTA

Because this sample makes use of the push registry, you can't see all of its features with the standard Run process. Use the Run via OTA feature to install the application into the emulator using a process that mirrors how applications are installed on real devices.

Right-click the WMADemo project and select Properties from the context menu.

Select the Running Category and choose the Execute through OTA radio button. Click OK.

Now run WMADemo in an emulator. There will be a download, then you see an alert that reads, "Is it OK to automatically start the application? WMA Demo wants to register itself to be automatically started. Is it OK to be automatically started?" To proceed, choose Yes.

Wait a few seconds for the application to download to the emulator and register itself.

22.2.3 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.

To launch the WMA console, select Tools > Java ME > WMA Console. To open the WMA Output window, select Window > Output > WMA Console Output. The WMADemo should be running in the emulator, as described in Section 22.2.2, "Running WMADemo OTA".

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

Choose the number that corresponds to the emulator, by default this means checking the box in front of 123456789. If you're not sure what number the emulator is using, look for a number above the emulator screen.

Fill in a port number of 50000.

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

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.

To type a return message, press the Reply soft button. Type a message and select Send. You are 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.)

22.2.4 Sending CBS Messages from WMA Console to an Emulator

This process is similar to sending SMS Messages. Instead of specifying a port number you specify a Message Identifier.

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

Choose Yes. The CBSReceive MIDlet is launched and immediately displays the incoming message. Click Exit to close the MIDlet.

22.2.5 Sending MMS Messages from WMA Console to an Emulator

To send an MMS message from the WMA console to the emulator, make sure that WMADemo has been installed using Run via OTA.

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

In the WMA console, click on 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. If only one emulator is running, that number is displayed in the To field by default. If you don't see your number, click the Add button to add it.

Click on the Parts tab. The WMA console allows 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.

Click on Send to send the message.

The image and its information are displayed in the emulator.

22.3 Running WMA Tool

To send and receive SMS, CBS, and MMS messages from the command line, use

installdir\bin\wma-tool

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:

receive

smsreceive - receives SMS messages

cbsreceive - receives CBS messages

mmsreceive - receives MMS messages

smssend - sends SMS message

cbssend - sends CBS message

mmssend - sends MMS message

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

A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.