1 /*

     2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CENREPNOTIFYHANDLER_H

    21 #define CENREPNOTIFYHANDLER_H

    22 

    23 // INCLUDES

    24 #include <e32std.h>

    25 #include <e32base.h>

    26 

    27 // FORWARD DECLARATIONS

    28 class MCenRepNotifyHandlerCallback;

    29 class CRepository;

    30 

    31 /**

    32 * Active object wrapper for Central Repository one-shot notification handling.

    33 * Central Repository Notification Handler API provides an easy-to-use 

    34 * implementation of a CActive-based wrapper for Central Repository single-shot

    35 * notifications. In most cases Central Repository Notification Handler can 

    36 * automatically resubscribe to notifications and fetch the modified value from

    37 * Central Repository. 

    38 * The API consists of the classes CCenRepNotifyHandler and 

    39 * MCenRepNotifyHandlerCallback. The user of this class needs to implement relevant

    40 * MCenRepNotifyHandlerCallback interface methods to receive notifications. 

    41 * The user of Central Repository Notification Handler API needs access to 

    42 * Central Repository (centralrepository.h).

    43 *

    44 * Usage:

    45 *  

    46 * Initialization example (from a class that implements MCenRepNotifyHandlerCallback interface):

    47 * @code

    48 * iSession = CRepository::NewL(KTestUid);

    49 * iNotifyHandler = CCenRepNotifyHandler::NewL(*this, *iSession, CCenRepNotifyHandler::EStringKey, KKey1);

    50 * iNotifyHandler->StartListeningL();

    51 * @endcode

    52 *

    53 * Uninitialization example:

    54 * @code

    55 * iNotifyHandler->StopListening(); 

    56 * delete iNotifyHandler;

    57 * @endcode

    58 *

    59 * Handler method implementation example:

    60 * @code

    61 * void CMyCenRepNotifyTest::HandleNotifyString(TUint32 aId, const TDesC16&  aNewValue)

    62 *    {

    63 *    // Print out the notified value

    64 *    RDebug::Print(_L("Key %d changed, new value: %S"), aId, &aNewValue);

    65 *    }

    66 * @endcode

    67 *

    68 * @publishedAll

    69 * @released

    70 */

    71 class CCenRepNotifyHandler : public CActive

    72     {

    73     public:

    74         /**

    75         * Defines different key types. Enumeration is used to indicate the 

    76         * key type that is listened to. 

    77         */

    78         enum TCenRepKeyType

    79         {

    80             EIntKey,    ///< Key holds a TInt value.

    81             ERealKey,   ///< Key holds a TReal value.

    82             EStringKey, ///< Key holds a TDesC16 value.

    83             EBinaryKey  ///< Key holds a TDesC8 value.

    84         };

    85 

    86         IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback, 

    87                                                     CRepository& aSession, 

    88                                                     TCenRepKeyType aKeyType, 

    89                                                     TUint32 aId );

    90 

    91         IMPORT_C static CCenRepNotifyHandler* NewL( MCenRepNotifyHandlerCallback& aCallback, 

    92                                                     CRepository& aSession );

    93 

    94         IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback, 

    95                                                      CRepository& aSession, 

    96                                                      TCenRepKeyType aKeyType, 

    97                                                      TUint32 aId );

    98 

    99         IMPORT_C static CCenRepNotifyHandler* NewLC( MCenRepNotifyHandlerCallback& aCallback, 

   100                                                      CRepository& aSession );

   101         IMPORT_C void StartListeningL();

   102 

   103         IMPORT_C void StopListening();

   104 

   105 

   106         /**

   107         * Destructor.

   108         */

   109         IMPORT_C virtual ~CCenRepNotifyHandler();

   110 

   111     protected:

   112 

   113         void RunL();

   114     

   115         TInt RunError( TInt aError );

   116 

   117         void DoCancel();

   118 

   119     private:

   120 

   121         CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback, 

   122                               CRepository& aSession, 

   123                               TCenRepKeyType aKeyType, 

   124                               TUint32 aId );

   125                                                    

   126         CCenRepNotifyHandler( MCenRepNotifyHandlerCallback& aCallback, 

   127                               CRepository& aSession );

   128         TInt OrderNotification();

   129        

   130     private:

   131         

   132         CRepository& iSession;  // not owned by this class

   133         MCenRepNotifyHandlerCallback& iCallback; // not owned by this class

   134         TCenRepKeyType iKeyType;

   135         TUint32 iId;        

   136         TBool iWholeRepository;  // The flag to indicate if listening is for whole repository

   137     };

   138 

   139 

   140 /**

   141 * Class provides a callback interface for handling the notifification

   142 * events from the Central Repository. The Client derives a class 

   143 * from this interface and implements the HandleNotify-methods that 

   144 * interest it.

   145 * An empty default implementation is provided for all of the methods.

   146 * In debug build the default implementations print out a debug trace.

   147 *

   148 * @publishedAll

   149 * @released

   150 */

   151 class MCenRepNotifyHandlerCallback

   152     {

   153 

   154     public:

   155 

   156     /** 

   157     * This callback method is used to notify the client about

   158     * changes for integer value keys, i.e. key type is EIntKey.

   159     *

   160     * @param aId Id of the key that has changed.

   161     * @param aNewValue The new value of the key.

   162     * @capability Dependent Capability required depends on implementation of override.

   163     */

   164     IMPORT_C virtual void HandleNotifyInt( TUint32 aId, TInt aNewValue );

   165 

   166     /** 

   167     * This callback method is used to notify the client about

   168     * changes for real value keys, i.e. key type is ERealKey.

   169     *

   170     * @param aId Id of the key that has changed.

   171     * @param aNewValue The new value of the key.

   172      * @capability Dependent Capability required depends on implementation of override.

   173    */

   174     IMPORT_C virtual void HandleNotifyReal( TUint32 aId, TReal aNewValue );

   175 

   176     /** 

   177     * This callback method is used to notify the client about

   178     * changes for string value keys, i.e. key type is EStringKey.

   179     *

   180     * @param aId Id of the key that has changed.

   181     * @param aNewValue The new value of the key.

   182     * @capability Dependent Capability required depends on implementation of override.

   183     */

   184     IMPORT_C virtual void HandleNotifyString( TUint32 aId, const TDesC16& aNewValue );

   185 

   186     /** 

   187     * This callback method is used to notify the client about

   188     * changes for binary value keys, i.e. key type is EBinaryKey.

   189     *

   190     * @param aId Id of the key that has changed.

   191     * @param aNewValue The new value of the key.

   192     * @capability Dependent Capability required depends on implementation of override.

   193     */

   194     IMPORT_C virtual void HandleNotifyBinary( TUint32 aId, const TDesC8& aNewValue );

   195 

   196     /** 

   197     * This callback method is used to notify the client about

   198     * changes in keys when the whole repository is listened for.

   199     *

   200     * Note: It is not guaranteed that a notification will be received

   201     *       for all keys, if multiple keys are changed in rapid succession

   202     *       by multiple threads or when the whole repository is reset,

   203     *       therefore only listen for whole repository if this is not an issue.

   204     *

   205     * @param aId Id of the key that has changed. If multiple keys were changed by

   206     *            whole repository reset, value will be KInvalidNotificationId.

   207     * @capability Dependent Capability required depends on implementation of override.

   208     */

   209     IMPORT_C virtual void HandleNotifyGeneric( TUint32 aId );

   210 

   211     /** 

   212     * This callback method is used to notify the client about errors

   213     * in the handler. Any error in handling causes the handler to stop

   214     * handling any more notifications. Handling can be restarted with

   215     * a call to aHandler->StartListeningL(), if the error is non-fatal.

   216     * However, be careful to trap any errors from this call if this is done.

   217     *

   218     * @param aId Id of the key this instance listens to or if notifications for

   219     *            whole repository are listened, could also be KInvalidNotificationId.

   220     * @param aError Error code.

   221     * @param aHandler Pointer to the handler instance. 

   222     *                 This pointer can be used to identify the handler or restart the listening.

   223     * @capability Dependent Capability required depends on implementation of override.

   224     */

   225     IMPORT_C virtual void HandleNotifyError( TUint32 aId, TInt aError, 

   226                                             CCenRepNotifyHandler* aHandler );

   227     };

   228 

   229 #endif      // CENREPNOTIFYHANDLER_H

   230 

   231 // End of File