os/persistentdata/persistentstorage/centralrepository/cenrepnotifierhandler/inc/cenrepnotifyhandler.h
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/centralrepository/cenrepnotifierhandler/inc/cenrepnotifyhandler.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,231 @@
1.4 +/*
1.5 +* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +#ifndef CENREPNOTIFYHANDLER_H
1.24 +#define CENREPNOTIFYHANDLER_H
1.25 +
1.26 +// INCLUDES
1.27 +#include <e32std.h>
1.28 +#include <e32base.h>
1.29 +
1.30 +// FORWARD DECLARATIONS
1.31 +class MCenRepNotifyHandlerCallback;
1.32 +class CRepository;
1.33 +
1.34 +/**
1.35 +* Active object wrapper for Central Repository one-shot notification handling.
1.36 +* Central Repository Notification Handler API provides an easy-to-use
1.37 +* implementation of a CActive-based wrapper for Central Repository single-shot
1.38 +* notifications. In most cases Central Repository Notification Handler can
1.39 +* automatically resubscribe to notifications and fetch the modified value from
1.40 +* Central Repository.
1.41 +* The API consists of the classes CCenRepNotifyHandler and
1.42 +* MCenRepNotifyHandlerCallback. The user of this class needs to implement relevant
1.43 +* MCenRepNotifyHandlerCallback interface methods to receive notifications.
1.44 +* The user of Central Repository Notification Handler API needs access to
1.45 +* Central Repository (centralrepository.h).
1.46 +*
1.47 +* Usage:
1.48 +*
1.49 +* Initialization example (from a class that implements MCenRepNotifyHandlerCallback interface):
1.50 +* @code
1.51 +* iSession = CRepository::NewL(KTestUid);
1.52 +* iNotifyHandler = CCenRepNotifyHandler::NewL(*this, *iSession, CCenRepNotifyHandler::EStringKey, KKey1);
1.53 +* iNotifyHandler->StartListeningL();
1.54 +* @endcode
1.55 +*
1.56 +* Uninitialization example:
1.57 +* @code
1.58 +* iNotifyHandler->StopListening();
1.59 +* delete iNotifyHandler;
1.60 +* @endcode
1.61 +*
1.62 +* Handler method implementation example:
1.63 +* @code
1.64 +* void CMyCenRepNotifyTest::HandleNotifyString(TUint32 aId, const TDesC16& aNewValue)
1.65 +* {
1.66 +* // Print out the notified value
1.67 +* RDebug::Print(_L("Key %d changed, new value: %S"), aId, &aNewValue);
1.68 +* }
1.69 +* @endcode
1.70 +*
1.71 +* @publishedAll
1.72 +* @released
1.73 +*/
1.74 +class CCenRepNotifyHandler : public CActive
1.75 + {
1.76 + public:
1.77 + /**
1.78 + * Defines different key types. Enumeration is used to indicate the
1.79 + * key type that is listened to.
1.80 + */
1.81 + enum TCenRepKeyType
1.82 + {
1.83 + EIntKey, ///< Key holds a TInt value.
1.84 + ERealKey, ///< Key holds a TReal value.
1.85 + EStringKey, ///< Key holds a TDesC16 value.
1.86 + EBinaryKey ///< Key holds a TDesC8 value.
1.87 + };
1.88 +
1.89 + IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback,
1.90 + CRepository& aSession,
1.91 + TCenRepKeyType aKeyType,
1.92 + TUint32 aId );
1.93 +
1.94 + IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback,
1.95 + CRepository& aSession );
1.96 +
1.97 + IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback,
1.98 + CRepository& aSession,
1.99 + TCenRepKeyType aKeyType,
1.100 + TUint32 aId );
1.101 +
1.102 + IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback,
1.103 + CRepository& aSession );
1.104 + IMPORT_C void StartListeningL();
1.105 +
1.106 + IMPORT_C void StopListening();
1.107 +
1.108 +
1.109 + /**
1.110 + * Destructor.
1.111 + */
1.112 + IMPORT_C virtual ~CCenRepNotifyHandler();
1.113 +
1.114 + protected:
1.115 +
1.116 + void RunL();
1.117 +
1.118 + TInt RunError( TInt aError );
1.119 +
1.120 + void DoCancel();
1.121 +
1.122 + private:
1.123 +
1.124 + CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback,
1.125 + CRepository& aSession,
1.126 + TCenRepKeyType aKeyType,
1.127 + TUint32 aId );
1.128 +
1.129 + CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback,
1.130 + CRepository& aSession );
1.131 + TInt OrderNotification();
1.132 +
1.133 + private:
1.134 +
1.135 + CRepository& iSession; // not owned by this class
1.136 + MCenRepNotifyHandlerCallback& iCallback; // not owned by this class
1.137 + TCenRepKeyType iKeyType;
1.138 + TUint32 iId;
1.139 + TBool iWholeRepository; // The flag to indicate if listening is for whole repository
1.140 + };
1.141 +
1.142 +
1.143 +/**
1.144 +* Class provides a callback interface for handling the notifification
1.145 +* events from the Central Repository. The Client derives a class
1.146 +* from this interface and implements the HandleNotify-methods that
1.147 +* interest it.
1.148 +* An empty default implementation is provided for all of the methods.
1.149 +* In debug build the default implementations print out a debug trace.
1.150 +*
1.151 +* @publishedAll
1.152 +* @released
1.153 +*/
1.154 +class MCenRepNotifyHandlerCallback
1.155 + {
1.156 +
1.157 + public:
1.158 +
1.159 + /**
1.160 + * This callback method is used to notify the client about
1.161 + * changes for integer value keys, i.e. key type is EIntKey.
1.162 + *
1.163 + * @param aId Id of the key that has changed.
1.164 + * @param aNewValue The new value of the key.
1.165 + * @capability Dependent Capability required depends on implementation of override.
1.166 + */
1.167 + IMPORT_C virtual void HandleNotifyInt( TUint32 aId, TInt aNewValue );
1.168 +
1.169 + /**
1.170 + * This callback method is used to notify the client about
1.171 + * changes for real value keys, i.e. key type is ERealKey.
1.172 + *
1.173 + * @param aId Id of the key that has changed.
1.174 + * @param aNewValue The new value of the key.
1.175 + * @capability Dependent Capability required depends on implementation of override.
1.176 + */
1.177 + IMPORT_C virtual void HandleNotifyReal( TUint32 aId, TReal aNewValue );
1.178 +
1.179 + /**
1.180 + * This callback method is used to notify the client about
1.181 + * changes for string value keys, i.e. key type is EStringKey.
1.182 + *
1.183 + * @param aId Id of the key that has changed.
1.184 + * @param aNewValue The new value of the key.
1.185 + * @capability Dependent Capability required depends on implementation of override.
1.186 + */
1.187 + IMPORT_C virtual void HandleNotifyString( TUint32 aId, const TDesC16& aNewValue );
1.188 +
1.189 + /**
1.190 + * This callback method is used to notify the client about
1.191 + * changes for binary value keys, i.e. key type is EBinaryKey.
1.192 + *
1.193 + * @param aId Id of the key that has changed.
1.194 + * @param aNewValue The new value of the key.
1.195 + * @capability Dependent Capability required depends on implementation of override.
1.196 + */
1.197 + IMPORT_C virtual void HandleNotifyBinary( TUint32 aId, const TDesC8& aNewValue );
1.198 +
1.199 + /**
1.200 + * This callback method is used to notify the client about
1.201 + * changes in keys when the whole repository is listened for.
1.202 + *
1.203 + * Note: It is not guaranteed that a notification will be received
1.204 + * for all keys, if multiple keys are changed in rapid succession
1.205 + * by multiple threads or when the whole repository is reset,
1.206 + * therefore only listen for whole repository if this is not an issue.
1.207 + *
1.208 + * @param aId Id of the key that has changed. If multiple keys were changed by
1.209 + * whole repository reset, value will be KInvalidNotificationId.
1.210 + * @capability Dependent Capability required depends on implementation of override.
1.211 + */
1.212 + IMPORT_C virtual void HandleNotifyGeneric( TUint32 aId );
1.213 +
1.214 + /**
1.215 + * This callback method is used to notify the client about errors
1.216 + * in the handler. Any error in handling causes the handler to stop
1.217 + * handling any more notifications. Handling can be restarted with
1.218 + * a call to aHandler->StartListeningL(), if the error is non-fatal.
1.219 + * However, be careful to trap any errors from this call if this is done.
1.220 + *
1.221 + * @param aId Id of the key this instance listens to or if notifications for
1.222 + * whole repository are listened, could also be KInvalidNotificationId.
1.223 + * @param aError Error code.
1.224 + * @param aHandler Pointer to the handler instance.
1.225 + * This pointer can be used to identify the handler or restart the listening.
1.226 + * @capability Dependent Capability required depends on implementation of override.
1.227 + */
1.228 + IMPORT_C virtual void HandleNotifyError( TUint32 aId, TInt aError,
1.229 + CCenRepNotifyHandler* aHandler );
1.230 + };
1.231 +
1.232 +#endif // CENREPNOTIFYHANDLER_H
1.233 +
1.234 +// End of File