22 JSR 205: Wireless Messaging

22.1.1 Launching the WMA Console

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

The console opens as a tab in the NetBeans 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. In the Device Selector, right-click the CLDC, Java(TM) ME Platform SDK 3.3 node in the device selector, and select Properties. Type a new value in the WMA Console Phone Number 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 NetBeans IDE.

22.1.2 WMA Console Interface

To open the WMA Output window, select Window > Output > WMA Console Output. This window displays messages received from an emulator. By default it is docked at the bottom of the NetBeans IDE.

Figure 22-1 WMA Console and Output Windows

Description of "Figure 22-1 WMA Console and Output Windows"

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

22.1.4 Sending a Text or Binary SMS Message

To launch the WMA console, select Tools > Java ME > WMA Console. To open the WMA Output window, select Window > Output > WMA Console Output.

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 "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 "Sending SMS Messages From WMA Console to an Emulator and Back."

22.1.5 Sending Text or Binary CBS Messages

Sending CBS messages is similar to Section 22.1.4, "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 "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.

To try this yourself see "Sending CBS Messages from WMA Console to an Emulator."

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 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. Click Add 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 Add 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 "WMADemo Push Registry Values").

  To remove a part, select it and press Remove.

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

22.1.7 Receiving Messages in the WMA Console

To start the WMA console, select Tools > Java ME > 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.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 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 uses the push registry, you cannot see all of its features with the regular execution process. You must install the application into the emulator using the over the air provisioning capability that mirrors how applications are installed on external devices.

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

2. Select the Running Category and select the Execute through OTA option. Click OK.

3. Run WMADemo in an emulator.

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

   The application home screen shows the MIDlets you can launch: SMS Send, SMS Receive, CBS Receive, MMS Send and MMS Receive.

4. Launch the WMA console (see "Launching the WMA Console").

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.

1. 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 "Running WMADemo OTA."

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

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

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.

1. To launch the WMA console, select Tools > Java ME > WMA Console. To open the WMA Output window, select Window > Output > WMA Console Output.

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

   Supply a Message Identifier of 50001.

   Type your text message or attach a binary message and click Send.

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

   Select 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, ensure that WMADemo has been installed using Run Project via OTA.

1. From the WMADemo home screen, select 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. If you do not see the number you want, click the Add button to add it. When you have listed multiple numbers the number field is a dropdown list

   The To field on the left is a dropdown list from which you can choose To, Cc or Bcc.

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.

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

Example

This example demonstrates how to receive a message from an emulator.

1. Start the emulator from the Windows Start menu:

   Start > Programs > Java(TM) ME Platform SDK 3.3 > Java ME SDK CLDC Emulator.

   You can also start the emulator from the bin directory. This example also runs the WMADemo project.

   emulator.exe -Xdevice:JavaMEPhone1 -Xdescriptor:"C:\Documents and Settings\username\My Documents\NetBeansProjects\WMADemo\dist\WMADemo.jad"

2. Start wma-tool from the Java ME SDK installdir\bin directory:

   
   C:\Java_ME_platform_SDK_3.3\bin\wma-tool smsreceive

WMA tool started with phone number: 987654321
press <Enter> to exit.
   

3. In the emulator run the SMS Send MIDlet and send a message to the WMA console. Enter the console telephone number

   The console receives the message as follows:

   
   SMS Received:
From: 123456789
Timestamp: Thu Aug 23 23:31:26 PDT 2012
Port: 50000
Content type: Text
Encoding: GSM7BIT
Content: A message from JavaMEPhone1 to wma-tool
Waiting for another message, press <Enter> to exit.
   

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

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

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

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