Implementing the FEP API

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

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.