Oracle® Java Micro Edition Software Development Kit Developer's Guide Release 3.0.5 for Windows E24265-04 |
|
Previous |
Next |
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.
Many of the tasks in this topic can also be accomplished from the command line. See Section 22.3, "Running WMA Tool" and Section 22.2.3, "Sending SMS Messages From WMA Console to an Emulator and Back".
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.
See Section 22.1.2, "WMA Console Interface".
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".
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.
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.
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.
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.
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.
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.
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.
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
.
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.
The application home screen shows the MIDlets you can launch: SMS Send, SMS Receive, CBS Received, MMS Send and MMS Receive.
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.
Choose Yes. The SMSReceive
MIDlet is launched and immediately displays the incoming SMS message.
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.)
This process is similar to sending SMS Messages. Instead of specifying a port number you specify a Message Identifier.
TTo launch the WMA console, select Tools > Java ME > WMA Console. To open the WMA Output window, select Window > Output > WMA Console Output.
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.
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.
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.
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.
Each command has its own arguments.
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:
C:\Java_ME_platform_SDK_3.0.5\bin>wma-tool smsreceive
WMA tool started with phone number: 123456803
press <Enter> to exit.
In the emulator run the SMS Send MIDlet and send a message to the WMA console. The console receives the message as follows:
SMS Received:
From: 123456789
Port: 50000
Content type: Text
Encoding: GSM7BIT
Content: from emulator to wma-tool
Waiting for another message, press <Enter> to exit.
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.
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.
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.
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.
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