Central Repository Notification Handler API: Using Central Repository Notification Handler API

To use CCenRepNotifyHandler, the client must first construct an instance of the class. After an instance is created, the StartListeningL() method call activates the notifications and the StopListening() method call cancels them.

Whenever some key value changes in Central Repository, the CCenRepNotifyHandler::RunL() method is called. In this method the notification is resubscribed and the appropriate callback method of the MCenRepNotifyHandlerCallback interface is called. In case of single key notifications, the key type-specific method is used (HandleNotifyInt(), HandleNotifyReal(), HandleNotifyString() or HandleNotifyBinary()). In the case of repository-wide notifications, HandleNotifyGeneric() is used.

If an error of any kind occurs in the notification process, HandleNotifyError() method is called. If this method is called, the notification subscription is not be renewed (that is, the state of the notifier is the same as if StopListening() was called).

The client need to derive a class from the MCenRepNotifyHandlerCallback interface and implement the HandleNotify methods that interest it. The following code snippet gives an example of the header of the class implemented by the client.

// INCLUDES
#include <e32std.h>
#include <cenrepnotifyhandler.h> // link against commonengine.lib

class CMyCenRepNotifyTest : public CBase, public MCenRepNotifyHandlerCallback
    {
    public:
        static CMyCenRepNotifyTest* NewL(TInt aTestCase);

        /**
        * Destructor.
        */
        virtual ~CMyCenRepNotifyTest();

        // MCenRepNotifyHandlerCallback
        void HandleNotifyInt(TUint32 aId, TInt aNewValue);
        void HandleNotifyError(TUint32 aId, TInt error, CCenRepNotifyHandler* aHandler);
        void HandleNotifyGeneric(TUint32 aId);

    private:
        /**
        * Constructor.
        */
        CMyCenRepNotifyTest();

        void ConstructL(TInt aTestCase);

    private:
        CCenRepNotifyHandler* iNotifyHandler;
        CRepository* iSession;
    };

Create an instance used for listening to notifications

A CCenRepNotifyHandler instance can be created by using NewL() or NewLC() methods. A valid reference to a Central Repository session (CRepository&) and a callback implementation class (MCenRepNotifyHandlerCallback&) must be available and passed to the constructor. The type and the ID of the key must also be specified at this time, if creating an instance for listening to a single key changes.

The following code snippet demonstrates how to create an instance for listening to a single key or an instance for listening to all keys in a single repository.

void CMyCenRepNotifyTest::ConstructL(TInt aTestCase)
    {   
    // Create a CRepository object for accessing a repository.
    iSession = CRepository::NewL(KTestUid);

    // test case 1 is single key notify, test case 2 is whole UID notify.
    if ( aTestCase == 1 )
        {
        iNotifyHandler = CCenRepNotifyHandler::NewL(*this, *iSession, EIntKey, KKey2);
        }
    else if ( aTestCase == 2 )
        {
        iNotifyHandler = CCenRepNotifyHandler::NewL(*this, *iSession);
        }
    }

Start listening for notifications

The StartListeningL() method call activates the notifications. The following code snippet demonstrates how to start listening for notifications.

iNotifyHandler->StartListeningL();

Stop listening for notifications

The StopListening() method call cancels the notifications. The following code snippet demonstrates how to stop listening for notifications.

iNotifyHandler->StopListening();

Release the instance

When the CCenRepNotifyHandler instance is not needed anymore it must be released. The following code snippet demonstrates how to release the instance.

Also the Central Repository session is released. The session can be released only after all instances of CCenRepNotifyHandler have been released.

CMyCenRepNotifyTest::~CMyCenRepNotifyTest()
    {
    delete iNotifyHandler;
    delete iSession;
    }

Error handling

The leave mechanism of the Symbian OS is used to handle error conditions on method calls.

When an error occurs in an error notification, the error is passed to the callback object via the HandleNotifyError() method and listening is canceled.