22 JSRs 120 and 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.

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

Note, WMA console operations can also be performed from the command line. See Section 22.3, "Running WMA Tool".

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

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

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

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

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

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 Section 22.2.2, "Running WMADemo OTA".

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

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

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

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

   Supply a Message Identifier of 50001.

   Type your text message or attach a binary message and click on 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.

   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.

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

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

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

4. Click on Send to send the message.

   The image and its information are displayed in the emulator.

22.3.1 smsreceive

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

-o outputDir. Store binary contents to outputDir.

-t timeout. Non-interactive mode, waits only timeout seconds for messages.

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

-q Quiet mode.

Example

Start the emulator from the bin directory:

emulator.exe -Xdevice:DefaultCldcPhone1 -Xdescriptor:..\apps\WMADemo\dist\WMADemo.jar

Start wma-tool from the bin directory:

In the emulator run the SMS Send MIDlet and send a message to the WMA console. The console receives the message as follows:

22.3.2 cbsreceive

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

-o outputDir. Store binary contents to outputDir.

-t timeout. Non-interactive mode, waits only timeout seconds for messages.

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

-q Quiet mode.

22.3.3 mmsreceive

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

-o outputDir. Store binary contents to outputDir.

-t timeout. Non-interactive mode, waits only timeout seconds for messages.

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

-q Quiet mode.

22.3.4 smssend

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.

22.3.5 cbssend

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.

22.3.6 mmssend

mmssend <application id> <subject>
     [-to <targetphone>]* [-cc <target phone>]* [-bcc <targetphone>]*
     [-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 variable:

• text

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

• -to target_phone

  "to" target phone number. Any number of these options can be used.

• -cc target_phone

  "cc" target phone number. Any number of these options can be used.

• -bcc target_phone

  "bcc" target phone number. Any number of these options can be used.

Part from Text Options

Separate options with semicolons. For example:

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

  Appends text part to the message. Any number of these arguments can be used. 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. Any number of these arguments can be used.

  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:

mmssend MyAppId MySubject -to 987654321
     -part text="text part" -part file=Duke.png:mimeType=image/png