SMS Tutorial

Required background

Before you start, you must understand:

• SMS MTM

• Schedule Send

• Message Server and Store

• Message Type Module

Introduction

The SMS MTM provides functionality for creating, storing and sending an SMS message, replying to a received SMS message and forwarding an existing SMS message. A reply to a received SMS message may include the original message text, including any EMS components. Configurable parameters can apply either at a global level or on an individual message basis. See SMS concepts for detailed information on how SMS functionality is implemented in the Symbian platform.

Global settings that are applied to the SMS MTM are known as SMS service settings. Each SMS message entry has its own individual group of settings known as SMS message settings. See SMS Settings for more information.

This tutorial explains how to create and send messages. It also explains how to handle incoming messages.

Creating and sending messages

1. Get a client MTM object.

2. Create a message.

3. Set the message body.

4. Set the message address.

5. Set the additional message fields, if required.

6. Send the message.

Get a client MTM object

The Messaging Framework is based around a server program to which a connection (a session) must be made before any operation on 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 sessioniMsvSession = CMsvSession::OpenSyncL(*this);

The OpenSyncL() method takes a parameter of type MMsvSessionObserver. 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.

Handling incoming messages

Messaging receives SMS messages through a number of watcher components. When a message is received its contents are read and a new entry for the message is created in the Message Store (in the global inbox folder). Typically these messages are then be read by the user through an SMS application, but other messaging clients can receive notifications when a new message is created in the store and can process the message if appropriate.

To receive such notifications, a class must implement the MMsvSessionObserver session observer interface. 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 code snippet 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_cast<CMsvEntrySelection*>(aArg1);
            break;
        default:
            break;
        }

The observer receives notifications for all types of entry, so it is necessary to read the message properties to check that the entry is appropriate to process.

The following code snippet does the first stage of checking:

1. Gets the index entry for the message. Getting an index entry is quick compared to getting the entire message. Therefore, it is recommended that you perform the required checks on this first.

2. Tests if the entry is an SMS message, by checking the index entry's iMtm and iType fields

3. Tests if it is an incoming message, by checking that the entry is in the Inbox.

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

    // check each entry to see if we want to process it
    while (count--)
        {
        // get the index entry
        TMsvId serviceId;
        TMsvEntry entry;
        iMtm->Session().GetEntry((*entries)[count], serviceId, entry);
        // if the entry is an SMS message
        if (entry.iMtm == KUidMsgTypeSMS && entry.iType == KUidMsvMessageEntry
            // and if it's an incoming message (as its in the inbox)
            && entry.Parent() == KMsvGlobalInBoxIndexEntryId)

An application can now perform further checks, for example, for particular message content.

//    sets the client MTM's context to the message 
             
iMtm->SwitchCurrentEntryL((*entries)[count]);
iMtm->LoadMessageL();

If you determine that your application must process the message, you can prevent the user from seeing the message in the Inbox of the standard messaging application. To do this, you can set the message entry's visible flag to false using TMsvEntry::SetVisible(EFalse). You must delete the message once its processing is complete.