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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    {

public:

    inline static CCoeFepPlugIn* NewL(TUid aFepUid);

    virtual ~CCoeFepPlugIn();

public:

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

    virtual void SynchronouslyExecuteSettingsDialogL(CCoeEnv& aConeEnvironment) = 0;

    };

</codeblock> </section>

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

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

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

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

(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;

const TImplementationProxy ImplementationTable[] = 

    {

    IMPLEMENTATION_PROXY_ENTRY(KTstFepPlugInImplementationValue, CTstFepPlugIn::NewL )

    };

EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)

    {

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

    return ImplementationTable;

    }

CTstFepPlugIn* CTstFepPlugIn::NewL()

    { // static

    return new(ELeave) CTstFepPlugIn;

    }

</codeblock></section>

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

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

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;

RESOURCE REGISTRY_INFO theInfo

    {

    dll_uid = 0x102024D0; // UID3 of the DLL

    interfaces = 

        {

        INTERFACE_INFO

            {

            interface_uid = 0x1020233F; // Same for every FEP

            implementations = 

                {

                IMPLEMENTATION_INFO

                    {

                    implementation_uid = 0x102024D0;

                    version_no = 1;

                    display_name = "FEPNAME";

                    default_data = "";

                    opaque_data = "";

                    }

                };

            }

        };

    }</codeblock></section>

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

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

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

{

public:

    enum TEventResponse

        {

        EEventWasNotConsumed,

        EEventWasConsumed

        };

    class MDeferredFunctionCall

        {

    public:

        virtual void ExecuteFunctionL()=0;

        };

    class MModifiedCharacter

        {

    public:

        virtual TUint CharacterCode() const=0;

        virtual TUint ModifierMask() const=0;

        virtual TUint ModifierValues() const=0;

        };

public:

    IMPORT_C virtual ~CCoeFep();

    virtual void CancelTransaction()=0;

protected:

    IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment);

    IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters);

    IMPORT_C void ReadAllAttributesL();

    IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall);

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

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

    IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid);

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

    IMPORT_C TBool IsOn() const;

private:

    virtual void IsOnHasChangedState()=0;

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

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

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

    };

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

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

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

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

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

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

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

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

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

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

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

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

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

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