williamr@2: /*
williamr@2: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef CENREPNOTIFYHANDLER_H
williamr@2: #define CENREPNOTIFYHANDLER_H
williamr@2: 
williamr@2: // INCLUDES
williamr@2: #include <e32std.h>
williamr@2: #include <e32base.h>
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class MCenRepNotifyHandlerCallback;
williamr@2: class CRepository;
williamr@2: 
williamr@2: /**
williamr@2: * Active object wrapper for Central Repository one-shot notification handling.
williamr@2: * Central Repository Notification Handler API provides an easy-to-use 
williamr@2: * implementation of a CActive-based wrapper for Central Repository single-shot
williamr@2: * notifications. In most cases Central Repository Notification Handler can 
williamr@2: * automatically resubscribe to notifications and fetch the modified value from
williamr@2: * Central Repository. 
williamr@2: * The API consists of the classes CCenRepNotifyHandler and 
williamr@2: * MCenRepNotifyHandlerCallback. The user of this class needs to implement relevant
williamr@2: * MCenRepNotifyHandlerCallback interface methods to receive notifications. 
williamr@2: * The user of Central Repository Notification Handler API needs access to 
williamr@2: * Central Repository (centralrepository.h).
williamr@2: *
williamr@2: * Usage:
williamr@2: *  
williamr@2: * Initialization example (from a class that implements MCenRepNotifyHandlerCallback interface):
williamr@2: * @code
williamr@2: * iSession = CRepository::NewL(KTestUid);
williamr@2: * iNotifyHandler = CCenRepNotifyHandler::NewL(*this, *iSession, CCenRepNotifyHandler::EStringKey, KKey1);
williamr@2: * iNotifyHandler->StartListeningL();
williamr@2: * @endcode
williamr@2: *
williamr@2: * Uninitialization example:
williamr@2: * @code
williamr@2: * iNotifyHandler->StopListening(); 
williamr@2: * delete iNotifyHandler;
williamr@2: * @endcode
williamr@2: *
williamr@2: * Handler method implementation example:
williamr@2: * @code
williamr@2: * void CMyCenRepNotifyTest::HandleNotifyString(TUint32 aId, const TDesC16&  aNewValue)
williamr@2: *    {
williamr@2: *    // Print out the notified value
williamr@2: *    RDebug::Print(_L("Key %d changed, new value: %S"), aId, &aNewValue);
williamr@2: *    }
williamr@2: * @endcode
williamr@2: *
williamr@4: * @publishedAll
williamr@2: * @released
williamr@2: */
williamr@2: class CCenRepNotifyHandler : public CActive
williamr@2:     {
williamr@2:     public:
williamr@2:         /**
williamr@2:         * Defines different key types. Enumeration is used to indicate the 
williamr@2:         * key type that is listened to. 
williamr@2:         */
williamr@2:         enum TCenRepKeyType
williamr@2:         {
williamr@2:             EIntKey,    ///< Key holds a TInt value.
williamr@2:             ERealKey,   ///< Key holds a TReal value.
williamr@2:             EStringKey, ///< Key holds a TDesC16 value.
williamr@2:             EBinaryKey  ///< Key holds a TDesC8 value.
williamr@2:         };
williamr@2: 
williamr@2:         IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback, 
williamr@2:                                                     CRepository& aSession, 
williamr@2:                                                     TCenRepKeyType aKeyType, 
williamr@2:                                                     TUint32 aId );
williamr@2: 
williamr@2:         IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback, 
williamr@2:                                                     CRepository& aSession );
williamr@2: 
williamr@2:         IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback, 
williamr@2:                                                      CRepository& aSession, 
williamr@2:                                                      TCenRepKeyType aKeyType, 
williamr@2:                                                      TUint32 aId );
williamr@2: 
williamr@2:         IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback, 
williamr@2:                                                      CRepository& aSession );
williamr@2:         IMPORT_C void StartListeningL();
williamr@2: 
williamr@2:         IMPORT_C void StopListening();
williamr@2: 
williamr@2: 
williamr@2:         /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         IMPORT_C virtual ~CCenRepNotifyHandler();
williamr@2: 
williamr@2:     protected:
williamr@2: 
williamr@2:         void RunL();
williamr@2:     
williamr@2:         TInt RunError( TInt aError );
williamr@2: 
williamr@2:         void DoCancel();
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback, 
williamr@2:                               CRepository& aSession, 
williamr@2:                               TCenRepKeyType aKeyType, 
williamr@2:                               TUint32 aId );
williamr@2:                                                    
williamr@2:         CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback, 
williamr@2:                               CRepository& aSession );
williamr@2:         TInt OrderNotification();
williamr@2:        
williamr@2:     private:
williamr@2:         
williamr@2:         CRepository& iSession;  // not owned by this class
williamr@2:         MCenRepNotifyHandlerCallback& iCallback; // not owned by this class
williamr@2:         TCenRepKeyType iKeyType;
williamr@2:         TUint32 iId;        
williamr@2:         TBool iWholeRepository;  // The flag to indicate if listening is for whole repository
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: * Class provides a callback interface for handling the notifification
williamr@2: * events from the Central Repository. The Client derives a class 
williamr@2: * from this interface and implements the HandleNotify-methods that 
williamr@2: * interest it.
williamr@2: * An empty default implementation is provided for all of the methods.
williamr@2: * In debug build the default implementations print out a debug trace.
williamr@2: *
williamr@4: * @publishedAll
williamr@2: * @released
williamr@2: */
williamr@2: class MCenRepNotifyHandlerCallback
williamr@2:     {
williamr@2: 
williamr@2:     public:
williamr@2: 
williamr@2:     /** 
williamr@2:     * This callback method is used to notify the client about
williamr@2:     * changes for integer value keys, i.e. key type is EIntKey.
williamr@2:     *
williamr@2:     * @param aId Id of the key that has changed.
williamr@2:     * @param aNewValue The new value of the key.
williamr@2:     * @capability Dependent Capability required depends on implementation of override.
williamr@2:     */
williamr@2:     IMPORT_C virtual void HandleNotifyInt( TUint32 aId, TInt aNewValue );
williamr@2: 
williamr@2:     /** 
williamr@2:     * This callback method is used to notify the client about
williamr@2:     * changes for real value keys, i.e. key type is ERealKey.
williamr@2:     *
williamr@2:     * @param aId Id of the key that has changed.
williamr@2:     * @param aNewValue The new value of the key.
williamr@2:      * @capability Dependent Capability required depends on implementation of override.
williamr@2:    */
williamr@2:     IMPORT_C virtual void HandleNotifyReal( TUint32 aId, TReal aNewValue );
williamr@2: 
williamr@2:     /** 
williamr@2:     * This callback method is used to notify the client about
williamr@2:     * changes for string value keys, i.e. key type is EStringKey.
williamr@2:     *
williamr@2:     * @param aId Id of the key that has changed.
williamr@2:     * @param aNewValue The new value of the key.
williamr@2:     * @capability Dependent Capability required depends on implementation of override.
williamr@2:     */
williamr@2:     IMPORT_C virtual void HandleNotifyString( TUint32 aId, const TDesC16& aNewValue );
williamr@2: 
williamr@2:     /** 
williamr@2:     * This callback method is used to notify the client about
williamr@2:     * changes for binary value keys, i.e. key type is EBinaryKey.
williamr@2:     *
williamr@2:     * @param aId Id of the key that has changed.
williamr@2:     * @param aNewValue The new value of the key.
williamr@2:     * @capability Dependent Capability required depends on implementation of override.
williamr@2:     */
williamr@2:     IMPORT_C virtual void HandleNotifyBinary( TUint32 aId, const TDesC8& aNewValue );
williamr@2: 
williamr@2:     /** 
williamr@2:     * This callback method is used to notify the client about
williamr@2:     * changes in keys when the whole repository is listened for.
williamr@2:     *
williamr@2:     * Note: It is not guaranteed that a notification will be received
williamr@2:     *       for all keys, if multiple keys are changed in rapid succession
williamr@2:     *       by multiple threads or when the whole repository is reset,
williamr@2:     *       therefore only listen for whole repository if this is not an issue.
williamr@2:     *
williamr@2:     * @param aId Id of the key that has changed. If multiple keys were changed by
williamr@2:     *            whole repository reset, value will be KInvalidNotificationId.
williamr@2:     * @capability Dependent Capability required depends on implementation of override.
williamr@2:     */
williamr@2:     IMPORT_C virtual void HandleNotifyGeneric( TUint32 aId );
williamr@2: 
williamr@2:     /** 
williamr@2:     * This callback method is used to notify the client about errors
williamr@2:     * in the handler. Any error in handling causes the handler to stop
williamr@2:     * handling any more notifications. Handling can be restarted with
williamr@2:     * a call to aHandler->StartListeningL(), if the error is non-fatal.
williamr@2:     * However, be careful to trap any errors from this call if this is done.
williamr@2:     *
williamr@2:     * @param aId Id of the key this instance listens to or if notifications for
williamr@2:     *            whole repository are listened, could also be KInvalidNotificationId.
williamr@2:     * @param aError Error code.
williamr@2:     * @param aHandler Pointer to the handler instance. 
williamr@2:     *                 This pointer can be used to identify the handler or restart the listening.
williamr@2:     * @capability Dependent Capability required depends on implementation of override.
williamr@2:     */
williamr@2:     IMPORT_C virtual void HandleNotifyError( TUint32 aId, TInt aError, 
williamr@2:                                             CCenRepNotifyHandler* aHandler );
williamr@2:     };
williamr@2: 
williamr@2: #endif      // CENREPNOTIFYHANDLER_H
williamr@2: 
williamr@2: // End of File