Wireless Messaging with the Wireless Toolkit

Chapter 7 Wireless Messaging with the Wireless Toolkit

The Wireless Messaging API (WMA) is supported by the J2ME Wireless Toolkit. With WMA, you can send brief text or binary messages by means of a wireless connection to one or to multiple mobile devices. The WMA supports Short Message Service (SMS) and Cell Broadcast Service (CBS) messaging. With SMS, you can have peer to peer messaging or client to server messaging. CBS enables messages to be broadcast to multiple devices connected to a cell or a network of cells simultaneously.

You can develop and test applications that use SMS and CBS messaging. To help you develop and test SMS and CBS messaging applications, the Wireless Toolkit provides you with:

Client to client messaging emulation enabling you to send messages between multiple emulators simultaneously

The ability to create applications that use WMA messaging and emulate the running of those applications

A WMA console that enables you to send and receive SMS text or binary messages to an emulated device and broadcast CBS text or binary messages to multiple emulators running simultaneously

The ability to create WMA push registry entries

WMA attributes that you can set in the Preferences dialog box to customize the phone numbers assigned to emulators, to specify an SMSC phone number, and to performance test your WMA applications

A network monitor to examine transmissions of SMS and CBS messages

A J2SE-based API that provides a mechanism to plug J2SE programs into the internal emulated wireless messaging environment of the Wireless Toolkit.

See the WMA specification at http://java.sun.com/products/wma for information about wireless messaging.

Getting Started With WMA Emulation

Use the WMA console to develop and test your messaging applications. You can send text or binary messages in either SMS or CBS mode to one or more emulated devices. You can use the console as a server with the emulated device acting as the client. The next section walks you through using the WMA console to test your messaging application. One way to familiarize yourself with the WMA console is to run the SMSDemo application included with the Wireless Toolkit (select it from the Open Project list), which uses WMA messaging. You can find a walk through of the SMSDemo application in the {j2mewtk.dir}\docs directory.

Before using the console, go through the following checklist for preparatory procedures that apply:

Make sure the WMA API is available for use during the session. Go to Edit -> Preferences and click the API Availability tab and make sure the WMA API option is checked.

If you want to simulate running using OTA provisioning, run using OTA directly from the KToolbar by choosing the Run via OTA command in the Project menu after you have packaged your project.

If you need to sign you application and will be running in OTA provisioning mode, check that the permissions settings for your project include the appropriate set of the following permissions relevant to your application:

javax.microedition.io.Push Registry

javax.microedition.io.Connector.sms

javax.microedition.io.Connector.cbs

javax.wireless.messaging.sms.send

javax.wireless.messaging.sms.receive

javax.wireless.messaging.cbs.receive

If you want to simulate real time delays in message transmission, make sure you have set the Message Fragment Loss and Message Delivery Delay attributes in the WMA panel of the Preferences dialog box. See "Setting WMA Parameters" in Chapter 5, "Working With the Emulator” for information on setting WMA performance parameters.

See "Adding API Permissions" in Chapter 3, "Operating with KToolbar” for information on setting MIDlet permissions.

Sending a Text SMS Message From the
WMA Console

You can send a text SMS message to a running emulated device from the WMA console by following these steps:

Click Open Console under WMA in the Utilities window.

The WMA console window opens. The phone number assigned to the console is displayed in the output screen. This number increases incrementally each time you run the console.

WMA console window displaying current default phone number, 5550000 being used.

FIGURE 26 – WMA Console Window

Click Send SMS in the console to send an SMS message to the emulated device.

The Send a Message dialog box opens. The assigned phone numbers of the console and any running emulated devices are shown in the Selected Clients list:

Send SMS dialog box displaying list of clients.

FIGURE 27 – Send a Message - SMS Dialog Box

Each time you run an emulated device, a phone number is assigned to it and added to the Selected Clients list.

Select the client number from the list and type the client’s port number in the Port text field.

By specifying a port number for an SMS message, you are designating a specific application or communication channel to receive or send your message through. Omitting the port number means that the message is sent directly to the client device. Since MIDlets can only receive SMS messages with a port number specified, you need to enter a port number.

For information on restrictions on port numbers for SMS messages, see the WMA specification at http://java.sun.com/products/wma.

Type a brief message in the Message field and click Send.

For maximum message length, consult the Wireless Messaging API. Maximum message (payload) length is dependent on the type of encoding used among other factors. If your message exceeds the allowable limit, an error message is displayed in the console’s output screen.

For a description of the SMS Demo application, see the “SMSDemo Application” document in the {j2mewtk.dir}\docs directory.

Sending a Binary SMS Message

Sending a binary SMS message is similar to sending a text message. To send a binary message:

Click Binary SMS in the Send a Message dialog box.

Type the pathname for the binary file you want to send or select one from the file chooser by clicking Browse, then click Send.

The Console screen in the WMA console window displays output with the URL address of the receiving device.

Sending a CBS Message

You can use the WMA console to send a CBS broadcast message to all running emulators. The procedure is similar to sending an SMS message. After you have opened the WMA console from the Utilities window:

Click Send CBS.

The Send a Message dialog box opens.

Click Text CBS or Binary CBS as desired.

Enter a message or specify a binary file and click Send.

If you are sending a text message, you must provide a message identifier and a brief text message in the corresponding fields in the dialog box.

If you are sending a binary message, you must provide a message identifier and a pathname for the binary file.

The output screen in the WMA console window displays information whether the information was sent and received or if an error occurred.

Setting WMA Preferences

The WMA panel of the Preferences dialog box contains fields that enable you to set WMA-related features.

Setting Device and SMSC Phone Numbers

The Wireless Toolkit assigns unique phone numbers to emulated devices as they are launched. These phone numbers are the addresses of the devices for sending and receiving SMS messages. Each field accepts a numeric string of eighteen digits or less with no spaces.

At times, you might want to specify that the next emulator you launch should have a specific phone number. You might want to do this if you are developing a MIDlet that assumes it has a specific phone number. You can specify this phone number in the "Phone Number of Next Emulator" field.

The WMA specification provides a mechanism for the MIDlet to discover the phone number of the SMSC that services the telephone. While there is no real SMSC within the emulated environment, you may specify this phone number in the "SMSC Phone Number" field.

The default first assigned phone number is 5550000. In locales outside the United States, you might want to change this number to conform to local phone number conventions. You can specify the first phone number that is assigned to an emulator in the "First Assigned Phone Number" field.

Specifying Message Delivery Parameters

The Wireless Messaging API specification provides automatic fragmentation and reassembly of messages that are too long to be sent in a single SMS message. The maximum size of a singe SMS fragment is determined by the content type and encoding of the message body. The Wireless Toolkit’s emulators automatically fragment longer messages into individual pieces. All the individual pieces are delivered to the destination address. The recipient automatically reassembles the fragments into the whole message before returning it to the MIDlet.

Many factors contribute to the actual delivery time of a message You can use the following parameters to simulate the real-world constraints on message delivery:

While in practice SMS message delivery is relatively reliable, there is no guarantee that all messages or message fragments will be delivered. You can simulate the random loss of message fragments using the "Random Message Fragment Loss" slider.

The Message Fragment Delivery Delay represents the time it takes for the wireless network to deliver SMS messages from source to destination. Delays might occur in the real world if a recipient is very distant or is shut off. You can simulate the delay in transmission by specifying the Message Fragment Delivery Delay time (in milliseconds).

User's Guide
Java™ 2 Platform, Micro Edition, Wireless Toolkit, Version 2.1

Chapter 7