Package com.nokia.mid.messaging

Sending and receiving messages As usual with the Generic Connection Framework, the message sending and receiving functionality is implemented by a Connection interface, in this case MessageConnection.

See:
          Description

Interface Summary
BinaryMessage An interface representing a binary message Object instances implementing this interface are just containers for the data that is passed in.
Message Base interface representing a message This interface contains the functionality common to all messages.
MessageConnection The MessageConnection interface defines the basic functionality for sending and receiving message.
MessageListener The MessageListener interface is an interface that can be implemented by a class of the application to get notified of incoming messages.
TextMessage An interface representing a text message Object instances implementing this interface are just containers for the data that is passed in.
 

Package com.nokia.mid.messaging Description

Sending and receiving messages

As usual with the Generic Connection Framework, the message sending and receiving functionality is implemented by a Connection interface, in this case MessageConnection.

The application obtains an object implementing the MessageConnection from the Connector class by providing a URL like string that identifies the address.

If the application specifies an full address that defines a recipient to the Connector, it gets a MessageConnection that works in a 'client' mode. This kind of Connection can only be used for sending messages to the address specified when creating it.

The application can create a 'server' mode MessageConnection by providing a URL string that includes only an identifier that specifies the messages intended to be received by this application. Then it can use this MessageConnection object for receiving and sending messages.

The MessageConnection object provides also factory methods for creating Message objects for sending.

For receiving messages, the MessageConnection supports also an event listener based receive mechanism, in addition to synchronous blocking receive() method.

Note that the methods for sending and receiving messages may throw a SecurityException. This is thrown if the application does not have the permission for those operations. The end user is prompted to give a permission to send messages. Sending messages to certain reserved port numbers is prohibited and will throw a SecurityException always.

GSM SMS message structure

The GSM SMS messages are defined in the GSM 03.40 standard [1]. The message consists of a fixed header and a field called TP-User-Data that carries the payload of the short message as well as optional header information that is not part of the fixed header. The optional headers are contained in a field called User Data Header and the presence of such headers in the TP-User-Data field is indicated in a separate field that is part of the fixed header.

The TP-User-Data can be encoded using different encodings depending on the type of the payload content. Possible encodings are a 7-bit alphabet defined in the GSM 03.38 standard, 8-bit binary data or 16-bit UCS-2 alphabet.

The maximum length of the one SMS protocol message payload depends on the encoding and whether there are optional headers present in the TP-User-Data field. This Java API uses the port numbers to distinguish to which application a message is targeted at, when sending messages that are intended to be received by a Java application instead of them being displayed to the end user as usual. The presence of the optional header for the port number causes the payload that fits into the SMS protocol message to be smaller.

The messages that the Java application sends may be longer than fits in a single SMS protocol message. In this case, the implementation uses the concatenation feature specified in sections 9.2.3.24.1 and 9.2.3.24.8 of the GSM 03.40 standard for splitting the payload of the message given to the Java API into multiple SMS protocol messages. Similarly, when receiving messages, the implementation concatenates automatically the received SMS protocol messages and passes the full reassembled payload to the application via the API.

Implementations of this API shall support at least 3 SMS protocol messages to be received and concatenated together. Similarly for sending, messages that can be sent with up to 3 SMS protocol messages shall be supported. Depending on the implementation, these limits may be higher. However, applications are advised not to send messages that will take up more than 3 SMS protocol messages, unless they have reason to assume that the recipient will be able to handle a larger number.

The following table gives the number of SMS protocol messages for each payload length in each case:

        Optional headers
Encoding
No port number present
(message to be displayed to the end user)
Port number present
(message targeted at an application)
Length SMS messages Length SMS messages
GSM 7-bit alphabet 0...160 chars 1 0...152 chars 1
161...304 chars 2 153...290 chars 2
305...266 chars 3 291...435 chars 3
8-bit binary data 0...140 bytes 1 0...133 bytes 1
141...266 bytes 2 134...254 bytes 2
267...399 bytes 3 255...381 bytes 3
UCS-2 alphabet 0...70 chars 1 0...66 chars 1
71...132 chars 2 67...126 chars 2
133...198 chars 3 127...189 chars 3

Addressing

The URL strings that specify the address use the following syntax:

smsurl ::== "com.nokia.sms://" address_part
address_part ::== foreign_host_address | local_host_address
local_host_address ::== port_number_part
port_number_part ::== ":" digits
foreign_host_address ::== msisdn | msisdn port_number_part
msisdn ::== "+" digits | digits
digit ::== "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
digits ::== digit | digit digits

Examples of valid URLs are:

com.nokia.sms://+358401234567
com.nokia.sms://+358401234567:6578
com.nokia.sms://:3381

In the address, the MSISDN part identifies the recipient phone number and the port number part the application port number address as specified in the GSM 3.40 SMS specification (sections 9.2.3.24.3 and 9.2.3.24.4). The same mechanism is used e.g. for the WAP WDP messages.

When the port number is present in the address, the TP-User Data of the SMS shall contain a User-Data-Header with the Application port addressing scheme information element.

When the recipient address does not contain a port number, the TP-User Data shall not contain the Application port addressing header. It is not possible for Java applications to receive this kind of messages, but they will be handled as normally in the recipient device, e.g. text messages will be displayed to the end user.

Messages can be sent using this API via 'client' or 'server' type MessageConnections. When a message identifying a port number is sent from a 'server' type MessageConnection, the originating port number in the message is set to the port number of the MessageConnection and thus the recipient can send a response to the message that will be received by this MessageConnection.

However, when a 'client' type MessageConnection is used for sending a message with a port number, the originating port number is set to an implementation specific value and any possible messages received to this port number are not delivered to the MessageConnection.

Thus, only the 'server' mode MessageConnections can be used for receiving messages and any messages to which the other party is expected to respond should be sent using the appropriate 'server' mode MessageConnection.

When SMS messages are received by an application, they are removed from the SIM / ME memory where they may have been stored. If an application wishes to save the message information more persistently, the application should handle the saving of the information itself e.g. using the RMS facility of the MIDP API or any other available mechanism.

Using port numbers

The receiving application in a device is identified with the port number included in the message. When opening the 'server' mode MessageConnection, the application specifies the port number that it will use for receiving messages.

The first application to allocate a given port number will get it and if subsequently other applications try to allocate the same port number while it is being used by the first application, the other applications will get an exception thrown when trying to open the MessageConnection. The same rule applies if some port number is being used by a system application in the device; in this case, the Java applications will not be able to use that port number.

As specified in the GSM 03.40 standard [1], the port numbers are split into ranges and there is a range that is controlled by IANA (the Internet Assigned Numbers Authority). If an application author wants to be sure that his application can always use some port number value, he can register a port number with IANA. Otherwise, he can just pick a number at random from the freely usable range and hope that the same number is not used by other applications at least such that would be installed in the same device as his application. This is exactly the same way as port numbers are used with TCP and UDP in the Internet currently.

Message types

SMS messages can be sent using the TextMessage or the BinaryMessage message type of the API. The encodings used in the SMS protocol are defined in the GSM 03.38 standard [2].

When the application uses the TextMessage, the TP-Data-Coding-Scheme in the SMS shall indicate the GSM default 7-bit alphabet or UCS-2 and the TP-User-Data shall be encoded appropriately using the chosen alphabet. The 7-bit alphabet shall be used for encoding if the String that is given by the application only contains characters that are present in the GSM 7-bit alphabet. If the String given by the application contains at least one character that is not present in the GSM 7-bit alphabet, the UCS-2 encoding shall be used.

When the application uses the BinaryMessage, the TP-Data-Coding-Scheme in the SMS shall indicate 8-bit data.

The application is responsible to keep the message payload such that it fits in an SMS message when encoded as defined in this specification. If the application tries to send a message with a too long payload, the MessageConnection.send() method will throw an exception and the message is not sent. This specification contains the necessary information for applications to be able to determine what is the maximum payload for the kind of message they are trying to send.

All messages sent via this API shall be sent as Class 1 messages.

Handling Received Messages when the MIDlet Is Not Running

The MIDP 2.0 (JSR118) will define the so-called "Push" mechanism that can be used to register the application so that it will be started when a message for it has been received.

Because this SMS API will be used in MIDP 1.0 based products, we define a similar mechanism based on an attribute in the JAD file for this purpose.

Syntax of the JAD file extension

The following extension may be placed in the JAD file to indicate that this MIDlet should be started when an SMS to the indicated port number is received.

Using the symbols defined in the BNF for application descriptors in section 8.5 of the MIDP 1.0 specification:

attrname: "Nokia-SMS-Handler-" n

where n shall be 1 for the first such attribute in the JAD file and the following such attributes in the same JAD file shall be numbered using consecutive ordinals.

attrvalue: SMS_URL WSP "," WSP description WSP "," WSP MIDlet_class

where SMS_URL is the URL as specified above, including the port number but not an MSISDN number (i.e. a URL for "server mode" connection).
description is descriptive text describing this connection (i.e. text suitable to be presented to the end user in some configuration / debugging cases)
MIDlet_class is the name of the MIDlet class that will be started to handle the messages to the indicated port number. This class name shall be such that the same class appears in one of the "MIDlet-" attributes in the same JAD file.
WSP is possible whitespace as defined in section 8.5 of the MIDP 1.0 specification.

The following line provides an example of the attribute line that could be included in the JAD file:

Nokia-SMS-Handler-1: com.nokia.sms://:7685, Chess move SMS, com.nokia.chess.Chess

Behaviour for receiving SMS messages for application

When the application is running and has opened the MessageConnection with the appropriate URL, the application will receive the incoming messages immediately as specified for the API.

When the application is not running and an SMS is received where the port number matches one of the port numbers indicated in a JAD file for a MIDlet, the implementation shall start the MIDlet indicated in the JAD file.

It is implementation specific how exactly this happens and it is not required to immediately pre-empt the application the user is currently using. The behaviour is intended to be similar to when a normal SMS arrives to the user (i.e. this notification is shown to the user at an appropriate time, but does not necessarily immediately pre-empt the application that the user is currently using). The implementation is also allowed to show a notification to the user asking for user confirmation before actually starting the MIDlet. The exact details how this happens are to be defined in the appropriate UI specification.

When the MIDlet is started, it is the responsibility of the MIDlet to open the MessageConnection with the same URL. When it does so, the messages that have been queued for it are delivered as defined in the API documentation.

If the application does not retrieve the messages (e.g. because the user denied starting the application or the application just does not call the API methods to receive the messages even after having been started), the implementation is allowed to delete the queued messages at an implementation-determined time. However, the implementation naturally needs to give the application reasonable time to retrieve the messages when it has been started.

Examples of Usage

This section provides some examples how the API can be used:

Sending a text message to an end user

The following example code sends the string "Hello World!" to an end user as a normal SMS.

try {
    String addr = "com.nokia.sms://+358401234567";
    MessageConnection conn = (MessageConnection)Connector.open(addr);
    TextMessage msg =   
       (TextMessage)conn.newMessage(MessageConnection.TEXT_MESSAGE);
    msg.setPayloadText("Hello World!");
    conn.send(msg);
} catch (Exception e) {
  ...
}

A server that responds to received messages

The following example code illustrates a server application that waits for messages sent to port 5432 and responds to them.

try {
    String addr = "com.nokia.sms://:5432";
    MessageConnection conn = (MessageConnection)Connector.open(addr);
    Message msg = null;
    while (someExitCondition) {
        // wait for incoming messages
        msg = conn.receive();
        // received a message
        if (msg instanceof TextMessage) {
            TextMessage tmsg = (TextMessage)msg;
            String receivedText = tmsg.getPayloadText();
            // respond with the same text with "Received:" inserted
            // in the beginning
            tmsg.setPayloadText("Received:" + receivedText);
            // Note that the recipient address in the message is
            // already correct as we are reusing the same object
            conn.send(tmsg);
        }
        else {
           // Received message was not a text message, but e.g. binary
           ... 
        }
    }
} catch (Exception e) {
   ...
}


forum.nokia.com/java

Copyright (c) 2002 Nokia Mobile Phones. All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc.