/*
* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "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:
*
* Description:
*
*/



#ifndef CENREPNOTIFYHANDLER_H
#define CENREPNOTIFYHANDLER_H

// INCLUDES
#include <e32std.h>
#include <e32base.h>

// FORWARD DECLARATIONS
class MCenRepNotifyHandlerCallback;
class CRepository;

/**
* Active object wrapper for Central Repository one-shot notification handling.
* Central Repository Notification Handler API provides an easy-to-use 
* implementation of a CActive-based wrapper for Central Repository single-shot
* notifications. In most cases Central Repository Notification Handler can 
* automatically resubscribe to notifications and fetch the modified value from
* Central Repository. 
* The API consists of the classes CCenRepNotifyHandler and 
* MCenRepNotifyHandlerCallback. The user of this class needs to implement relevant
* MCenRepNotifyHandlerCallback interface methods to receive notifications. 
* The user of Central Repository Notification Handler API needs access to 
* Central Repository (centralrepository.h).
*
* Usage:
*  
* Initialization example (from a class that implements MCenRepNotifyHandlerCallback interface):
* @code
* iSession = CRepository::NewL(KTestUid);
* iNotifyHandler = CCenRepNotifyHandler::NewL(*this, *iSession, CCenRepNotifyHandler::EStringKey, KKey1);
* iNotifyHandler->StartListeningL();
* @endcode
*
* Uninitialization example:
* @code
* iNotifyHandler->StopListening(); 
* delete iNotifyHandler;
* @endcode
*
* Handler method implementation example:
* @code
* void CMyCenRepNotifyTest::HandleNotifyString(TUint32 aId, const TDesC16&  aNewValue)
*    {
*    // Print out the notified value
*    RDebug::Print(_L("Key %d changed, new value: %S"), aId, &aNewValue);
*    }
* @endcode
*
* @publishedAll
* @released
*/
class CCenRepNotifyHandler : public CActive
    {
    public:
        /**
        * Defines different key types. Enumeration is used to indicate the 
        * key type that is listened to. 
        */
        enum TCenRepKeyType
        {
            EIntKey,    ///< Key holds a TInt value.
            ERealKey,   ///< Key holds a TReal value.
            EStringKey, ///< Key holds a TDesC16 value.
            EBinaryKey  ///< Key holds a TDesC8 value.
        };

        IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback, 
                                                    CRepository& aSession, 
                                                    TCenRepKeyType aKeyType, 
                                                    TUint32 aId );

        IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback, 
                                                    CRepository& aSession );

        IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback, 
                                                     CRepository& aSession, 
                                                     TCenRepKeyType aKeyType, 
                                                     TUint32 aId );

        IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback, 
                                                     CRepository& aSession );
        IMPORT_C void StartListeningL();

        IMPORT_C void StopListening();


        /**
        * Destructor.
        */
        IMPORT_C virtual ~CCenRepNotifyHandler();

    protected:

        void RunL();
    
        TInt RunError( TInt aError );

        void DoCancel();

    private:

        CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback, 
                              CRepository& aSession, 
                              TCenRepKeyType aKeyType, 
                              TUint32 aId );
                                                   
        CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback, 
                              CRepository& aSession );
        TInt OrderNotification();
       
    private:
        
        CRepository& iSession;  // not owned by this class
        MCenRepNotifyHandlerCallback& iCallback; // not owned by this class
        TCenRepKeyType iKeyType;
        TUint32 iId;        
        TBool iWholeRepository;  // The flag to indicate if listening is for whole repository
    };


/**
* Class provides a callback interface for handling the notifification
* events from the Central Repository. The Client derives a class 
* from this interface and implements the HandleNotify-methods that 
* interest it.
* An empty default implementation is provided for all of the methods.
* In debug build the default implementations print out a debug trace.
*
* @publishedAll
* @released
*/
class MCenRepNotifyHandlerCallback
    {

    public:

    /** 
    * This callback method is used to notify the client about
    * changes for integer value keys, i.e. key type is EIntKey.
    *
    * @param aId Id of the key that has changed.
    * @param aNewValue The new value of the key.
    * @capability Dependent Capability required depends on implementation of override.
    */
    IMPORT_C virtual void HandleNotifyInt( TUint32 aId, TInt aNewValue );

    /** 
    * This callback method is used to notify the client about
    * changes for real value keys, i.e. key type is ERealKey.
    *
    * @param aId Id of the key that has changed.
    * @param aNewValue The new value of the key.
     * @capability Dependent Capability required depends on implementation of override.
   */
    IMPORT_C virtual void HandleNotifyReal( TUint32 aId, TReal aNewValue );

    /** 
    * This callback method is used to notify the client about
    * changes for string value keys, i.e. key type is EStringKey.
    *
    * @param aId Id of the key that has changed.
    * @param aNewValue The new value of the key.
    * @capability Dependent Capability required depends on implementation of override.
    */
    IMPORT_C virtual void HandleNotifyString( TUint32 aId, const TDesC16& aNewValue );

    /** 
    * This callback method is used to notify the client about
    * changes for binary value keys, i.e. key type is EBinaryKey.
    *
    * @param aId Id of the key that has changed.
    * @param aNewValue The new value of the key.
    * @capability Dependent Capability required depends on implementation of override.
    */
    IMPORT_C virtual void HandleNotifyBinary( TUint32 aId, const TDesC8& aNewValue );

    /** 
    * This callback method is used to notify the client about
    * changes in keys when the whole repository is listened for.
    *
    * Note: It is not guaranteed that a notification will be received
    *       for all keys, if multiple keys are changed in rapid succession
    *       by multiple threads or when the whole repository is reset,
    *       therefore only listen for whole repository if this is not an issue.
    *
    * @param aId Id of the key that has changed. If multiple keys were changed by
    *            whole repository reset, value will be KInvalidNotificationId.
    * @capability Dependent Capability required depends on implementation of override.
    */
    IMPORT_C virtual void HandleNotifyGeneric( TUint32 aId );

    /** 
    * This callback method is used to notify the client about errors
    * in the handler. Any error in handling causes the handler to stop
    * handling any more notifications. Handling can be restarted with
    * a call to aHandler->StartListeningL(), if the error is non-fatal.
    * However, be careful to trap any errors from this call if this is done.
    *
    * @param aId Id of the key this instance listens to or if notifications for
    *            whole repository are listened, could also be KInvalidNotificationId.
    * @param aError Error code.
    * @param aHandler Pointer to the handler instance. 
    *                 This pointer can be used to identify the handler or restart the listening.
    * @capability Dependent Capability required depends on implementation of override.
    */
    IMPORT_C virtual void HandleNotifyError( TUint32 aId, TInt aError, 
                                            CCenRepNotifyHandler* aHandler );
    };

#endif      // CENREPNOTIFYHANDLER_H

// End of File