|
||
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:
Overview describes the architectural changes made to support SMS over CDMA.
Comparing GSM SMS and CDMA SMS describes some key differences between the SMS standards on GSM and CDMA.
CDMA SMS MTM classes provides a brief overview of the API, and identifies the new classes.
CSmsMessage fields analyses
how to move from the low-level GSM SMS stack CSmsMessage
class to
the messaging MTM API.
GSM SMS stack sockets describes how to move from using the sockets client with the GSM SMS stack to the messaging MTM API
Send As describes compatibility between GSM and CDMA for SendAs API users
MTM API change summary summarises the changes between the CDMA SMS MTM and the GSM SMS MTM.
In previous versions of Symbian OS, the GSM SMS standard (ETSI, ETS 300 536 (GSM 03.40)) was supported through three components:
The ETel multimode API, for low-level access to the phone drivers
The SMS (narrow band protocols) stack subsystem, which offered an encapsulation of a GSM SMS message, together with the ability to send and receive messages
The messaging SMS MTM, which integrated SMS into the messaging architecture, so that SMS could be used in a messaging client in a similar way to email, fax, etc.
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:
A new, additional SMS stack for CDMA. This provides an encapsulation of a CDMA SMS message, and message sending and receiving.
A new messaging SMS MTM that supports CDMA SMS.
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:
a single interface to the functionality that GSM and CDMA SMS have in common.
extensions to the common interface that allows access to GSM and CDMA specific functionality.
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:
SMS Stack
SMS standard on ETSI website (requires registration).
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:
|
CDMA also defines six message types. Like GSM, it has Deliver and Submit types. The other types differ from GSM:
|
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. |
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 |
|
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 |
|
Encapsulates an SMS message.
In the GSM SMS MTM, this provided access to the GSM SMS stack's
message class
In the new API added in the CDMA SMS MTM, the class provides
access to the family of classes derived from |
|
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 |
|
Provides access to message fields that are compatible with both GSM and CDMA. |
|
Provides access to GSM-specific fields. |
|
Provides access to CDMA-specific fields.
Architecturally, the class provides a wrapper around the CDMA SMS
stack message class |
|
Provides a specialisation of the message server index class
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. |
|
Encapsulates recipient information for an SMS message. |
|
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
|
|
This is now deprecated and kept for backward compatibility. |
|
Provides defaults for outgoing messages, both GSM and CDMA.
It also provides access to an additional object for CDMA-specific
settings, |
|
Defines CDMA-specific settings for outgoing messages. |
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 |
|
The message type is represented as a
The message type can be obtained using
|
Message is complete |
|
Not applicable. Note that the message index entry flag
|
Message is decoded |
|
SMS messages stored in the message server have always been decoded. |
Store location and status |
|
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
|
Log Server Id |
|
CDMA has a message identifier field that can be used in a
similiar way. The identifier can be got through
|
Time |
|
For GSM, this is the message creation time. There is no CDMA equivalent. |
Message PDU |
|
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
|
Service Center Address |
|
Service center addresses are not used with CDMA, so these functions are not relevant for that network. |
To and From addresses |
|
Addresses on outgoing messages can be set through
The recipients of messages (ingoing or outgoing) can be accessed
using |
Text portion of the message |
|
The message text is available as a text object through the client
MTM |
Message length |
|
The message text length can be found by getting the length of the
text returned by the client MTM |
EMS |
|
EMS is a GSM specific feature that can be used over CDMA through
the WEMT Teleservice. This is done through the wrapper class
|
Email over SMS |
|
Not currently available through the MTM API |
PDUs and slots |
|
Low level PDU and slot handling is not available through the MTM API. |
User data settings |
|
The settings are encapsulated in an
|
TSmsUserDataSettings
Description |
TSmsUserDataSettings function |
MTM API |
Character encoding |
|
The character encoding can be got and set using
|
Compression |
|
Not applicable to MTM API. |
Concatenation |
|
Not applicable to MTM API. |
Message waiting indication |
|
Not available through the MTM API. |
Class |
|
Not applicable to CDMA MTM API. |
The GSM SMS stack API has two libraries:
gsmu.lib
, which provides the message encapsulation
class CSmsMessage
and PDU classes.
The CSmsMessage
class is discussed in the
CSmsMessage
fields table above.
smsu.lib
, which provides utility classes that allow
clients to use the sockets client API to send and receive SMS messages and give
commands related to the SIM.
This section explains how to change from using the sockets client API to the MTM API to send and receive messages.
Before you can do any operations with the MTM, your program must perform a couple of set up steps:
Connect to the message server: the messaging framework is based
around a server program, to which a connection (a session) must be made before
anything else with messaging can be done. The session class is called
CMsvSession
, and message client applications typically
create an instance of this class upon start-up.
// Create message server session
iMsvSession = CMsvSession::OpenSyncL(*this);
The OpenSyncL()
method takes a parameter of type
MMsvSessionObserver
, so, for this code to work, the
containing class must implement this observer interface. It enables the server
to call the client to inform it of significant events, such as new MTMs being
registered.
Get the SMS Client MTM: an application cannot directly create a
CSmsClientMtm
object. Instead, it must ask the message
server to create the object for it. A record of all the MTM components
installed on a machine is held in a dedicated registry file managed by the
message server. Registry classes use this registration data to allow MTM
components to be identified and instantiated.
To get a SMS client MTM object, use
CClientMtmRegistry
as follows:
// Create client registry object
iClientMtmRegistry = CClientMtmRegistry::NewL(*iMsvSession);
// Request MMS client MTM object
iSmsClientMtm = (CSmsClientMtm *)iClientMtmRegistry->NewMtmL(KUidMsgTypeSMS);
The registry NewMtmL()
function returns a pointer to
the client MTM base class, CBaseMtm
, so I cast it to the
SMS client class, CSmsClientMtm
.
If you use the GSM SMS stack API, your program will probably follow a procedure such as this to send an SMS:
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
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
Send the message by issuing an socket ioctl command
KIoctlSendSmsMessage
The comparable procedure for a program using the messaging API is:
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.
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();
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.
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:
Prepare a socket to get incoming messages:
open a socket of the KSMSAddrFamily
protocol type
create a TSmsAddr
, and set its address family to a
method of recognizing which incoming messages should be handled. A typical
method is match a text pattern against the incoming message. Bind the address
to the socket.
start listening for messages by issuing a socket ioctl command
KIoctlSelect
When a message that matches the handling criterion is received:
create an empty buffer (CSmsBuffer
) and
message (CSmsMessage
) object
read the message into the message object using
RSmsSocketReadStream
.
acknowledge that the message has been received successfully by
issuing a socket ioctl command KIoctlReadMessageSucceeded
(or
KIoctlReadMessageFailed
on failure)
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);
}
}
}
}
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.
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).
This section summarises the API differences between the GSM SMS MTM and the CDMA SMS MTM.
The following headers are new in the CDMA SMS MTM:
File |
Contents |
|
Enums, typedefs, and constants that define settings values including:
|
|
New classes to handle settings:
|
|
New classes that provide a wrapper layer above the underlying GSM
or CDMA SMS stacks: |
The following types have had items or values added relative to the GSM SMS MTM:
CSmsHeader
Purpose |
Function |
Creation: new The second overload allows a CDMA teleservice to be specified. |
|
Message type: the |
|
Message direction: this is required because some message types in CDMA are bi-directional. |
|
Bearer (CDMA or GSM) of the message. |
|
Generic SMS message fields accessor |
|
GSM-specific SMS message fields accessor |
|
CDMA-specific SMS message fields accessor |
|
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. |
|
An additional utility function to search through the list of recipients either using the phone number or the message identifer. |
|
CSmsSettings
Purpose |
Function |
CDMA default teleservice |
|
CDMA alert on delivery |
|
CDMA preferred languages |
|
CDMA message display mode |
|
CDMA digit mode |
|
Gets |
|
Handling of original message in replies |
|
CSmsNumber
Purpose |
Function |
Gets a message identifier for the recipient. |
|
CDMA user acknowledgement |
|