How to use multiple active objects

Encapsulating the service provider

The class CActiveConsole encapsulates the provision of basic keyboard services. Its iConsole data member is a pointer to the service provider, the CConsoleBase object.

The active object class is defined as:

class CActiveConsole : public CActive
    {
public:
    CActiveConsole(CConsoleBase* aConsole);
    void ConstructL();
    ~CActiveConsole();
    void RequestCharacter();
    void RunL();
    void DoCancel();
    virtual void ProcessKeyPress(TChar aChar)=0;
protected:
    CConsoleBase* iConsole; 
    };

The class constructor takes a pointer to a CConsoleBase object as its single argument and initializes its iConsole data member to this value:

CActiveConsole::CActiveConsole(CConsoleBase* aConsole)
    : iConsole(aConsole)
    {}

The ConstructL() function adds the active object to the active scheduler:

void CActiveConsole::ConstructL()
    {
    CActiveScheduler::Add(this);
    }

The destructor cancels any outstanding request before destroying the active object:

CActiveConsole::~CActiveConsole()
    {
    Cancel();
    }

DoCancel() is implemented to cancel the request to iConsole.

The RequestCharacter() function makes a request for a key press to the service provider by calling iConsole->Read(iStatus) and setting the active request flag:

void CActiveConsole::RequestCharacter()
    {
    iConsole->Read(iStatus);
    SetActive();
    }

The RunL() function makes a call to the ProcessKeyPress() function. This is a pure virtual function that derived classes must implement to handle the key press and to reissue the request:

void CActiveConsole::RunL()
    {
    ProcessKeyPress(TChar(iConsole->KeyCode()));
    }

Further deriving from the active object

The class CMessageKeyProcessor is a concrete class, derived from CActiveConsole. It provides an implementation for theProcessKeyPress() function and can issue or cancel requests to aCExampleActiveObject active object.

This active object class is defined as:

class CMessageKeyProcessor : public CActiveConsole
    {
public:
    ...
    CMessageKeyProcessor(CConsoleBase* aConsole, CExampleActiveObject* iExampleObject);
    void ProcessKeyPress(TChar aChar);
private:
    CExampleActiveObject* iExampleObject;
    };

Notes

• The first constructor parameter specifies a CConsoleBase which will be used to provide asynchronous keyboard input.

• the second constructor parameter specifies a CExampleActiveObject which will be controlled by this CMessageKeyProcessor.

The behaviour of the ProcessKeyPress() function depends on the key code value:

void CMessageKeyProcessor::ProcessKeyPress(TChar aChar)
    {
    if (aChar == 'm' || aChar == 'M')
        {
        iExampleObject->Cancel();
        iExampleObject->IssueRequest();
        }
    if (aChar == 'c' || aChar == 'C')
        {
        iExampleObject->Cancel();
        }
    if (aChar != EKeyEscape)
        {
        RequestCharacter();
        }
    else
        {
        iExampleObject->Cancel();
        CActiveScheduler::Stop();
        }
    }

Enhanced framework

In the code fragment below, an active scheduler is created to which both a CMessageKeyProcessor active object and aCExampleActiveObject active object are added:

LOCAL_C void doExampleL()
    {
    CActiveScheduler* exampleScheduler=new (ELeave) CActiveScheduler;
    CleanupStack::PushL(exampleScheduler);
    CActiveScheduler::Install(exampleScheduler);

    CExampleActiveObject* iExampleObject =
            CExampleActiveObject::NewLC();
    CMessageKeyProcessor* keyProcessor=
             CMessageKeyProcessor::NewLC(console, iExampleObject);

    keyProcessor->RequestCharacter();
    CActiveScheduler::Start();
    CleanupStack::PopAndDestroy(3);
    }

Notes

• An instance of the active scheduler, exampleScheduler is pushed onto the cleanup stack and installed as the current active scheduler.

• An instance of the CExampleActiveObject active object is created.

• An instance of the CMessageKeyProcessor active object is created and this is in control.

• keyProcessor->RequestCharacter() issues a request for keyboard input.

• CActiveScheduler::Start() starts the active scheduler. At least one outstanding request is necessary before the wait loop is started, otherwise the thread hangs. All further request issuing and servicing occurs within this function. The wait loop continues until one of the active objects’ RunL() callsCActiveScheduler::Stop().

• The active objects and the active scheduler are popped from the cleanup stack and destroyed.