/*

 * 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