diff -r 000000000000 -r 08ec8eefde2f persistentstorage/centralrepository/cenrepnotifierhandler/inc/cenrepnotifyhandler.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/persistentstorage/centralrepository/cenrepnotifierhandler/inc/cenrepnotifyhandler.h Fri Jan 22 11:06:30 2010 +0200 @@ -0,0 +1,231 @@ +/* +* 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 +#include + +// 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