Using the Wireless Messaging API 2.0

The Wireless Messaging API 2.0 has added support for MMS messaging. To properly use MMS, new classes are required that are suitably to this type of messaging. Thus, WMA 2.0 includes the class javax.wireless.messaging.MultipartMessage, which represents an MMS instance, and the class javax.wireless.messaging.MessagePart, which contains a single message part of the many that may compose a given message's body, as explained in the previous section.

Creating multipart messages

Multipart messages are richer than normal text messages and this functionality is represented in the MultipartMessage class. For example, the class includes methods to specify multiple destination addresses including the type "cc" and "bcc" addresses. This class also contains methods to manage the values of the message's headers and methods to add and remove message parts. The MessagePart class represents the actual contents of the MMS and contains the body of the message part, its MIME type, and its content-Id.

Finally, WMA2.0 extends MessageConnection to support MultipartMessages and specifies the type of URLs used to create MMS-oriented MessageConnections.

To send and receive MMS messages using WMA 2.0, you have to create a MessageConnection instance using the Generic Connection Framework. To do so you need to create an appropriate URL using the following format:

mms://{target}

The target can be a phone number, an IP address, e -mail address, and so on when creating a client-side connection, or alternatively indicate a local endpoint when creating a server-side MessageConnection. The URL may contain an application-ID that is used to identify a particular application in a similar way as port numbers are used when sending SMS messages. It is recommended to give your MIDlet an application-ID if it is desired to receive or send MMS messages to specific endpoints. Examples of valid MMS URLs are:

// to send a message to the default application
mms://+569037202
// to send a message to a specific application mms://+569037202:applicationID
// server-side connection to send or receive message
mms://:applicationID

Sending multipart messages

The sending of MMS messages is done by creating a MessageConnection, then creating a MultipartMessage, adding the message's parts, and finally calling the send method as follows:

MessageConnection connection =
   (MessageConnection)Connector.open("mms://:myapp");
MultipartMessage msg = (MultipartMessage) connection
   .newMessage(MessageConnection.MULTIPART_MESSAGE);
// add the parts to the message
msg.addMessagePart(textPart);
msg.setAddress(recipientAddress);
connection.send(msg);

Each message part can be created directly from a byte array representation of the part's body or read from InputStream. Additionally, it is necessary to specify the part's ID and MIME type.

Receiving multipart messages

The receiving of messages is done by creating a server-side connection and setting up MessageListener. The code snippet below shows the creation of such a connection and listener:

String mmsUrl = "mms://:application-ID";
connection = (MessageConnection) Connector.open(mmsUrl);
connection.setMessageListener(listener);

The listener will then be called whenever a new message sent to application-id is received. This highlights the need to specify a proper application-ID for your MIDlet if you need this functionality. When a message is received, it can be read using the receive method as follows:

Message incomingMessage = connection.receive();

Notice that many of the calls to MessageConnection should be done in a different thread than the user interface thread since operations involving sending or receiving messages may take a while. Additionally, due to the MIDP 2.0 security model, the device may request the user to give explicit permission to send or receive messages. If the calls to MessageConnection are done in the UI thread, it is possible to create a deadlock when the user permission is requested.

Security

Use of the messaging features of WMA 2.0 is subject to security restrictions. WMA 2.0 defines several permissions that a MIDlet needs to acquire to use the underlying messaging engine. For more information about permissions, see the WM API 2.0 specification and the Wireless Messaging API (JSR-205): Implementation Notes.

© Nokia 2008.