1 favouritesdb.h

     1 /*

     2 * Copyright (c) 2004 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 "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:  Declaration of RFavouritesDb.

    15 *

    16 */

    17 

    18 

    19 #ifndef FAVOURITES_DB_H

    20 #define FAVOURITES_DB_H

    21 

    22 //  INCLUDES

    23 

    24 #include <e32base.h>

    25 #include <d32dbms.h>

    26 #include <FavouritesItem.h>

    27 #include <FavouritesLimits.h>

    28 #include <FavouritesSession.h>

    29 #include <FavouritesHandle.h>

    30 

    31 // FORWARD DECLARATIONS

    32 

    33 class CFavouritesItemList;

    34 class MFavouritesItemData;

    35 class MRfsApMapper;

    36 

    37 // CLASS DECLARATION

    38 

    39 /**

    40 * RFavouritesDb is the representation of the favourites database.

    41 * This class encapsulates a session with bookmark database server.

    42 * It provides a way to access the database, do administration

    43 * (recovery, compaction) and explicit transaction support. 

    44 */

    45 class RFavouritesDb: public RFavouritesHandle

    46     {

    47 

    48     public:     // New methods

    49 

    50         /**

    51         * Open the database. Created if does not exist.

    52         * @since 0.9 

    53         * @param aSess Session to be used.

    54         * @param aName Database name.

    55         * @return Error code.

    56         */

    57         IMPORT_C TInt Open( RFavouritesSession& aSess, const TDesC& aName );

    58 

    59     public:     // Adminstration

    60         

    61         /**

    62         * Get version information.

    63         * @since 0.9 

    64         * @return Version object of this CFavouritesDb.

    65         */

    66         IMPORT_C TVersion Version() const;

    67 

    68         /**

    69         * Check if the database to be recovered is fully functional.

    70         * @since 0.9 

    71         * @param aIsDamaged Result is returned here.

    72         * @return Error code.

    73         */

    74         IMPORT_C TInt IsDamaged( TBool& aIsDamaged );

    75 

    76         /**

    77         * Perform database synchronous recovery. This function requires exclusive access 

    78         * to the database.

    79         * @since 0.9 

    80         * @return Error code.

    81         */

    82         IMPORT_C TInt Recover();

    83 

    84         /**

    85         * Perform databas synchronous compaction. This function requires exclusive access 

    86         * to the database.

    87         * @since 0.9 

    88         * @return Error code.

    89         */

    90         IMPORT_C TInt Compact();

    91 

    92         /**

    93         * Get available database size.

    94         * @since 0.9 

    95         * @param aSize Database size returned here.

    96         * @return Error code.

    97         */

    98         IMPORT_C TInt Size( RDbDatabase::TSize& aSize ) const;

    99 

   100         /**

   101         * Update database statistics.

   102         * @since 0.9 

   103         * @return Error code.

   104         */

   105         IMPORT_C TInt UpdateStats();

   106 

   107     public:     // Transaction support

   108 

   109         /**

   110         * Explicitly begin a transaction.

   111         * @since 0.9 

   112         * @param aWrite Access mode.

   113         * @return Error code.

   114         */

   115         IMPORT_C TInt Begin( TBool aWrite = EFalse );

   116 

   117         /**

   118         * Commit the transaction.

   119         * @since 0.9 

   120         * @return Error code.

   121         */

   122         IMPORT_C TInt Commit();

   123 

   124         /**

   125         * Roll back the transaction.

   126         * @since 0.9 

   127         * @return void

   128         */

   129         IMPORT_C void Rollback();

   130 

   131         /**

   132         * Push a rollback on the cleanup stack. Call this after Begin() call,

   133         * to make the transaction leave-safe.

   134         * @since 0.9 

   135         * @return void

   136         */

   137         IMPORT_C void CleanupRollbackPushL();

   138 

   139     public:     // Data access / update / delete

   140 

   141         /**

   142         * Get the item with this Uid.

   143         * @since 0.9 

   144         * @param aUid Uid or item to get.

   145         * @param aItem placeholder for the returned item data.

   146         * @return Error code.

   147         */

   148         IMPORT_C TInt Get( TInt aUid, CFavouritesItem& aItem );

   149 

   150         /**

   151         * Get all items matching the supplied criteria.

   152         * @since 0.9 

   153         * @param aItemList placeholder for the returned item data. Existing

   154         * items remain (new ones appended).

   155         * @param aParentFolderFilter Uid value to filter. KFavouritesNullUid

   156         * clears (all accepted); this is the default.

   157         * @param aTypeFilter EItem or EFolder to use filter; ENone to clear

   158         * filter (all accepted); this is the default.

   159         * @param aNameFilter wildcard pattern to be used for name matching.

   160         * NULL clears (all accepted); this is the default.

   161         * @param aContextIdFilter ContextId value to filter.

   162         * KFavouritesNullContextId clears (all accepted); this is the default.

   163         * @return Error code.

   164         */

   165         IMPORT_C TInt GetAll

   166             (

   167             CFavouritesItemList& aItemList,

   168             TInt aParentFolderFilter = KFavouritesNullUid,

   169             CFavouritesItem::TType aTypeFilter = CFavouritesItem::ENone,

   170             const TDesC* aNameFilter = NULL,

   171             TInt32 aContextIdFilter = KFavouritesNullContextId

   172             );

   173 

   174         /**

   175         * Get uids of all items matching the supplied criteria.

   176         * @since 0.9 

   177         * @param aUids placeholder for the returned item data. Existing

   178         * items remain (new ones appended).

   179         * @param aParentFolderFilter Uid value to filter. KFavouritesNullUid

   180         * clears (all accepted); this is the default.

   181         * @param aTypeFilter EItem or EFolder to use filter; ENone to clear

   182         * filter (all accepted); this is the default.

   183         * @param aNameFilter wildcard pattern to be used for name matching.

   184         * NULL clears (all accepted); this is the default.

   185         * @param aContextIdFilter ContextId value to filter.

   186         * KFavouritesNullContextId clears (all accepted); this is the default.

   187         * @return Error code.

   188         */

   189         IMPORT_C TInt GetUids

   190             (

   191             CArrayFix<TInt>& aUids,

   192             TInt aParentFolderFilter = KFavouritesNullUid,

   193             CFavouritesItem::TType aTypeFilter = CFavouritesItem::ENone,

   194             const TDesC* aNameFilter = NULL,

   195             TInt32 aContextIdFilter = KFavouritesNullContextId

   196             );

   197 

   198         /**

   199         * Get preferred Uid for a folder.

   200         * @since 0.9 

   201         * @param aFolder Folder Uid.

   202         * @param aPreferredUid Uid of preferred item is returned here.

   203         * @return Error code.

   204         */

   205         IMPORT_C TInt PreferredUid( TInt aFolder, TInt& aPreferredUid );

   206 

   207         /**

   208         * Delete item by Uid. If this is a folder, all descendants and the contents

   209         * of them are deleted. Homepage or root cannot be deleted.

   210         * @since 0.9 

   211         * @param aUid Uid of item to delete.

   212         * @return Error code, including:

   213         *   - KErrNotFound if the item is not found.

   214         *   - KErrAccessDenied if the item's cannot be deleted.

   215         */

   216         IMPORT_C TInt Delete( TInt aUid );

   217 

   218         /**

   219         * Update an item. Remember Homapage or Last Visited Page cannot be updated using

   220         * this method.

   221         * @since 0.9 

   222         * @param aItem Contents from this item (except Uid) will be used to

   223         * update the item.

   224         * If successful, its Uid, Last-Mod-Time (and possibly its name) is

   225         * updated on return.

   226         * @param aUid Update this item.

   227         * @param aAutoRename If this is ETrue, and the name already exists,

   228         * the item will be renamed to a non-conflicting name.

   229         * @return Error code, including:

   230         *   - KErrNotFound if the item is not found.

   231         *   - KErrArgument if the item's data is invalid (bad name, no URL,

   232         *     parent folder does not exist etc.).

   233         *   - KErrAlreadyExists if the name is already in use in that folder.

   234         *   - KErrAccessDenied for read-only items.

   235         */

   236         IMPORT_C TInt Update

   237             ( CFavouritesItem& aItem, TInt aUid, TBool aAutoRename );

   238 

   239         /**

   240         * Add a new item to the database.

   241         * If successful, its Uid, Last-Mod-Time (and possibly its name) is

   242         * updated on return.

   243         * @since 0.9 

   244         * @param aItem The item to add.

   245         * @param aAutoRename If this is ETrue, and the name already exists,

   246         * the item will be renamed to a non-conflicting name.

   247         * @return Error code, including:

   248         *   - KErrArgument if the item's data is invalid (bad name, no URL,

   249         *     parent folder does not exist etc.).

   250         *   - KErrAlreadyExists if the name is already in use in that folder.

   251         */

   252         IMPORT_C TInt Add( CFavouritesItem& aItem, TBool aAutoRename );

   253 

   254         /**

   255         * Update the Homepage item. If does not exist, it is now

   256         * created. The old Homepage, if any, is overwritten.

   257         * If successful, its Uid and Last-Mod-Time is updated on return.

   258         * Name needs not be unique.

   259         * @since 0.9 

   260         * @param aItem Contents from this item (except Uid) will

   261         * be used to update the Homepage Bookmark.

   262         * @return Error code, including:

   263         *   - KErrArgument if the supplied item is not item, or is not in

   264         *     the root folder.

   265         */

   266         IMPORT_C TInt SetHomepage( CFavouritesItem& aItem );

   267 

   268         /**

   269         * Update the Last Visited. If does not exist, it is now

   270         * created. The old Last Visited, if any, is overwritten.

   271         * If successful, its Uid is updated on return.

   272         * Name needs not be unique.

   273         * @since 0.9 

   274         * @param aItem Contents from this item (except Uid) will

   275         * be used to update the Last Visited Item.

   276         * @return Error code, including:

   277         *   - KErrArgument if the supplied item is not item, or is not in

   278         *     the root folder.

   279         */

   280         IMPORT_C TInt SetLastVisited( CFavouritesItem& aItem );

   281 

   282         /**

   283         * Set factory item flag on an item.

   284         * (Item with this flag set will be deleted if RFS is executed.)

   285         * @since 0.9 

   286         * @param aUid Uid of item.

   287         * @param aFactoryItem Flag value to set.

   288         * @return Error code, including:

   289         *   - KErrNotFound if the item is not found.

   290         */

   291         IMPORT_C TInt SetFactoryItem( TInt aUid, TBool aFactoryItem );

   292 

   293         /**

   294         * Set read-only flag on an item.

   295         * @since 0.9 

   296         * @param aUid Uid of item.

   297         * @param aReadOnly Flag value to set.

   298         * @return Error code, including:

   299         *   - KErrNotFound if the item is not found.

   300         */

   301         IMPORT_C TInt SetReadOnly( TInt aUid, TBool aReadOnly );

   302 

   303         /**

   304         * Manual setting of Last Modification Time of an item.

   305         * Note that the Last Modification Time is automatically set by any

   306         * edit, so this method need not be used in usual circumstances. It is

   307         * provided for administration purposes only.

   308         * @since 0.9 

   309         * @param aUid Uid of item.

   310         * @param aModified Last Modification Time to set.

   311         * @return Error code, including:

   312         *   - KErrNotFound if the item is not found.

   313         */

   314         IMPORT_C TInt SetModified( TInt aUid, TTime aModified );

   315 

   316         /**

   317         * Set preferred Uid for a folder.

   318         * @since 0.9 

   319         * @param aFolder Folder Uid.

   320         * @param aUid Uid to be set as preferred. Not checked to exist in the folder.

   321         * @return Error code, including:

   322         * - KErrNotFound if aFolder is not found;

   323         * - KErrArgument if aFolder is not a folder.

   324         */

   325         IMPORT_C TInt SetPreferredUid( TInt aFolder, TInt aUid );

   326 

   327         /**

   328         * Check if we already have this item.

   329         * @since 0.9 

   330         * @param aUid The item Uid to be checked.

   331         * @param aItemExists Returned value.

   332         * @return Error code.

   333         */

   334         IMPORT_C TInt ItemExists( TInt aUid, TBool& aItemExists );

   335 

   336         /**

   337         * Check if the folder exists.

   338         * @since 0.9 

   339         * @param aFolder The folder to be checked.

   340         * @param aFolderExists Returned value.

   341         * @return Error code.

   342         */

   343         IMPORT_C TInt FolderExists( TInt aFolder, TBool& aFolderExists );

   344 

   345         /**

   346         * Count all items matching the supplied criteria.

   347         * @since 0.9 

   348         * @param aCount Placeholder for the returned item count. In case of

   349         * any error, existing value is unchanged.

   350         * @param aParentFolderFilter Uid value to filter. KFavouritesNullUid

   351         * clears (all accepted); this is the default.

   352         * @param aTypeFilter EItem or EFolder to use filter; ENone to clear

   353         * filter (all accepted); this is the default.

   354         * @param aNameFilter Wildcard pattern to be used for name matching.

   355         * NULL clears (all accepted); this is the default.

   356         * @param aContextIdFilter ContextId value to filter.

   357         * KFavouritesNullContextId clears (all accepted); this is the default.

   358         * @return Error code.

   359         */

   360         IMPORT_C TInt Count

   361             (

   362             TInt& aCount,

   363             TInt aParentFolderFilter = KFavouritesNullUid,

   364             CFavouritesItem::TType aTypeFilter = CFavouritesItem::ENone,

   365             const TDesC* aNameFilter = NULL,

   366             TInt32 aContextIdFilter = KFavouritesNullContextId

   367             );

   368 

   369     public:     // extra data

   370 

   371         /**

   372         * Set data associated with an item. Any existing data, belonging to

   373         * item having aUid, is now replaced. The item itself is not changed.

   374         * In case of any errors, the data is not saved.

   375         * @since 0.9 

   376         * @param aUid The uid of the item, to which the data belongs.

   377         * @param aData Data) which replaces existing data.

   378         * @return Error code, including:

   379         *   - KErrNotFound No item is found with aUid.

   380         */

   381         IMPORT_C TInt SetData( TInt aUid, const MFavouritesItemData& aData );

   382 

   383         /**

   384         * Get data associated with an item.

   385         * @since 0.9 

   386         * @param aUid The uid of the item, to which the data belongs.

   387         * @param aData Data object, which receives the data.

   388         * @return Error code, including:

   389         *   - KErrNotFound No item is found with aUid.

   390         */

   391         IMPORT_C TInt GetData( TInt aUid, MFavouritesItemData& aData );

   392 

   393     public:     // Browser data

   394 

   395         /**

   396         * Set Browser data associated with an item. Any existing data,

   397         * belonging to  item having aUid, is now replaced. The item itself is

   398         * not changed.

   399         * This data is for Browser's dedicated use, do not tamper.

   400         * In case of any errors, the data is not saved.

   401         * @since 0.9 

   402         * @param aUid The uid of the item, to which the data belongs.

   403         * @param aData Data) which replaces existing data.

   404         * @return Error code, including:

   405         *   - KErrNotFound No item is found with aUid.

   406         */

   407         IMPORT_C TInt SetBrowserData( TInt aUid, const MFavouritesItemData& aData );

   408 

   409         /**

   410         * Get Browser associated with an item.

   411         * This data is for Browser's dedicated use, do not tamper.

   412         * @since 0.9 

   413         * @param aUid The uid of the item, to which the data belongs.

   414         * @param aData Data object, which receives the data.

   415         * @return Error code, including:

   416         *   - KErrNotFound No item is found with aUid.

   417         */

   418         IMPORT_C TInt GetBrowserData( TInt aUid, MFavouritesItemData& aData );

   419 

   420     public:     // unique name support

   421 

   422         /**

   423         * Check if aName is unique in aFolder; and if not, change to

   424         * an unique one, appending a number. In case of any errors, aName is

   425         * unchanged. Names of special items (Start Page etc.) are not

   426         * considered (can have conflicting names).

   427         * @since 0.9         

   428         * @param aName Descriptor containing the original name and receiving

   429         * the resulting unique name. Must be large enough to accomodate the

   430         * result. (The appended text is KFavouritesMaxPostfix characters at

   431         * most; the resulting length is KFavouritesMaxName at most.)

   432         * @param aFolder Folder to be used for uniqueness-checking.

   433         * @return Error code, including:

   434         *   - KErrArgument aFolder is not found.

   435         *   - KErrBadName aName is empty.

   436         */

   437         IMPORT_C TInt MakeUniqueName( TDes& aName, TInt aFolder );

   438 

   439         /**

   440         * Check if aName is unique in its folder; and if not, change to

   441         * an unique one, appending a number. In case of any errors, aItem is

   442         * unchanged. Names of special items (Start Page etc.) are not

   443         * considered (can have conflicting names).

   444         * @since 0.9 

   445         * @param aItem Item to set unique name for.

   446         * @return Error code, including:

   447         *   - KErrArgument aFolder is not found.

   448         *   - KErrBadName Current name is empty.

   449         */

   450         IMPORT_C TInt MakeUniqueName( CFavouritesItem& aItem );

   451 

   452     public:     // Browser support

   453 

   454         /**

   455         * Create an empty item with uid KFavouritesStartPageUid. Owner is the

   456         * caller. Except its uid, the item is uninitialized. The Browser

   457         * needs this. Note that this item does not exist in the database.

   458         * @since 0.9 

   459         * @return The created item.

   460         */

   461         IMPORT_C CFavouritesItem* CreateStartPageItemL();

   462 

   463         /**

   464         * Create a folder with uid KFavouritesAdaptiveItemsFolderUid.

   465         * Owner is the caller. Uid, type (folder) and parent (root) is set,

   466         * other properties are uninitialized. The Browser  needs this. Note

   467         * that this item does not exist in the database.

   468         * @since 0.9 

   469         * @return The created item.

   470         */

   471         IMPORT_C CFavouritesItem* CreateAdaptiveItemsFolderL();

   472 

   473     public:     // Files

   474 

   475         /**

   476         * Delete file. See RFavouritesFile.

   477         * @since 0.9 

   478         * @param aUid Uid of the item.

   479         * @return Errro code.

   480         */

   481         IMPORT_C TInt DeleteFile( TInt aUid );

   482 

   483     public:     // RFS

   484 

   485         /**

   486         * User-level Restore Factory Settings operation.

   487         * Delete all items that has "factory item" flag set, then add new

   488         * ones from reference database. In case of name conflilcts, new

   489         * names are generated. Leaves on any error.

   490         * @since 0.9 

   491         * @param aName Database name.

   492         * @param aReferenceDbPath Full pathname of reference database.

   493         * @param aApMapper Access Point mapper to be used.

   494         */

   495         IMPORT_C static void RestoreFactorySettingsL

   496             (

   497             const TDesC& aName,

   498             const TDesC& aReferenceDbPath,

   499             MRfsApMapper& aApMapper

   500             );

   501 

   502     private:    // New methods

   503 

   504         /**

   505         * Set Homepage / Last Visited Page.

   506         * @since 0.9 

   507         * @param aItem Item data.

   508         * @param aUid Uid of the item to be set.

   509         * @return Error code.

   510         */

   511         TInt SetSpecialItem( CFavouritesItem& aItem, TInt aUid );

   512 

   513         /**

   514         * Set data associated with an item.

   515         * @since 0.9 

   516         * @param aFunction Function.

   517         * @param aUid The uid of the item, to which the data belongs.

   518         * @param aData Data which replaces existing data.

   519         * @return Error code.

   520         */

   521         TInt SetData

   522             ( TInt aFunction, TInt aUid, const MFavouritesItemData& aData );

   523 

   524         /**

   525         * Get data associated with an item.

   526         * @since 0.9 

   527         * @param aFunction Function.

   528         * @param aUid The uid of the item, to which the data belongs.

   529         * @param aData Data object, which receives the data.

   530         * @return Error code.

   531         */

   532         TInt GetData

   533             ( TInt aFunction, TInt aUid, MFavouritesItemData& aData );

   534 

   535         /**

   536         * Implementation of RestoreFactorySettingsL().

   537         * @since 0.9 

   538         * @param aReferenceDbPath Full pathname of reference database.

   539         * @param aApMapper Access Point mapper to be used.

   540         */

   541         void DoRestoreFactorySettingsL

   542             ( const TDesC& aReferenceDbPath, MRfsApMapper& aApMapper );

   543 

   544         /**

   545         * Cleanup helper, static wrapper around the rollback call.

   546         * @since 0.9 

   547         * @param aPtr This as TAny*.

   548         */

   549         static void StaticRollback( TAny* aPtr );

   550 

   551     };

   552 

   553 #endif

   554             

   555 // End of File