Using the Class 0 Plug-in for Class 0 SMS

Overview

Class 0 SMS is a type of SMS message that is displayed on the mobile screen without being saved in the message store or on the SIM card; unless explicitly saved by the mobile user. The Class 0 plug-in handles and displays Class 0 SMS.

Using this plug-in, the Symbian Messaging subsystem does not store Class 0 SMS in the message store (SMS service Inbox), but immediately displays them on the mobile screen; even if there is no memory available on the SIM or device. For more detailed information on how Class 0 messages are handled by the Symbian Messaging subsystem, see the Architecture section.

SMS stack configuration

The SMS stack must be configured to handle Class 0 SMS. This is done in accordance with the SMS stack licence. If the SMS stack is not configured to handle Class 0 messages they will be treated as non Class 0 SMS. They will be stored in the message store and are notified to the UI framework. For more information on configuration of the SMS stack to handle Class 0 messages, see Configuring SMS Stack To Handle Class 0 Messages.

Symbian provides a default plug-in as part of the Symbian Messaging subsystem. However, licensees can override it by writing a new ECom plug-in using the CSmsClass0Base class. For more information on CSmsClass0Base, see Writing a new plug-in using CSmsClass0Base class.

Architecture

The Class 0 plug-in is loaded by the Narrow Band Socket (NBS) watcher when it starts. The NBS watcher looks for the Class 0 plug-in ROM only. When the NBS watcher receives an SMS message from the SMS stack, it checks for the type of SMS message. If it is a Class 0 SMS message, the NBS watcher passes the message to the Class 0 plug-in. The Class 0 plug-in immediately notifies a UI notifier plug-in which displays the content of the Class 0 SMS message on the UI without storing it in the message store (SMS service Inbox).

Figure 1. Architecture of the Class 0 plug-in

SMS stack

SMS Stack sends and receives SMS on GSM networks.

NBS watcher

NBS watcher handles reception of SMS and listens to the following special SMS received from the SMS stack:

• Replace type messages

• Message indications

• Delivery reports

Writing a new plug-in using the CSmsClass0Base class

The Symbian Messaging subsystem includes a default implementation of the CSmsClass0Base plug-in which can be found in the class0sms.dll file.

However, licensees can override it by writing a new ECom plug-in using the CSmsClass0Base exported class. For instructions on writing a new ECom plug-in, see the ECom guide.

Figure 2. Class diagram

void CClass0Sms::DisplayMessageHandler(TDesC8& aSmsMessage, TBool aIsCompleteMsg)

This class calls RNotifier::StartNotifier or RNotifier::UpdateNotifier according to the aIsCompleteMsg flag setting as illustrated in the following code example:

void CClass0Sms::DisplayMessageHandler(TDesC8& aSmsMessage, TBool aIsCompleteMsg)
    {
    TPckgBuf<TInt>     response;
    
    if(aIsCompleteMsg)
        {
        //The UID of KUidClass0SmsNotifier should to be used in UI Notifier. 
        iNotifier.StartNotifier(KUidClass0SmsNotifier, aSmsMessage);        
        }
    else
        {
        //The UID of KUidClass0SmsNotifier should to be used in UI Notifier.
        iNotifier.UpdateNotifier(KUidClass0SmsNotifier, aSmsMessage, response);
        }
    }

For more details on writing a UI Notifier, see Example.

Understanding types of Class 0 SMS

The SMS stack can send a complete or partial messages to the Messaging client. When it sends a partial message to the Messaging client, such as in an out-of-disk condition, it provides additional information about the partial message.

The following are the type of Class 0 SMS message displayed on the UI framework.

StartPos:0EndPos:0IsCompleteMsg: EFalse

StartPos: StartingPDUpositionEndPos:  EndingPDUpositionisLastMessage: ETrue

Extracting the serial buffer

The Symbian Messaging subsystem passes the serial buffer, which contains starting and ending PDU, and the Class 0 SMS message in the TDesC8 descriptor to the UI. The TDesC8 descriptor must be read at the UI side in the same order; that is, TInt aStartPos, TInt endPos, TBool aIsLastMessage, and TPtr aSmsData.

Example

The following example code shows how to write a UI notifier and extract the Class 0 SMS message:

class0smsUInotifier.h

// class0smsUInotifier.h
//
// Copyright ©) Symbian Software Ltd 2007. All rights reserved.
//

#ifndef __CLASS0SMSUINOTIFIER_H__
#define __CLASS0SMSUINOTIFIER_H__

#include <eiknotapi.h>
#include <ecom.h>

class CClass0SmsUINotifier : public MEikSrvNotifierBase2
    {
public:
       // Construction
       static CClass0SmsUINotifier* NewL();
       ~CClass0SmsUINotifier();
private:
       CClass0SmsUINotifier();
       void ConstructL();

       // from MEikSrvNotifierBase2
       virtual void Release();
       virtual TNotifierInfo RegisterL();
       virtual TNotifierInfo Info() const;
       virtual TPtrC8 StartL(const TDesC8& aBuffer);
       virtual void Cancel();
       virtual TPtrC8 UpdateL(const TDesC8& aBuffer);
       void ExtractClass0SMSData(const TDesC8& aBuffer);

private:
       TNotifierInfo iInfo;
       };

#endif    // __CLASS0SMSUINOTIFIER_H__

class0smsUInotifier.cpp

// class0smsUInotifier.cpp
//
// Copyright ©) Symbian Software Ltd 2007.  All rights reserved.
//
#include <ecom.h>
#include <tmsvpackednotifierrequest.h>
#include <implementationproxy.h>
#include <gsmubuf.h>
#include <s32mem.h>
#include <e32base.h>
#include "class0smsUInotifier.h"


// The UID identifying the notifier, 
// this UID is used in RNotifier::StartNotifier/RNotifier::UpdateNotifier to send the class 0 SMS message from messaging application.

const TUid KUidClass0SmsNotifier  = {0x2000C382};
const TUid KClass0SmsNotifierOutput     = {0x2000C382};


EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray()
       {
       CArrayPtrFlat<MEikSrvNotifierBase2>* subjects=NULL;
       TRAPD( err, subjects=new (ELeave)CArrayPtrFlat<MEikSrvNotifierBase2>(1) );
       if( err == KErrNone )
              {
              TRAP( err, subjects->AppendL( CClass0SmsUINotifier::NewL() ) );
              return(subjects);
               }
       else
              {
              return NULL;
              }
       }

// Allocates and constructs a CClass0SmsUINotifier object
CClass0SmsUINotifier* CClass0SmsUINotifier::NewL()
        {
        CClass0SmsUINotifier* self=new (ELeave) CClass0SmsUINotifier();
        CleanupStack::PushL(self);
        self->ConstructL();
        CleanupStack::Pop(self);
        return self;
        }
    
void CClass0SmsUINotifier::ConstructL()
        {
        }

// destructor
CClass0SmsUINotifier::~CClass0SmsUINotifier()
       {
       REComSession::FinalClose();
       }
// constructor
CClass0SmsUINotifier::CClass0SmsUINotifier()
       {
       //The UID identifying the notifier. 
       iInfo.iUid      = KUidClass0SmsNotifier;
       iInfo.iChannel  = KClass0SmsNotifierOutput;
       iInfo.iPriority = ENotifierPriorityHigh;
       }

// Frees all resources owned by CClass0SmsUINotifier notifier
void CClass0SmsUINotifier::Release()
       {
       delete this;
       }


// Called when a notifier is first loaded to allow any initial construction that is required.
CClass0SmsUINotifier::TNotifierInfo CClass0SmsUINotifier::RegisterL()
       {
       return iInfo;
       }

// To get the notifier parameters
CClass0SmsUINotifier::TNotifierInfo CClass0SmsUINotifier::Info() const
       {
       return iInfo;
       }
    

// The notifier has been deactivated so resources can be freed and outstanding messages completed.
void CClass0SmsUINotifier::Cancel()
       {
       }

// Class0SMS PDU will be received here. 
TPtrC8 CClass0SmsUINotifier::StartL(const TDesC8& aBuffer)
       {
       ExtractClass0SMSData(aBuffer);
       return KNullDesC8();
       }

// Update a currently active notifier with data aBuffer.
TPtrC8 CClass0SmsUINotifier::UpdateL(const TDesC8& aBuffer)
       {
       ExtractClass0SMSData(aBuffer);
       return KNullDesC8();
       }


//Adding ECOM SUPPORT
const TImplementationProxy ImplementationTable[] =
       {
       IMPLEMENTATION_PROXY_ENTRY(0x2000C612, NotifierArray)
       };

EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)
       {
       aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy);
       return ImplementationTable;
       }

// Extract class 0 SMS Message and Display on UI
void CClass0SmsUINotifier::ExtractClass0SMSData(const TDesC8& aBuff)
       {
       // to extract Starting PDU position of decoded message
       TInt startPos=0;
       // to extract Ending PDU position of decoded message
       TINT endPos=0;
       // Is it Last message
       TBool isLastMessage = EFalse;
    
       RDesReadStream readStream(aBuff);
       CleanupClosePushL (readStream);
        
       startPos = readStream.ReadInt32L();
       endPos = readStream.ReadInt32L();
       isLastMessage = readStream.ReadInt32L();
    
       // Buffer to extract SMS data 
       TBuf<1000> smsMsg;
       readStream >> smsMsg;
    
       // function to display SMS Message on UI, this needs to be implemented..
       DisplayClass0SMSDataOnUI(smsMsg);
       }