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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <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()

    13 // Lib main entry point

    14       {...}

    15  

    16 EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray2()

    17 // Lib main entry point

    18       {...}

    19  

    20 // Adding ECom support

    21 #include <ImplementationProxy.h>

    22 const TImplementationProxy ImplementationTable[] =

    23       {

    24       IMPLEMENTATION_PROXY_ENTRY(0x10022238,NotifierArray1),

    25       IMPLEMENTATION_PROXY_ENTRY(0x10022237,NotifierArray2)

    26       }; 

    27 EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)

    28       {

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

    30       return ImplementationTable;

    31        }</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

    32 //

    33 

    34 #include "RegistryInfo.rh"

    35 #include "Uikon.hrh"

    36 

    37 RESOURCE REGISTRY_INFO theInfo

    38    {

    39       dll_uid = 0x10021239;

    40       interfaces =

    41       {

    42       INTERFACE_INFO

    43             {

    44             interface_uid = KUikonUidPluginInterfaceNotifiers;

    45             implementations =

    46                   {

    47                   IMPLEMENTATION_INFO

    48                         {

    49                         implementation_uid = 0x10022237;

    50                         version_no = 1;

    51                         display_name = "TTNOTIFY2V2 Plugin 1";

    52                         default_data = "TTNOTIFY2V2";

    53                         opaque_data     = "0";

    54                         },

    55                   IMPLEMENTATION_INFO

    56                         {

    57                         implementation_uid = 0x10022238;

    58                         version_no = 1;

    59                         display_name = "TTNOTIFY2V2 Plugin 2";

    60                         default_data = "TTNOTIFY2V2";

    61                         opaque_data     = "0";

    62                         }

    63                   };

    64             }

    65       };

    66 }</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">

    67 target            TESTNOTIFIER.DLL 

    68 targettype        PLUGIN 

    69 capability         TrustedUI ProtServ 

    70 UID                0x10009D8D 0x10021239 

    71 sourcepath        ...

    72 userinclude        ... 

    73 systeminclude    \epoc32\include \epoc32\include\techview 

    74 lang                SC 

    75 

    76 start resource    10021239.rss  

    77 target            TESTNOTIFIER.rsc  

    78 

    79 start resource    TNOTDIAL.RSS 

    80 targetpath        \private\10003a4a 

    81 header 

    82 end 

    83 source            filename.cpp 

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

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