1 /*

     2 * Copyright (c) 2002-2005 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: Class that provides access to landmark databases.

    15 *

    16 *

    17 */

    18 

    19 

    20 #ifndef CPOSLMLOCALDBACCESS_H

    21 #define CPOSLMLOCALDBACCESS_H

    22 

    23 #include <d32dbms.h>

    24 #include <EPos_CPosLandmarkDatabase.h> // For TSize

    25 

    26 enum TPosLmInitParams

    27     {

    28     ENoInit     = 0x0000,   // No initialization needed.

    29     ECreated    = 0x0001,   // Database has been created.

    30     ELanguage   = 0x0002,   // Language has changed.

    31     EIndexes    = 0x0004    // Database missing some indexes

    32     };

    33 

    34 /**

    35 *  Class that provides access to landmark databases.

    36 *  Responsible for creating and opening landmark databases. It is also

    37 *  responsible for transaction handling and for providing a handle to the

    38 *  database.

    39 *

    40 *  @lib eposlmlocalaccess.lib

    41 */

    42 class CPosLmLocalDbAccess : public CBase

    43     {

    44     public:  // Data types

    45 

    46         /**

    47         * Preparation type for PrepareViewLC.

    48         */

    49         enum TPreparationType

    50             {

    51             EAddPreparation = 0,

    52             EUpdatablePreparation

    53             };

    54 

    55         /**

    56         * Compact level type for NewL.

    57         */

    58         enum TCompactLevelType

    59             {

    60             ELocalCompactLevel = 0,

    61             EServerCompactLevel

    62             };

    63 

    64     public:  // Constructors and destructor

    65 

    66         /**

    67         * Two-phased constructor.

    68         * @param aCompactLevel The compact level type to compare with when

    69         *   deciding if compact is needed.

    70         */

    71         IMPORT_C static CPosLmLocalDbAccess* NewL(

    72         /* IN  */   TCompactLevelType aCompactLevel = ELocalCompactLevel

    73         );

    74 

    75         /**

    76         * Destructor.

    77         */

    78         IMPORT_C virtual ~CPosLmLocalDbAccess();

    79 

    80     public: // New functions

    81 

    82         /**

    83         * Begins a transaction and puts a rollback function on the clean-up

    84         * stack.

    85         */

    86         IMPORT_C void BeginTransactionLC();

    87 

    88         /**

    89         * Commits a transaction and pops the rollback function from the

    90         * clean-up stack. Rollback function is not popped if commit fails.

    91         */

    92         IMPORT_C void CommitTransactionAndPopL();

    93 

    94         /**

    95         * Returns a handle to the database. Do NOT close the RDbNamedDatabase

    96         * object when done with it. This will close the database for the client.

    97         * The ownership still belongs to this class. The handle is used for

    98         * issuing sql queries on the database.

    99         * @param aDatabase A handle to the database.

   100         */

   101         IMPORT_C void GetDatabase(

   102         /* OUT */   RDbNamedDatabase& aDatabase

   103         );

   104 

   105         /**

   106         * Opens a landmark database with the specified URI.

   107         * @param aUri A database URI.

   108         * @return KErrNone if successful. KErrNotFound, KErrPathNotFound,

   109         *   KErrArgument or KErrAlreadyExists if the database does not exist.

   110         */

   111         IMPORT_C TInt OpenDatabaseL(

   112         /* IN */    const TDesC& aUri

   113         );

   114 

   115         /**

   116         * Begins a transaction. Does not put a rollback on the clean-up stack.

   117         * Useful for asynchronous operations.

   118         * @return KErrNone for client side access to the database or, if this

   119         *   is a shared database and the client has successfully locked it.

   120         *   KErrLocked if this is a shared database and another client already

   121         *   has an exclusive write-lock on it. Otherwise, one of the other

   122         *   system error codes.

   123         */

   124         IMPORT_C TInt BeginTransaction();

   125 

   126         /**

   127         * Commits a transaction. Useful for asynchronous operations that cannot

   128         * put a rollback on the clean-up stack.

   129         * @return KErrNone if successful, otherwise one of the other system

   130         *   wide error codes including the DBMS database error codes.

   131         */

   132         IMPORT_C TInt CommitTransaction();

   133 

   134         /**

   135         * Rolls back the current transaction. Useful when a rollback function

   136         * cannot be placed on the clean-up stack, i.e. in asynchronous

   137         * operations.

   138         */

   139         IMPORT_C void RollbackTransaction();

   140 

   141         /*

   142         * Tests if there is an outstanding transaction on the database.

   143         * @return ETrue, if a transaction is in progress; EFalse, otherwise.

   144         */

   145         IMPORT_C TBool InTransaction() const;

   146 

   147         /*

   148         * Returns the init flag which tells whether a database must be

   149         * initialized or not.

   150         *

   151         * @return Init flag.

   152         */

   153         IMPORT_C TUint InitFlag() const;

   154 

   155         /*

   156         * Returns a pointer to the init flag which tells whether a database

   157         * must be initialized or not.

   158         *

   159         * @return Pointer to init flag.

   160         */

   161         IMPORT_C TUint* InitFlagPtr();

   162 

   163         /*

   164         * Resets the init flag which tells whether a database must be

   165         * initialized or not.

   166         */

   167         IMPORT_C void ResetInitFlag();

   168 

   169         /**

   170         * Checks if database is damaged. That is, it needs to be recovered.

   171         *

   172         * @return Returns ETrue if the database is damaged. Otherwise EFalse.

   173         */

   174         IMPORT_C TBool IsDamaged();

   175 

   176         /**

   177         * Executes an SQL query.

   178         *

   179         * @param aQuery SQL query.

   180         */

   181         IMPORT_C void ExecuteL(

   182         /* IN */        const TDesC& aQuery

   183         );

   184 

   185         /**

   186         * Prepares and evalutes a database view. The view is put on the cleanup

   187         * stack.

   188         * @param aType The type of preparation (add/read).

   189         * @param aView A database view to prepare and evaluate.

   190         * @param aSql A SQL query.

   191         * @param aComparison A comparison type.

   192         */

   193         IMPORT_C void PrepareViewLC(

   194         /* IN */        TPreparationType aType,

   195         /* IN/OUT */    RDbView& aView,

   196         /* IN */        const TDesC& aSql,

   197         /* IN */        TDbTextComparison aComparison = EDbCompareNormal

   198         );

   199 

   200         /**

   201         * Returns size information for the database.

   202         *

   203         * @returns Size information for the database.

   204         */

   205         IMPORT_C CPosLandmarkDatabase::TSize SizeL();

   206 

   207         /**

   208         * Checks whether a database needs to be initialized or not.

   209         *

   210         * @param aIsNeeded ETrue if the database needs to be initialized,

   211         *   EFalse otherwise.

   212         * @return KErrCorrupt if the settings table cannot be found.

   213         *   KErrNone otherwise.

   214         */

   215         IMPORT_C TInt IsInitializeNeededL(

   216         /* OUT */       TBool& aIsNeeded

   217         );

   218 

   219         /**

   220         * Sets a flag in the database that initialization is done.

   221         */

   222         IMPORT_C void SetInitializeDoneL();

   223 

   224         /**

   225         * Checks if the language must be changed for a landmark database.

   226         * That is if the language in the database does not match the language

   227         * of the phone.

   228         *

   229         * @param aIsNeeded ETrue if language must be changed, EFalse otherwise.

   230         * @return KErrCorrupt if the settings table cannot be found.

   231         *   KErrNone otherwise.

   232         */

   233         IMPORT_C TInt IsLanguageChangeNeededL(

   234         /* OUT */       TBool& aIsNeeded

   235         );

   236 

   237         /**

   238         * Sets the language of the database to the specified language.

   239         *

   240         * @param aLanguage A language to set.

   241         */

   242         IMPORT_C void SetLanguageL(

   243         /* IN */        TLanguage aLanguage

   244         );

   245 

   246         /**

   247         * Checks whether compact is needed or not.

   248         *

   249         * @return ETrue if compact is needed. EFalse otherwise.

   250         */

   251         IMPORT_C TBool IsCompactNeededL();

   252 

   253         /** Checks if new indexes exist in the database */

   254         IMPORT_C TBool IsIndexCreationNeededL() const;

   255         

   256     private:

   257 

   258         /**

   259         * C++ default constructor.

   260         */

   261         CPosLmLocalDbAccess(

   262         /* IN  */   TCompactLevelType aCompactLevel

   263         );

   264 

   265         /**

   266         * By default Symbian 2nd phase constructor is private.

   267         */

   268         void ConstructL();

   269 

   270         /**

   271         * Checks whether the database needs to be initialized or not.

   272         * @return KErrCorrupt if impossible to read from settings table.

   273         *   Otherwise KErrNone.

   274         */

   275         TInt VerifyDatabaseNeedInitializationL();

   276 

   277         /**

   278         * Reads the internal compact database level from a resource file.

   279         */

   280         void ReadCompactDbLevelL();

   281 

   282         /**

   283         * Either checks if initialize or a language switch is needed. A boolean

   284         * specifies which type of check to perform.

   285         *

   286         * @param aIsInitCheck ETrue if init check. EFalse if language check.

   287         * @param aIsNeeded ETrue if the change is needed. EFalse otherwise.

   288         * @return KErrCorrupt if the settings table cannot be found.

   289         *   KErrNone otherwise.

   290         */

   291         TInt PerformCheckL(

   292         /* IN */        TBool aIsInitCheck,

   293         /* OUT */       TBool& aIsNeeded

   294         );

   295 

   296         /**

   297         * Sets a flag in the database telling that either language switch or

   298         * initialization has been performed.

   299         *

   300         * @param aSetLanguage ETrue if setting language, EFalse if setting

   301         *   init flag.

   302         * @param aLanguage If setting language this will hold the actual

   303         *   language.

   304         */

   305         void SetFlagL(

   306         /* IN */        TBool aSetLanguage,

   307         /* IN */        TLanguage aLanguage

   308         );

   309         

   310         /** Checks whether given index exists on given table */

   311         TBool IndexExistsL( const TDesC& aTable, const TDesC& aIndex ) const;

   312 

   313     private:    // Data

   314 

   315         // Database session

   316         RDbs iDbSession;

   317 

   318         // Database

   319         RDbNamedDatabase iDb;

   320 

   321         // Flag used for remembering if initialization must be done.

   322         TUint iInit;

   323 

   324         // Level for internal compact.

   325         TCompactLevelType iLevelType;

   326         TReal32 iRelativeCompactLevel;

   327         TInt32 iAbsoluteCompactLevel;

   328     };

   329 

   330 #endif      // CPOSLMLOCALDBACCESS_H

   331