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 id="GUID-6CEAFE12-EB30-5231-94F4-2D097E79BFE0" xml:lang="en"><title>Implementing

    13 the FEP API</title><shortdesc>This topic describes various implementations of FEP.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-D0CB0202-D4B6-422B-84AA-F70974DDF7F3"><title>Post-platform

    15 security – the ECom plugin interface</title><p>In the secure platform, FEPs

    16 must be implemented as ECom plug-ins. ECom provides a secure environment for

    17 loading FEPs that cannot be achieved using standard, non-ECom polymorphic

    18 DLLs. The main tasks that are specific to implementing a FEP as an ECom plug-in

    19 are described in this section. Note that the differences between pre- and

    20 post-platform security FEPs are imposed by the change from old-style, standard

    21 polymorphic DLLs to ECom plugins. The C++ APIs involved in FEP creation, which

    22 are defined in <filepath>fepbase.h</filepath>, are unchanged. </p> </section>

    23 <section id="GUID-97C929BB-0523-45F4-8100-D8065B9A53D5"><title>Define a class

    24 that implements the CCoeFepPlugIn interface</title><p>This class must implement

    25 the <codeph>NewFepL()</codeph> and <codeph>SynchronouslyExecuteSettingsDialogL()</codeph> functions

    26 that were, pre-platform security, the first and second exports from the DLL.

    27 Note that these functions have been redefined and no longer take the const <codeph>TDesC&amp;

    28 aFullFileNameOfDll </codeph> argument: the ECom plugin implementation is identified

    29 by a UID rather than a filename. This means that the implementation of <codeph>SynchronouslyExecuteSettingsDialogL()</codeph> is

    30 now responsible for locating the resource file needed to execute the settings

    31 dialog itself. </p> <codeblock id="GUID-310F5ADC-B9CB-5A3B-878F-AF13C4C4C08B" xml:space="preserve">class CCoeFepPlugIn : public CBase

    32     {

    33 public:

    34     inline static CCoeFepPlugIn* NewL(TUid aFepUid);

    35     virtual ~CCoeFepPlugIn();

    36 public:

    37     virtual CCoeFep* NewFepL(CCoeEnv& aConeEnvironment, const CCoeFepParameters& aFepParameters) = 0;

    38     virtual void SynchronouslyExecuteSettingsDialogL(CCoeEnv& aConeEnvironment) = 0;

    39     };

    40 </codeblock> </section>

    41 <section id="GUID-939614DA-C3EF-43FD-924A-805596AEC2FD"><title>Provide the

    42 factory code required to instantiate the derived class </title> <p>FEPs must

    43 provide the standard factory code required by every ECom plugin. For more

    44 information, see “Using ECom” in the Symbian Developer Library. For example,

    45 (the following code is taken from <filepath>TFEP1PlugIn.cpp</filepath>): </p> <codeblock id="GUID-88F37824-8CAA-53B8-BD69-AB5B17B9BBB5" xml:space="preserve">const TInt KTstFepPlugInImplementationValue = 0x102024D0;

    46 const TImplementationProxy ImplementationTable[] = 

    47     {

    48     IMPLEMENTATION_PROXY_ENTRY(KTstFepPlugInImplementationValue, CTstFepPlugIn::NewL )

    49     };

    50 EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)

    51     {

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

    53     return ImplementationTable;

    54     }

    55 CTstFepPlugIn* CTstFepPlugIn::NewL()

    56     { // static

    57     return new(ELeave) CTstFepPlugIn;

    58     }

    59 </codeblock></section>

    60 <section id="GUID-FC0B99AB-B579-42A2-8A0C-3A36BE648616"><title>Create an ECom

    61 resource file</title> <p>Each FEP must have an ECom resource file. Its interface

    62 UID must be 0x1020233f, or CONE will not be able to find the FEP. For example, </p> <codeblock id="GUID-5CBDB731-EBAD-5326-909C-4DF78E7AC360" xml:space="preserve">#include &lt;RegistryInfo.rh&gt;

    63 

    64 RESOURCE REGISTRY_INFO theInfo

    65     {

    66     dll_uid = 0x102024D0; // UID3 of the DLL

    67     interfaces = 

    68         {

    69         INTERFACE_INFO

    70             {

    71             interface_uid = 0x1020233F; // Same for every FEP

    72             implementations = 

    73                 {

    74                 IMPLEMENTATION_INFO

    75                     {

    76                     implementation_uid = 0x102024D0;

    77                     version_no = 1;

    78                     display_name = "FEPNAME";

    79                     default_data = "";

    80                     opaque_data = "";

    81                     }

    82                 };

    83             }

    84         };

    85     }</codeblock></section>

    86 <section id="GUID-BEDE8AA4-843E-405E-A8F9-EC80893D7D59"><title>The CCoeFep

    87 class</title> <p>The parts of <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> relevant to classes

    88 deriving from it are shown below: </p> <codeblock id="GUID-14B6DFB4-02DE-5D12-BBFB-0665F6B089E0" xml:space="preserve">class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver

    89 {

    90 public:

    91     enum TEventResponse

    92         {

    93         EEventWasNotConsumed,

    94         EEventWasConsumed

    95         };

    96     class MDeferredFunctionCall

    97         {

    98     public:

    99         virtual void ExecuteFunctionL()=0;

   100         };

   101     class MModifiedCharacter

   102         {

   103     public:

   104         virtual TUint CharacterCode() const=0;

   105         virtual TUint ModifierMask() const=0;

   106         virtual TUint ModifierValues() const=0;

   107         };

   108 public:

   109     IMPORT_C virtual ~CCoeFep();

   110     virtual void CancelTransaction()=0;

   111 protected:

   112     IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment);

   113     IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters);

   114     IMPORT_C void ReadAllAttributesL();

   115     IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall);

   116     IMPORT_C void SimulateKeyEventsL(const TArray<TUint>& aArrayOfCharacters);

   117     IMPORT_C void SimulateKeyEventsL(const TArray<MModifiedCharacter>& aArrayOfModifiedCharacters);

   118     IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid);

   119     IMPORT_C void WriteAttributeDataAndBroadcastL(const TArray<TUid>& aAttributeUids);

   120     IMPORT_C TBool IsOn() const;

   121 private:

   122     virtual void IsOnHasChangedState()=0;

   123     virtual void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode)=0;

   124     virtual void OfferPointerEventL(TEventResponse& aEventResponse, const TPointerEvent& aPointerEvent, const CCoeControl* aWindowOwningControl)=0;

   125     virtual void OfferPointerBufferReadyEventL(TEventResponse& aEventResponse, const CCoeControl* aWindowOwningControl)=0;

   126     };

   127 </codeblock> <p>Note that <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> inherits, but does not

   128 override, some pure virtual functions from its base classes <xref href="GUID-270424BB-124B-39FF-9CDA-5CAFB5407FAE.dita"><apiname>MFepAttributeStorer</apiname></xref>, <xref href="GUID-2CAC79B0-8BD3-3961-A162-75B004AEE5FC.dita"><apiname>MCoeForegroundObserver</apiname></xref> and <xref href="GUID-E591B7D7-ED56-3CEF-883F-7091D5833731.dita"><apiname>MCoeFocusObserver</apiname></xref>. These therefore need to be overridden in addition

   129 to <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> ’s own pure virtual member functions. The details

   130 of the member functions of <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> and its base classes

   131 are explained in various sections of this document. </p></section>

   132 <section id="GUID-ECA1F4AE-1B25-4079-B249-AC8ECF3D3F90"><title>The CCoeControl

   133 class</title><p>The <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> class (defined in <filepath>epoc32\include\COECNTRL.H</filepath>)

   134 provides many useful features for implementing a FEP, such as functions for

   135 handling window server events. In fact, for FEPs wishing to intercept key

   136 events, writing a class that derives from <codeph>CCoeControl</codeph> is

   137 a necessity because of the need to use the control stack (see <xref href="GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96.dita#GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96/GUID-1B15C661-851B-5922-B8BC-7A772232DBD2">Intercepting key events</xref>, below). Thus although deriving from <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> is

   138 not explicitly demanded by the FEP architecture, it is assumed throughout

   139 this document that the object of the <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> derived

   140 class owns an object of a <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> derived class. </p></section>

   141 </conbody></concept>