<?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&lt;TInt&gt;     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 &lt;eiknotapi.h&gt;
#include &lt;ecom.h&gt;

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&amp; aBuffer);
       virtual void Cancel();
       virtual TPtrC8 UpdateL(const TDesC8&amp; aBuffer);
       void ExtractClass0SMSData(const TDesC8&amp; 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 &lt;ecom.h&gt;
#include &lt;tmsvpackednotifierrequest.h&gt;
#include &lt;implementationproxy.h&gt;
#include &lt;gsmubuf.h&gt;
#include &lt;s32mem.h&gt;
#include &lt;e32base.h&gt;
#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&lt;MEikSrvNotifierBase2&gt;* NotifierArray()
       {
       CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;* subjects=NULL;
       TRAPD( err, subjects=new (ELeave)CArrayPtrFlat&lt;MEikSrvNotifierBase2&gt;(1) );
       if( err == KErrNone )
              {
              TRAP( err, subjects-&gt;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-&gt;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&amp; aBuffer)
       {
       ExtractClass0SMSData(aBuffer);
       return KNullDesC8();
       }

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


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

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

// Extract class 0 SMS Message and Display on UI
void CClass0SmsUINotifier::ExtractClass0SMSData(const TDesC8&amp; 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&lt;1000&gt; smsMsg;
       readStream &gt;&gt; smsMsg;
    
       // function to display SMS Message on UI, this needs to be implemented..
       DisplayClass0SMSDataOnUI(smsMsg);
       }
</codeblock> </section>
</conbody></concept>