19 JSR 205: Wireless Messaging

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.

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.

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.

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

  Example:

  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.

  Example:

  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.

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

Example:

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