Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



How to port GSM SMS applications to CDMA


Introduction

This document explains how applications written to use SMS over GSM on previous versions of Symbian OS can be changed to support SMS over CDMA. It contains the following sections:

[Top]


Overview

In previous versions of Symbian OS, the GSM SMS standard (ETSI, ETS 300 536 (GSM 03.40)) was supported through three components:

CDMA also supports an SMS standard, defined by the 3GPP2, in standard C.S0015-A, derived from the TIA/EIA standard, TIA/EIA-637-B. The GSM and CDMA standards define broadly similiar functionality, but are different in architecture and in data structures. To add support for CDMA SMS to Symbian OS has required the following changes:

In order not to break existing GSM SMS messaging applications, the new CDMA MTM maintains API compatibility with the previous GSM SMS MTM, despite this API having elements that are specific to GSM. In particular, the GSM SMS MTM CSmsHeader class exposes the GSM SMS stack class CSmsMessage to clients. The new MTM maintains compatibility with the old API by translating features that are common to both GSM and CDMA into CDMA. GSM-specific features are ignored.

The MTM also offers a new interface, created by extending some existing classes and adding some new classes, that provides:

The new interface does not expose either of the underlying GSM or CDMA SMS stacks, and is intended to be the primary API for SMS CDMA applications, rather than the lower-level SMS CDMA stack. Using the MTM API offers a simpler future approach to maintaining common application code between GSM and CDMA phones. This means that applications that previously used the GSM SMS stack API will need considerable changes to use the now preferred MTM API. Applications that previously used the GSM SMS MTM will need smaller changes to update to use the MTM's new classes.

For further information on the SMS standards and related Symbian OS components, see:

[Top]


Comparing GSM SMS and CDMA SMS

The following table provides a quick comparison of the GSM SMS and CDMA SMS standards.

Area

GSM

CDMA

Message types

GSM SMS defines six types (Protocol Data Unit (PDU) types) of SMS message:

  • Deliver: a message sent from the service center (SC) to the phone.

  • Submit: a message sent from the phone to the SC.

  • Deliver report: sent from the phone to inform the SC of a failure in a Delivered message.

  • Submit report: sent from the SC to inform the phone of a failure in a Submitted message.

  • Status report: sent from the SC to inform the phone of the status of a message previously submitted by the phone.

  • Command: sent from the phone to invoke an operation at the SC.

CDMA also defines six message types. Like GSM, it has Deliver and Submit types. The other types differ from GSM:

  • Deliver: message sent to the phone

  • Submit: message sent from the phone.

  • Cancellation: from the phone to the Message Center (MC) to cancel a submitted message.

  • User Acknowledgment: sent from a phone that has received a message to the submitter to inform it that the user has acknowledged the message.

  • Delivery Acknowledgment: sent from the MC to inform the phone of the status of a submitted message.

  • Read Acknowledgment Message: sent from a phone that has received a message to the submitter to inform it that the user has opened the message.

Application layer

A message can have a Protocol-Identifier field to specify a higher layer protocol being used. The standard does not define the operation of such protocols.

A message can have a Teleservice identifier to specify the application. The standard defines the operation of six teleservices.

The Wireless Messaging Teleservice (WMT) is for short text messaging between users. The Wireless Enhanced Messaging Teleservice (WEMT) extends this to include EMS elements such as pictures.

Other teleservices defined are: IS-91 Extended Protocol Enhanced Services, Wireless Paging Teleservice (WPT), Voice Mail Notification (VMN), and Service Category Programming Teleservice (SCPT).

Not all teleservices use all message types: for example, WPT does not support message cancellation, so does not use the Cancellation message type.

Enhanced messaging

The Enhanced Messaging Service (EMS) standard carries pictures, animations, sounds, and rich text in SMS messages.

Wireless Enhanced Messaging Teleservice (WEMT) carries EMS over CDMA SMS.

Character encoding

Alphanumeric text is encoded as 7-bit characters (GSM 03.38).

The encodings used can be specified in the message. Possible encoding types are listed in [3GPP2 C.R1001-C Table 9.1-1].

Point-to-Point\Broadcast

GSM SMS offers a one-to-one and one-to-a-few service.

In addition to a Point-to-Point service, CDMA SMS offers a broadcast service for sending a message to all phones in a defined area.

[Top]


CDMA SMS MTM classes

The following diagram shows the key classes in the CDMA SMS MTM:

Classes that existed in the GSM SMS MTM are in yellow; classes that are new are in blue; significant classes from components other than the MTM are in grey. The following table summarises the classes:

Class

Purpose

CSmsClientMtm

Implements the messaging architecture client MTM interface for SMS. It allows messages to be created, replied to, and forwarded, and MTM-specific commands to be given.

It provides an accessor function SmsHeader() to get the CSmsHeader for a message.

CSmsHeader

Encapsulates an SMS message.

In the GSM SMS MTM, this provided access to the GSM SMS stack's message class CSmsMessage and classes representing individual PDU types. For compatibility reasons, this interface is maintained in the CDMA SMS MTM.

In the new API added in the CDMA SMS MTM, the class provides access to the family of classes derived from TMsvMessageBio. These classes allow fields of a message to be set and accessed.

TMsvMessageBio

Base class for a family of classes that provide access to message fields.

Architecturally, the class provides a wrapper around the GSM SMS stack message class CSmsMessage. An instance of this class is used to store fields that are common to both GSM and CDMA, and for stroring GSM-specific fields.

TMsvMessageSms

Provides access to message fields that are compatible with both GSM and CDMA.

TMsvMessageGsm

Provides access to GSM-specific fields.

TMsvMessageCdma

Provides access to CDMA-specific fields.

Architecturally, the class provides a wrapper around the CDMA SMS stack message class CCdmaSmsMessage. An instance of this class is used to store fields that are specific to CDMA.

TMsvSmsEntry

Provides a specialisation of the message server index class TMsvEntry for SMS message entries.

Putting selected SMS-specific fields in the index entry allows message clients to quickly get important message properties without having to create a message object.

CSmsNumber

Encapsulates recipient information for an SMS message.

CSmsSettings

Defines settings for the SMS service.

It contains some GSM-specific functions to maintain compability with the GSM SMS MTM.

It also provides access to CSmsMessageSettingsProxy for outgoing message defaults.

CSmsMessageSettings

This is now deprecated and kept for backward compatibility.

CSmsMessageSettingsProxy

Provides defaults for outgoing messages, both GSM and CDMA.

It also provides access to an additional object for CDMA-specific settings, TSmsMessageSettingsCdma.

TSmsMessageSettingsCdma

Defines CDMA-specific settings for outgoing messages.

[Top]


CSmsMessage fields

CSmsMessage is the GSM SMS stack class that allows access to message properties such as addressing information, the message text itself, and to individual PDUs. Applications may previously have used CSmsMessage either directly with the GSM SMS stack API, or in conjunction with the GMS SMS MTM API. Both categories of application should now prefer to use only APIs offered by the CDMA MTM API.

The following table maps the CSmsMessage functions to equivalents in the MTM API. Sometimes there is no equivalent, either because the function is too low-level to have an appropriate equivalent in messaging, such as phone slot information, or because the function is concerned with GSM-specific features that have not been addressed in the current release of the MTM.

Description

CSmsMessage function

MTM API

Message type

Type()

The message type is represented as a TSmsMessageType. As seen in the previous GSM/CDMA comparison table, the two standards have different message types, so a range of values is provided to represent each. Constants beginning at KSmsTypeGsmOffset define GSM types; from KSmsTypeCdmaOffset define CDMA types.

The message type can be obtained using CSmsHeader::MessageType().

Message is complete

IsComplete()

Not applicable. Note that the message index entry flag TMsvEntry::Complete() is not set or used by the MTM or standard watchers.

Message is decoded

IsDecoded()

SMS messages stored in the message server have always been decoded.

Store location and status

Storage(), SetStorage(), Status(), SetStatus()

Messages available through the MTM API have been stored in the message server's message store, so this is not relevant.

The MTM does offer commands however to copy/move messages between an R-UIM/SIM and the message store. IDs for these commands are given by TSmsMtmCommand.

Log Server Id

LogServerId(), SetLogServerId()

CDMA has a message identifier field that can be used in a similiar way. The identifier can be got through CSmsNumber::MessageId().

Time

Time(), SetTime()

For GSM, this is the message creation time. There is no CDMA equivalent.

Message PDU

SmsPDU()

This function gets a GSM-specific PDU type. Most of the fields accessed for these types are GSM specific, and have no equivalent in the MTM API. There a couple of exceptions to this, where both CDMA and GSM support the fields. In that case, the MTM API provides access to the fields through its common fields class TMsvMessageSms.

Service Center Address

ServiceCenterAddress(), SetServiceCenterAddressL(), ParsedServiceCenterAddress(), SetParsedServiceCenterAddressL()

Service center addresses are not used with CDMA, so these functions are not relevant for that network.

To and From addresses

ToFromAddress(), SetToFromAddressL(), ParsedToFromAddress(), SetParsedToFromAddressL()

Addresses on outgoing messages can be set through CSmsClientMtm using AddAddresseeL() and RemoveAddressee(), or through CSmsHeader's AddRecipientL() and RemoveRecipient().

The recipients of messages (ingoing or outgoing) can be accessed using CSmsHeader::Recipients(). Recipient information is encapsulated by CSmsNumber.

Text portion of the message

Buffer(), TextPresent()

The message text is available as a text object through the client MTM Body() function.

Message length

MessageLengthL(), MaxMessageLength()

The message text length can be found by getting the length of the text returned by the client MTM Body() function.

EMS

GetEMSInformationElementsL(), AddEMSInformationElementL(), RemoveEMSInformationElementsL(), RemoveEMSInformationElementL(), ResetEMSL(), CopyEmsElementsL()

EMS is a GSM specific feature that can be used over CDMA through the WEMT Teleservice. This is done through the wrapper class TMsvMessageSms. For details, see EMS in How to use the CDMA SMS MTM.

Email over SMS

AddEmailHeaderL(), IsEmailHeader(), GetEmailHeaderL()

Not currently available through the MTM API

PDUs and slots

NumMessagePDUsL(), EncodeMessagePDUsL() DecodeMessagePDUsL() EncodeIntoSinglePDUL() AddSlotL() MatchSlots()

Low level PDU and slot handling is not available through the MTM API.

User data settings

UserDataSettings(), SetUserDataSettingsL(), OptimizeSettingsL()

The settings are encapsulated in an TSmsUserDataSettings object, as described in the table below.

User Data Settings: TSmsUserDataSettings

Description

TSmsUserDataSettings function

MTM API

Character encoding

Alphabet(), SetAlphabet()

The character encoding can be got and set using TMsvMessageBio::Encoding() and TMsvMessageBio::SetEncoding() respectively. These functions specify the encoding with an TSmsCharacterEncoding integer type.

Compression

TextCompressed(), SetTextCompressed()

Not applicable to MTM API.

Concatenation

TextConcatenated(), SetTextConcatenated()

Not applicable to MTM API.

Message waiting indication

IndicationState(), IndicationType()

Not available through the MTM API.

Class

Class()

Not applicable to CDMA MTM API.

[Top]


GSM SMS stack sockets

The GSM SMS stack API has two libraries:

Before you can do any operations with the MTM, your program must perform a couple of set up steps:

Sending messages

If you use the GSM SMS stack API, your program will probably follow a procedure such as this to send an SMS:

  1. Set up a message to send in a CSmsMessage object:

    • create a CSmsBuffer buffer, and store in it the message text

    • create a CSmsMessage to encapsulate the message

    • set the message properties, such as user data settings, destination address, and service center address, using CSmsMessage functions

  2. Prepare a socket to send the message:

    • open a socket of the KSMSAddrFamily protocol type

    • create a TSmsAddr with address family ESmsAddrSendOnly, and bind this to the socket

    • open a write stream RSmsSocketWriteStream on the socket, write the CSmsMessage to this stream, and commit the stream

  3. Send the message by issuing an socket ioctl command KIoctlSendSmsMessage

The comparable procedure for a program using the messaging API is:

  1. Create a CMsvEntry message entry, and initialising it appropriately. For details, see Message creation in How to use the CDMA SMS MTM.

    You can also create new messages by forwarding or replying to an existing SMS message, through CSmsClientMtm::ForwardL() and CSmsClientMtm::ReplyL() respectively. In these cases, the new message is created for you, with the appropriate content copied into it from the original message.

  2. Set the message content and properties using CSmsClientMtm, and where necessary, CSmsHeader, and for CDMA-specific fields, TMsvMessageCdma. The following sets the message text, adds an address, and sets the (CDMA-specific) priority field.

        // set body text
        CRichText& body = iSmsClientMtm->Body();
        _LIT(KMsgText,"message text");
        body.InsertL(0,KMsgText);
                        
        // set recipients
        _LIT(KNum,"6238263876");
        iSmsClientMtm->AddAddresseeL(KNum);
            
        // set any protocol-specific fields
        TMsvMessageCdma& cdma = iSmsClientMtm->SmsHeader().CdmaMessage();
        cdma.SetPriorityIndicatorL(tia637::KBdUrgent);
        
        // save message before sending
        iSmsClientMtm->SaveMessageL();

  3. Send the message: once a message has been set up, it can be sent by copying the message to the SMS service. This can be done using CMsvEntry::CopyL(). The following copies the message, whose ID is obtained using iSmsClientMtm->Entry().EntryId(), to the service, whose ID can be got from the MTM using ServiceId().

    iSendOperation = ent->CopyL(iSmsClientMtm->Entry().EntryId(), iSmsClientMtm->ServiceId(), iStatus);

    The function returns a CMsvOperation object, which can be used to monitor the sending progress (TSmsProgress) and to obtain any error information.

Receiving messages

As well as sending messages, both the GSM SMS stack API and the MTM API can be used to get incoming messages. As a reminder, the GSM SMS stack procedure to get incoming messages is:

Messaging receives SMS messages through a number of watcher components that listen to the CDMA stack for incoming messages that belong to particular teleservices (WMT, WEMT, VMN, WPT). When an incoming message belonging to one of these teleservices is received, its contents are read, and a new entry for the message is created in the message server's store (in the global inbox folder). The usual case is that these messages will then be read by the user through the email application, but other messaging clients can receive notifications when a new message is created in the store, and process the message if appropriate.

To do this, a class must must implement the session observer interface MMsvSessionObserver. The interface has just one function:

void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0;

When a new message is created in the store, the framework calls this function with aEvent set to EMsvEntriesCreated, and aArg1 is set to a CMsvEntrySelection* that specifies the IDs of the entries that have been created. The following checks the event type, and gets the entry ID selection:

void CClientApp::HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* , TAny* )
    {
    CMsvEntrySelection* entries = NULL;

    switch (aEvent)
        {
        case EMsvEntriesCreated:
            entries = static_castCMsvEntrySelection*>(aArg1);
            break;
        default:
            break;
        }

The observer will receive notifications for all types of entry, not just SMS, so it's necessary to read the message properties to check that the entry is appropriate to process. The following code first checks the index entry to see if the entry is an SMS message, and then reads the message's CSmsHeader to see if it is of the Deliver (i.e. incoming) type. Further checks, e.g. for particular message content, could be made. If you determine that your application should process the message, you can prevent the user from seeing the message in the Inbox of the standard messaging application. To do this, set the message entry's visible flag to false, using TMsvEntry::SetVisible(EFalse).

    if (entries != NULL)
        {
        TInt count = entries->Count();

        // check each entry to see if we want to process it
        while (count--)
            {
            // get the index entry
            const TMsvId id = (*entries)[count];
            iEntry->SetEntryL(id);
            const TMsvEntry& entry = iEntry->Entry();
            // if the entry is an SMS message
            if (entry.iMtm == KUidMsgTypeSMS && entry.iType == KUidMsvMessageEntry)
                {
                // and if it's an incoming message
                iSmsClientMtm->SwitchCurrentEntryL(id);
                CSmsHeader& header = iSmsClientMtm->SmsHeader();
                if (header.MessageType() == KSmsTypeDeliver) 
                    {
                    // make the entry invisible
                    TMsvEntry changeEnt(entry);                    
                    changeEnt.SetVisible(EFalse);
                    iEntry->ChangeL(changeEnt);
                    // do something with the message
                    HandleReceivedMessageL(id);
                    }
                }               
            }
        }

Phone store commands

The GSM SMS MTM offered a range of extension commands called through CSmsClientMtm::InvokeAsyncFunctionL() to copy/move messages between a phone store and the message store. The CDMA SMS MTM uses the same commands to manage message storage on the phone store or R-UIM. A new class TMsvSmsSimOperationParams is defined to specify parameters for the commands.

[Top]


Send As

SMS messages can be created using the messaging Send As API in the same way for the CDMA SMS MTM as for the GSM SMS MTM. No changes to calling code are required.

For CDMA-only phones, the message is created as a generic SMS Text, and sent as a Wireless Messaging Teleservice (WMT) message. Other settings are taken from the defaults specified by the current service and message settings (see SMS services).

[Top]


MTM API change summary

This section summarises the API differences between the GSM SMS MTM and the CDMA SMS MTM.

Headers

The following headers are new in the CDMA SMS MTM:

File

Contents

Smsstd.h

Enums, typedefs, and constants that define settings values including:

SmsSettings.h

New classes to handle settings: CSmsMessageSettingsProxy, TSmsMessageSettingsGsm, TSmsMessageSettingsCdma.

SmsMessageWrappers.h

New classes that provide a wrapper layer above the underlying GSM or CDMA SMS stacks: TMsvMessageBio, TMsvMessageCdma, TMsvMessageGsm and TMsvMessageSms.

Modified types

The following types have had items or values added relative to the GSM SMS MTM:

CSmsHeader

Purpose

Function

Creation: new NewL() overloads are added to create objects for a particular message type, where the message type is specified in a common GSM/CDMA format.

The second overload allows a CDMA teleservice to be specified.

NewL(CEditableText& aText, TSmsMessageType aMessageType);

NewL(CEditableText& aText, TSmsMessageType aMessageType, tia637::TTeleserviceId aTeleservice);

Message type: the TSmsMessageType value returned is capable of representing both CDMA and GSM message types.

MessageType()

Message direction: this is required because some message types in CDMA are bi-directional.

MessageBearing()

Bearer (CDMA or GSM) of the message.

SmsBearer()

Generic SMS message fields accessor

BioMessageL(),SmsMessageL()

GSM-specific SMS message fields accessor

GsmMessageL()

CDMA-specific SMS message fields accessor

CdmaMessage()

Acknowledgement options: when a CDMA SMS message is sent, a number of different types of acknowledgement can be requested from the receiver. These functions allow these request options to be accessed.

AcknowledgementRequested(), SetAcknowledgementRequest()

An additional utility function to search through the list of recipients either using the phone number or the message identifer.

FindRecipient()

CSmsSettings

Purpose

Function

CDMA default teleservice

DefaultTeleservice(), SetDefaultTeleservice()

CDMA alert on delivery

AlertOnDelivery(), SetAlertOnDelivery()

CDMA preferred languages

PreferedLanguageList()

CDMA message display mode

MessageDisplayMode(), SetMessageDisplayMode

CDMA digit mode

DigitMode(), SetDigitMode()

Gets CSmsMessageSettingsProxy message settings

MessageSettings()

Handling of original message in replies

ReplyWithOriginalMessage(), SetReplyWithOriginalMessage()

CSmsNumber

Purpose

Function

Gets a message identifier for the recipient.

MessageIdentifier()

CDMA user acknowledgement

SetUserAck(), UserAck()