<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268" xml:lang="en"><title>Using

the Class 0 Plug-in for Class 0 SMS</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This section describes an ECom plug-in called <b>Class 0 </b> plug-in for

the messaging subsystem which handles <b>Class 0</b> SMS. </p>

<section><title>Overview</title> <p>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. </p> <p>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 <xref href="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268.dita#GUID-C45FFBDD-37D4-5892-8D13-CFE292264268/GUID-42CA3291-7C12-52F3-9F1E-7A16E740FB89">Architecture</xref> section. </p> <p><b>SMS stack configuration</b> </p> <p>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 <xref href="GUID-266B3FD6-A414-599D-BF31-FF67ADDD4E70.dita">Configuring

SMS Stack To Handle Class 0 Messages</xref>. </p><note> WAP messages that

use Class 0 SMS are treated as non Class 0 SMS.</note><p>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 <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref> class.

For more information on <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref>, see <xref href="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268.dita#GUID-C45FFBDD-37D4-5892-8D13-CFE292264268/GUID-B6EECACA-77D1-57AF-A7F9-4ECE7E911C38">Writing a new plug-in using CSmsClass0Base class</xref>.</p> </section>

<section id="GUID-42CA3291-7C12-52F3-9F1E-7A16E740FB89"><title>Architecture</title> <p>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). </p> <fig id="GUID-9768EB50-2605-5181-AB53-7376A4B82272">

<title>              Architecture of the Class 0 plug-in            </title>

<image href="GUID-EC6C21FB-16E1-57FA-B995-8B0F34B6588A_d0e477912_href.png" placement="inline"/>

</fig> <dl>

<dlentry>

<dt>SMS stack</dt>

<dd><p>SMS Stack sends and receives SMS on GSM networks. </p> </dd>

</dlentry>

<dlentry>

<dt>NBS watcher</dt>

<dd><p>NBS watcher handles reception of SMS and listens to the following special

SMS received from the SMS stack: </p> <ul>

<li id="GUID-5EC44BF6-BEAB-5716-9ADD-81E9A4DA8420"><p>Replace type messages </p> </li>

<li id="GUID-9698F7AD-0E2E-58FE-81FA-DAA1AFDB9A2C"><p>Message indications </p> </li>

<li id="GUID-1164E798-FBFA-5C32-B031-FC5158D35083"><p>Delivery reports </p> </li>

</ul> </dd>

</dlentry>

</dl> </section>

<section id="GUID-B6EECACA-77D1-57AF-A7F9-4ECE7E911C38"><title>Writing a new

plug-in using the CSmsClass0Base class</title> <p>The Symbian Messaging subsystem

includes a default implementation of the <codeph>CSmsClass0Base</codeph> plug-in

which can be found in the <filepath>class0sms.dll</filepath> file. </p> <p>However,

licensees can override it by writing a new ECom plug-in using the <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref> exported

class. For instructions on writing a new ECom plug-in, see the <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom</xref> guide. </p> <fig id="GUID-89F37A8E-78B2-5BEE-A066-90A186687FCA">

<title>              Class diagram            </title>

<image href="GUID-B479BE8B-5CAD-57C2-9E21-DEB9E64E25EE_d0e477987_href.png" placement="inline"/>

</fig> <p> <codeph>void CClass0Sms::DisplayMessageHandler(TDesC8&amp; aSmsMessage,

TBool aIsCompleteMsg)</codeph>  </p> <table id="GUID-F3506200-AB0D-56EB-9C18-70E83B818ABA">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <xref href="GUID-E6FE50CD-CA6D-3377-8936-F2053330FF80.dita"><apiname>CClass0Sms</apiname></xref>  </p> </entry>

<entry><p>Derived from the <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref> class </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-50DE662C-DB6E-3149-B0F3-6740BF7989E9.dita"><apiname>DisplayMessageHandler</apiname></xref>  </p> </entry>

<entry><p>This method calls <xref href="GUID-C6382C9D-1AE1-3B11-9B51-9D29D902254B.dita"><apiname>StartNotifier()</apiname></xref> or <xref href="GUID-9475FFE9-37AC-3B6C-9312-577D951DE191.dita"><apiname>UpdateNotifier()</apiname></xref> according

to the value set in the aIsCompleteMsg flag. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> <codeph>&amp; aSmsMessage</codeph>  </p> </entry>

<entry><p>Contains the following data: </p> <ul>

<li id="GUID-CFE508B0-7546-5F34-9B22-63648DEE1235"><p>Starting PDU (Protocol

Data Unit) position of the decoded message </p> </li>

<li id="GUID-AE21C54C-FA96-5921-8FD2-64A886C311AA"><p>Ending PDU position

of the decoded message </p> </li>

<li id="GUID-BC00D3B1-2254-5A5C-8E09-8DBBA87320C8"><p>Boolean value indicating

if it is a last incomplete message. </p> </li>

<li id="GUID-DE984CF4-308B-56B2-B935-9EF711E10B26"><p>Class 0 SMS data </p> </li>

</ul> <p>The data needs be extracted at the client side in same order; that

is, <codeph>TInt aStartPos</codeph>, <codeph>TInt endPos</codeph>, <xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref> <codeph> aIsLastMessage</codeph>,

and <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref> <codeph> aSmsData</codeph>. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref> <codeph> aIsCompleteMsg</codeph>  </p> </entry>

<entry><p>Indicates whether the message is a complete or partial message. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>This class calls <codeph>RNotifier::StartNotifier</codeph> or <codeph>RNotifier::UpdateNotifier</codeph> according

to the <codeph>aIsCompleteMsg</codeph> flag setting as illustrated in the

following code example: </p> <codeblock id="GUID-8695AEDE-4F2D-5379-BA42-23374176F3D3" xml:space="preserve">void CClass0Sms::DisplayMessageHandler(TDesC8&amp; 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);

        }

    }</codeblock> <p>For more details on writing a UI Notifier, see <xref href="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268.dita#GUID-C45FFBDD-37D4-5892-8D13-CFE292264268/GUID-EBBDB3ED-B5BD-580C-8869-BA35DBA64F1F">Example</xref>. </p> </section>

<section><title>Understanding types of Class 0 SMS</title> <p>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. </p> <p>The

following are the type of Class 0 SMS message displayed on the UI framework. </p><table id="GUID-31075134-4116-45C7-9905-D06A0F73C759">

<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>

<tbody>

<row>

<entry><p><b>Type of Class 0 SMS message </b></p></entry>

<entry><p><b>Displayed on the UI framework</b></p></entry>

</row>

<row>

<entry><p>Complete </p></entry>

<entry><p>If the received message is complete, it contains the Class 0 SMS

data and the remaining fields are set to zero (0).</p><codeblock xml:space="preserve">StartPos:0EndPos:0IsCompleteMsg: EFalse</codeblock></entry>

</row>

<row>

<entry><p>Partial </p></entry>

<entry><p>If the received message is incomplete, it contains information about

the starting and ending PDU positions of the decoded message, and the <codeph>isCompleteMessageFlag</codeph> flag

is set to <codeph>EFalse</codeph>. </p><codeblock xml:space="preserve">StartPos: StartingPDUpositionEndPos:  EndingPDUpositionisLastMessage: ETrue</codeblock><p>If it is the last part of the partial message, then <codeph>IsCompleteMessageFlag</codeph> will

be set to <codeph>EFalse</codeph>. </p></entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>Extracting the serial buffer</title> <p>The Symbian Messaging

subsystem passes the serial buffer, which contains starting and ending PDU,

and the Class 0 SMS message in the <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> descriptor to

the UI. The <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> descriptor must be read at the UI side

in the same order; that is, <codeph>TInt aStartPos</codeph>, <codeph>TInt

endPos</codeph>, <xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref> <codeph> aIsLastMessage</codeph>,

and <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref> <codeph> aSmsData</codeph>. </p> </section>

<section id="GUID-EBBDB3ED-B5BD-580C-8869-BA35DBA64F1F-GENID-1-7-1-17-1-1-6-1-6-1-4-1-2-7"><title>Example</title> <p>The

following example code shows how to write a UI notifier and extract the Class

0 SMS message: </p> <p><b>class0smsUInotifier.h</b> </p> <codeblock id="GUID-88CC9E44-3C8C-522B-83D3-658EEEEE928D" xml:space="preserve">// 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__

</codeblock> <p><b>class0smsUInotifier.cpp</b> </p> <codeblock id="GUID-E7C55266-C174-59A2-B926-A7F3E0496B5C" xml:space="preserve">// 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);

       }

</codeblock> </section>