How to write a FEP

Post-platform security – the ECom plugin interface

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 fepbase.h, are unchanged.

Define a class that implements the CCoeFepPlugIn interface

This class must implement the NewFepL() and SynchronouslyExecuteSettingsDialogL() 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 TDesC& aFullFileNameOfDll argument: the ECom plugin implementation is identified by a UID rather than a filename. This means that the implementation of SynchronouslyExecuteSettingsDialogL() is now responsible for locating the resource file needed to execute the settings dialog itself.

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

Provide the factory code required to instantiate the derived class

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 TFEP1PlugIn.cpp):

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

Create an ECom resource file

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,

#include <RegistryInfo.rh>

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 = "";
                    }
                };
            }
        };
    }

Configure the project (mmp) file to build an ECom plugin

The important differences between this and the pre-platform security version are that the targettype must be plugin, the targetpath is no longer required, the specified UID2 must have the correct value for an ECom DLL (0x10009D8D), and you must include a start resource ... end block to compile the ECom resource file. The target keyword is used to specify that the built resource has the same name (without extension) as the DLL. For example,

target     tfep1plugin.dll
targettype     plugin
uid     0x10009D8D 0x102024D0
VENDORID   0x70000001
CAPABILITY  All -Tcb
sourcepath      ..\source
source      TFEP1.CPP TFEP1PlugIn.cpp
systeminclude   ..\include \epoc32\include \epoc32\include\techview \epoc32\include\ecom
library     EUSER.LIB EFSRV.LIB ESTOR.LIB GDI.LIB ETEXT.LIB FBSCLI.LIB BITGDI.LIB 
library     WS32.LIB FORM.LIB CONE.LIB FEPBASE.LIB BAFL.LIB EIKDLG.LIB EIKCOCTL.LIB EIKCTL.LIB
library     ECOM.LIB 
START RESOURCE TFEP1PlugIn.RSS
HEADER
TARGETPATH  \resource\data
lang        01 10
END
start resource 102024d0.rss
#ifdef SYMBIAN_SECURE_ECOM
target tfep1plugin.rsc
#endif
END

The CCoeFep class

The parts of CCoeFep relevant to classes deriving from it are shown below:

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

Note that CCoeFep inherits, but does not override, some pure virtual functions from its base classes MFepAttributeStorer, MCoeForegroundObserver and MCoeFocusObserver. These therefore need to be overridden in addition to CCoeFep’s own pure virtual member functions. The details of the member functions of CCoeFep and its base classes are explained in various sections of this document.

The CCoeControl class

The CCoeControl class (defined in epoc32\include\COECNTRL.H) 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 CCoeControl is a necessity because of the need to use the control stack (see Intercepting key events, below). Thus although deriving from CCoeControl is not explicitly demanded by the FEP architecture, it is assumed throughout this document that the object of the CCoeFep-derived class owns an object of a CCoeControl-derived class.