1 activeapdb.h

     1 /*

     2 * Copyright (c) 2002 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Declaration of classes CActiveApDb

    15 *               and MActiveApDbObserver.

    16 *

    17 */

    18 

    19 

    20 #ifndef ACTIVE_APDB_H

    21 #define ACTIVE_APDB_H

    22 

    23 // Deprecation warning

    24 #warning This header file has been deprecated. Will be removed in one of the next SDK releases.

    25 

    26 

    27 //  INCLUDES

    28 #include <commdb.h>

    29 #include <ApEngineVer.h>

    30 

    31 /*

    32 // Enum for DATABASE_TYPE field

    33 // Will be deprecated in 7.0

    34 enum TCommDbDatabaseType

    35     {

    36     EUnspecified = 0,   // not specifying which type it is - any type of 

    37                         // database can be opened with this parameter

    38     EIAP,

    39     EISP

    40     };

    41 */

    42 

    43 // CONSTANTS

    44 const TInt KErrActiveApDbObserverNotFound = -500;

    45 

    46 // FORWARD DECLARATION

    47 class CActiveApDbNotifier;

    48 

    49 // CLASS DECLARATION

    50 

    51 /**

    52 * Mixin protocol for handling events from a CCommsDatabase.

    53 * Events are related to database changes and availability.

    54 */

    55 class MActiveApDbObserver

    56     {

    57     public:     // types

    58         enum TEvent       /// Events reported to the database observer.

    59             {

    60             EDbChanged,   ///< Database has changed.

    61             EDbClosing,   ///< Database is about to close.

    62             EDbAvailable  ///< Database is available again.(E.g. after unlock)

    63             };

    64 

    65     public:     // new methods

    66 

    67         /**

    68         * Derived classes should implement this method, and act accordingly

    69         * to database events.

    70         * @param anEvent Database-related event.

    71         *

    72         * @deprecated

    73         */

    74         IMPORT_C virtual void HandleApDbEventL( TEvent anEvent ) = 0;

    75 

    76     };

    77 

    78 /**

    79 * This class manages and guards database integrity

    80 * by handling all events that are related to the database. These events

    81 * may originate from the system (Shutdown, Backup/Restore) and from the

    82 * database itself. The events are transformed into a simple protocol,

    83 * defined by MActiveApDbObserver.

    84 * Expects an active scheduler to be installed and running.

    85 */

    86 NONSHARABLE_CLASS( CActiveApDb ) : public CBase

    87     {

    88 

    89     public:     // Constructors and destructor

    90         /**

    91         * Two-phased constructor. Leaves on failure.

    92         * @param aType The desired type of the CCommsDatabase object.

    93         * Defaults to EDatabaseTypeIAP.

    94         * @return The constructed CActiveApDb object.

    95         *

    96         * @deprecated

    97         */

    98         IMPORT_C static CActiveApDb* NewL

    99             ( TCommDbDatabaseType aType = EDatabaseTypeIAP );

   100 

   101 

   102 

   103         /**

   104         * Destructor.

   105         *

   106         * @deprecated

   107         */

   108         IMPORT_C virtual ~CActiveApDb();

   109 

   110     protected:  // Constructors

   111 

   112         /**

   113         * Second phase constructor. Leaves on failure.

   114         * @param aType The desired type of the CCommsDatabase object.

   115         * events.

   116         */

   117         void ConstructL();

   118 

   119     public:     // new methods

   120         /**

   121         * Adds an observer to the list of observers to be notified

   122         * about the DB events.

   123         * Also automatically starts observation and notification.

   124         * The order of notification will be exactly the order of registration.

   125         * @param anObserver Observer to be notified about database-related

   126         * events.

   127         *

   128         * @deprecated

   129         */

   130         IMPORT_C void AddObserverL( MActiveApDbObserver* anObserver );

   131 

   132 

   133         /**

   134         * Removes an observer. If not added, silently ignores.

   135         * @param anObserver The observer.

   136         *

   137         * @deprecated

   138         */

   139         IMPORT_C void RemoveObserver( MActiveApDbObserver* anObserver );

   140 

   141 

   142         /**

   143         * Returns the CCommsDatabase.

   144         * Required because we can not derive from CCommsDatabase...

   145         *

   146         * @deprecated

   147         */

   148         IMPORT_C CCommsDatabase*  Database();

   149 

   150     private:

   151         /**

   152         * Handle events from the database (DBMS).

   153         * The order of notification is the order of registration.

   154         * @param anEvent Event generated by DBMS. Values from

   155         * RDbNotifier::TEvent, or KErrCancel.

   156         */

   157         void HandleDbEventL( TInt anEvent );

   158 

   159 

   160         /**

   161         * Notify all observers about an event.

   162         * @param anEvent Event to be sent to observers.

   163         */

   164         void NotifyObserversL( MActiveApDbObserver::TEvent anEvent );

   165 

   166     friend class CActiveApDbNotifier;

   167 

   168     private:    // types

   169         /**

   170         * Default constructor. Can not leave.

   171         */

   172         CActiveApDb();

   173 

   174 

   175         enum TState             /// State of the finite state machine.

   176             {

   177             EClosed,            ///< Closed and idle.

   178             EReady,             ///< Open and ready for use.

   179             EWaitClose,         ///< Closed, waiting for other users to close.

   180             EWaitBackupRestore, ///< Closed, waiting Backup/Restore to finish.

   181             EWaitShutdown       ///< Closed, waiting to die.

   182             };

   183 

   184     private:        // Data

   185         CArrayPtrFlat<MActiveApDbObserver>* iObservers;   ///< Observers.

   186 

   187         CCommsDatabase*     iDb;    // Creates & owns it !

   188         // CommsDb has its own RDbNotifier...

   189         TState iState;  ///< Current state of the database.

   190         CActiveApDbNotifier*    iDbNotifier;

   191     };

   192 

   193 #endif

   194 

   195 // End of File