<?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 xml:lang="en" id="GUID-B861091F-DFD7-5BDD-B73C-52833F972CBD"><title>Porting Notifiers to Secure Platform</title><shortdesc>This page describes how to migrate notifiers to Symbian OS v9.1. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-EC370F04-02A3-57D6-8B5A-C085950FAFCD"><title>Introduction</title> <p>Notifier plug-in DLLs ("notifiers") allow components with no direct UI linkage to interact with the user through a UI element; for example, a dialog box. </p> <p>You can migrate notifiers to Symbian OS v9.1 without major changes. Any notifier classes derived from <codeph>MEikSrvNotifierBase</codeph> must now derive from <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita"><apiname>MEikSrvNotifierBase2</apiname></xref>. An enumeration is used to define an ECom-based notifier plug-in interface. This acts as a primary key to separate ECom-based notifier plug-ins from other types. </p> <p> <b> Note:</b> The Symbian platform architecture still supports old-style (non-ECom-based) plug-ins. </p> <p>Notifiers have the following features: </p> <ul><li id="GUID-FC1E274F-203B-5DE9-A382-762C3C97BFE3"><p>They can be installed in ROM (<filepath>Z:</filepath>), RAM (<filepath>C:</filepath>), or on a memory card (for example, <filepath>E:</filepath>). </p> </li> <li id="GUID-E36D43EE-B2EC-5219-B969-FC2CCEE50868"><p>They can be installed and un-installed using SIS files. </p> </li> <li id="GUID-784483E3-D297-5228-8BDA-0C93018DD640"><p>A single plug-in DLL can provide multiple notifiers. The plug-in DLL returns an array of <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita"><apiname>MEikSrvNotifierBase2</apiname></xref> class pointers through ECom. </p> </li> <li id="GUID-D9D6A40E-D26F-5448-9E50-6D81544B9F7D"><p>Each notifier can have multiple implementations. </p> </li> </ul> </section> <section id="GUID-A53A1B64-4250-53B9-BD0F-32AFE2F34E5F"><title>Notifier source code example</title> <p>ECom defines standard framework functions that plug-ins implement. Here is an example of the required notifier source code: </p> <codeblock id="GUID-CD591744-90C4-57B5-918B-ABE3B41CBA00" xml:space="preserve">EXPORT_C CArrayPtr&lt;MEikSrvNotifierBase2&gt;* NotifierArray1()

// Lib main entry point

      {...}

EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray2()

// Lib main entry point

      {...}

// Adding ECom support

#include <ImplementationProxy.h>

const TImplementationProxy ImplementationTable[] =

      {

      IMPLEMENTATION_PROXY_ENTRY(0x10022238,NotifierArray1),

      IMPLEMENTATION_PROXY_ENTRY(0x10022237,NotifierArray2)

      }; 

EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)

      {

      aTableCount = sizeof(ImplementationTable)/sizeof(TImplementationProxy);

      return ImplementationTable;

       }</codeblock> </section> <section id="GUID-3F83B740-F999-55F1-A244-83C97F240883"><title>Resource file example</title> <p>ECom uses resource files to define the main elements of application GUIs. Resource file names must have the format: <filepath>&lt;dll_uid&gt;.rss</filepath>. </p> <p>The following UIDs may appear in the resource file. </p> <table id="GUID-8A60EEFE-E0FB-559C-B864-CB37EC324AD4"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><p> <b>UID Name</b>  </p> </entry> <entry><p> <b>Description</b>  </p> </entry> </row> <row><entry><p> <codeph>dll_uid</codeph>  </p> </entry> <entry><p>The UID of the notifier plug-in DLL. </p> </entry> </row> <row><entry><p> <codeph> interface_uid</codeph>  </p> </entry> <entry><p>The interface UID for all notifiers, which is defined in <filepath>uikon.hrh</filepath> as: </p> <codeblock id="GUID-E664FEB0-AD66-5598-BD88-C72F068372C6" xml:space="preserve">#define KUikonUidpluginInterfaceNotifiers    0x101fdfae.</codeblock> </entry> </row> <row><entry><p> <codeph> implementation_uid</codeph>  </p> </entry> <entry><p>This is implementation-specific. </p> </entry> </row> <row><entry><p>plug-in_UID </p> </entry> <entry><p>The notifier’s UID. </p> </entry> </row> <row><entry><p>channel_UID </p> </entry> <entry><p>The channel for a notifier (for example, a screen or LED). </p> </entry> </row> </tbody> </tgroup> </table> <p>Together, the <codeph>plug-in_UID</codeph> and <codeph>channel_UID</codeph> uniquely identify the notifier plug-in. </p> <p>The following resource file corresponds to the C++ <xref href="GUID-B861091F-DFD7-5BDD-B73C-52833F972CBD.dita#GUID-B861091F-DFD7-5BDD-B73C-52833F972CBD/GUID-A53A1B64-4250-53B9-BD0F-32AFE2F34E5F">Source code</xref>, above. It defines two implementations of the notifier interface. </p> <codeblock id="GUID-D0D2F679-5196-5150-988E-ED5EB30668E2" xml:space="preserve">// 10021239.rss

//

#include "RegistryInfo.rh"

#include "Uikon.hrh"

RESOURCE REGISTRY_INFO theInfo

   {

      dll_uid = 0x10021239;

      interfaces =

      {

      INTERFACE_INFO

            {

            interface_uid = KUikonUidPluginInterfaceNotifiers;

            implementations =

                  {

                  IMPLEMENTATION_INFO

                        {

                        implementation_uid = 0x10022237;

                        version_no = 1;

                        display_name = "TTNOTIFY2V2 Plugin 1";

                        default_data = "TTNOTIFY2V2";

                        opaque_data     = "0";

                        },

                  IMPLEMENTATION_INFO

                        {

                        implementation_uid = 0x10022238;

                        version_no = 1;

                        display_name = "TTNOTIFY2V2 Plugin 2";

                        default_data = "TTNOTIFY2V2";

                        opaque_data     = "0";

                        }

                  };

            }

      };

}</codeblock> </section> <section id="GUID-8E585844-E5B3-5909-9B48-A288D89E621F"><title>MMP file example</title> <p>This is an example project specification (<filepath>.mmp</filepath>) file for the notifier: </p> <codeblock id="GUID-2316985A-2B7D-5255-ACD0-1A4E72026232" xml:space="preserve">

target            TESTNOTIFIER.DLL 

targettype        PLUGIN 

capability         TrustedUI ProtServ 

UID                0x10009D8D 0x10021239 

sourcepath        ...

userinclude        ... 

systeminclude    \epoc32\include \epoc32\include\techview 

lang                SC 

start resource    10021239.rss  

target            TESTNOTIFIER.rsc  

start resource    TNOTDIAL.RSS 

targetpath        \private\10003a4a 

header 

end 

source            filename.cpp 

library            ECOM.LIB</codeblock> </section> </conbody><related-links><link href="GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1.dita"><linktext>Using the extended notifier

                framework</linktext> </link> </related-links></concept>