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: 

    15 *      Declaration of class CFavouritesSrvDb.

    16 *      

    17 *

    18 */

    19 

    20 

    21 #ifndef FAVOURITES_SRV_DB_H

    22 #define FAVOURITES_SRV_DB_H

    23 

    24 //  INCLUDES

    25 

    26 #include <e32base.h>

    27 #include <d32dbms.h>

    28 #include <f32file.h>

    29 #include <FavouritesLimits.h>

    30 #include "FavouritesSrvTable.h"

    31 #include "UnicodeFile.h"

    32 #include <FavouritesDb.h>

    33 

    34 

    35 // FORWARD DECLARATIONS

    36 

    37 class CFavouritesItemImpl;

    38 class CFavouritesItemImplList;

    39 class MFavouritesItemData;

    40 class TFavouritesFilter;

    41 class MStreamBuf;

    42 class CUidMap;

    43 class CFavouritesFolder;

    44 

    45 // CLASS DECLARATION

    46 

    47 /**

    48 * Server side favourites database.

    49 */

    50 NONSHARABLE_CLASS(CFavouritesSrvDb): public CBase

    51     {

    52 

    53     public:     // Constructors and destructor

    54     

    55         /**

    56         * Two-phased constructor. Leaves on failure.

    57         * @param aFs File server session handle.

    58         * @param aDbs DBMS session handle.

    59         * @param aPath Database path.

    60         * @param aDBName Database name.        

    61         * @return The constructed db.

    62         */

    63         static CFavouritesSrvDb* NewL

    64             ( RFs& aFs, RDbs& aDbs, const TDesC& aPath, const TDesC& aDBName );

    65 

    66         /**

    67         * Destructor.

    68         */

    69         virtual ~CFavouritesSrvDb();

    70 

    71     public:     // Adminstration

    72         

    73         /**

    74         * Check if the database has to be recovered to be

    75         * fully functional.

    76         * @return ETrue if recovery is needed; EFalse otherwise.

    77         */

    78         TBool IsDamagedL();

    79 

    80         /**

    81         * Perform synchronous recovery. Requires exclusive access

    82         * to the database.

    83         */

    84         void RecoverL();

    85 

    86         /**

    87         * Perform synchronous compaction. Requires exclusive access

    88         * to the database.

    89         */

    90         void CompactL();

    91 

    92         /**

    93         * Get available database size.

    94         * @return Database size.

    95         */

    96         RDbDatabase::TSize Size() const;

    97 

    98         /**

    99         * Update database statistics.

   100         */

   101         void UpdateStatsL();

   102 

   103         /**

   104         * Check transaction.

   105         */

   106         inline TBool InTransaction();

   107     

   108     public:     // Transaction support

   109 

   110         /**

   111         * Explicitly begin a transaction.

   112         * @param aWrite If ETrue, write-lock is placed immediately.

   113         */

   114         void BeginL( TBool aWrite = EFalse );

   115 

   116         /**

   117         * Commit the transaction.

   118         */

   119         void CommitL();

   120 

   121         /**

   122         * Roll back the transaction.

   123         */

   124         void Rollback();

   125 

   126     public:     // Data access / update / delete

   127 

   128         /**

   129         * Get the item having this Uid.

   130         * @param aUid Uid or item to get.

   131         * @param aItem placeholder for the returned item data. Must be of type

   132         * what is returned by CreateItemL().

   133         */

   134         void GetL( TInt aUid, CFavouritesItemImpl& aItem );

   135 

   136         /**

   137         * Get all items matching the supplied criteria.

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

   139         * items remain (new ones appended).

   140         * @param aFilter Filters.

   141         */

   142         void GetAllL

   143             (

   144             CFavouritesItemImplList& aItemList,

   145             const TFavouritesFilter& aFilter

   146             );

   147 

   148         /**

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

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

   151         * items remain (new ones appended).

   152         * @param aFilter Filters.

   153         * @return Error code.

   154         */

   155         void GetUidsL

   156             ( CArrayFix<TInt>& aUids, const TFavouritesFilter& aFilter );

   157 

   158         /**

   159         * Get preferred Uid for a folder.

   160         * @param aFolder Folder Uid.

   161         * @return - Uid of preferred item in folder aFolder, or

   162         *         - KFavouritesNullUid if no preferred item or in case of any

   163         *           errors (aFolder does not exist, is not a folder etc.).

   164         */

   165         TInt PreferredUidL( TInt aFolder );

   166 

   167         /**

   168         * Delete item. If this is a folder, all descendants and the contents

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

   170         * @param aUid Uid of item to delete.

   171         */

   172         void DeleteL( TInt aUid );

   173 

   174         /**

   175         * Update item. Homapage or Last Visited Page cannot be updated using

   176         * this method.

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

   178         * update the item. Must be of type what is returned by CreateItemL().

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

   180         * updated on return.

   181         * @param aUid Update this item.

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

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

   184         */

   185         void UpdateL

   186             ( CFavouritesItemImpl& aItem, TInt aUid, TBool aAutoRename );

   187 

   188         /**

   189         * Add a new item to the database.

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

   191         * updated on return.

   192         * @param aItem The item to add.

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

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

   195         */

   196         void AddL( CFavouritesItemImpl& aItem, TBool aAutoRename );

   197 

   198         /**

   199         * Set Homepage / Last Visited Page.

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

   201         * Name needs not be unique. The cursor is left on the

   202         * added / updated row.

   203         * @param aItem Item data.

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

   205         * KFavouritesHomepageUid or KFavouritesLastVisitedUid.

   206         */

   207         void SetSpecialItemL( CFavouritesItemImpl& aItem, TInt aUid );

   208 

   209         /**

   210         * Set factory item flag on an item.

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

   212         * @param aUid Uid of item.

   213         * @param aFactoryItem Flag value to set.

   214         */

   215         void SetFactoryItemL( TInt aUid, TBool aFactoryItem );

   216 

   217         /**

   218         * Set read-only flag on an item.

   219         * @param aUid Uid of item.

   220         * @param aReadOnly Flag value to set.

   221         */

   222         void SetReadOnlyL( TInt aUid, TBool aReadOnly );

   223 

   224         /**

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

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

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

   228         * provided for administration purposes only.

   229         * @param aUid Uid of item.

   230         * @param aModified Last Modification Time to set.

   231         */

   232         void SetModifiedL( TInt aUid, TTime aModified );

   233 

   234         /**

   235         * Set preferred Uid for a folder.

   236         * @param aFolder Folder Uid.

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

   238         * folder.

   239         */

   240         void SetPreferredUidL( TInt aFolder, TInt aUid );

   241 

   242         /**

   243         * Check if we have this item.

   244         * @param aUid The item to check.

   245         * @return

   246         *   - ETrue if we have this item;

   247         *   - EFalse if no such uid, or in case of any error.

   248         */

   249         TBool ItemExistsL( TInt aUid );

   250 

   251         /**

   252         * Check if we have this folder.

   253         * @param aFolder The folder to check.

   254         * @return

   255         *   - ETrue if we have this folder;

   256         *   - EFalse if no such uid; not a folder; or in case of any error.

   257         */

   258         TBool FolderExistsL( TInt aFolder );

   259 

   260         /**

   261         * Count all items matching the supplied criteria.

   262         * @param aFilter Filters.

   263         * @return Item count.

   264         */

   265         TInt CountL( const TFavouritesFilter& aFilter );

   266 

   267     public:     // extra data

   268 

   269         /**

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

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

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

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

   274         * @param aSource Data source.

   275         */

   276         void SetDataL( TInt aUid, MStreamBuf& aSource );

   277 

   278         /**

   279         * Get data associated with an item.

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

   281         * @param aSink Data sink.

   282         */

   283         void GetDataL( TInt aUid, MStreamBuf& aSink );

   284 

   285     public:     // Browser data

   286 

   287         /**

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

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

   290         * not changed.

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

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

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

   294         * @param aSource Data source.

   295         */

   296         void SetBrowserDataL( TInt aUid, MStreamBuf& aSource );

   297 

   298         /**

   299         * Get Browser associated with an item.

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

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

   302         * @param aSink Data sink.

   303         */

   304         void GetBrowserDataL( TInt aUid, MStreamBuf& aSink );

   305 

   306     public:     // unique name support

   307 

   308         /**

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

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

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

   312         * considered (can have conflicting names).

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

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

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

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

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

   318         */

   319         void MakeUniqueNameL( TDes& aName, TInt aFolder );

   320 

   321     public:     // new methods

   322 

   323         /**

   324         * User-level Restore Factory Settings operation.

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

   326         * ones from reference database. In case of name conflicts, new

   327         * names are generated. Leaves on any error.

   328         * @param aReferenceDbPath Full pathname of reference database.

   329         * @param aApMap AP map. After AP mapping is done, SetAccessPointsL

   330         * is to be called.

   331         * Expects a transaction.

   332         */

   333         void RestoreFactorySettingsL

   334             ( const TDesC& aReferenceDbPath, CUidMap& aApMap );

   335 

   336         /**

   337         * Get filename for uid.

   338         * @param aUid Uid.

   339         * @param aParse Filename is returned here.

   340         */

   341 

   342         void InitSavedFilePathL(const TDesC&  aDBName );    

   343         

   344         

   345 

   346         void FilenameL( TInt aUid, TParse& aParse );

   347       

   348     protected:      // Constructors

   349 

   350         /**

   351         * Constructor.

   352         * @param aFs File server session handle.

   353         * @param aDbs DBMS session handle.

   354         */

   355         CFavouritesSrvDb( RFs& aFs, RDbs& aDbs );

   356 

   357 

   358         /**

   359         * Second-phase constructor.

   360         * @param aPath Database path.

   361         * @param aDBName Database name.

   362         */

   363         void ConstructL( const TDesC& aPath, const TDesC&  aDBName  );

   364 

   365 

   366     protected:  // types

   367 

   368         /**

   369         * What to do with conflicting names in Add or Update operations.

   370         */

   371         enum TRenameType

   372             {

   373             EDontRename,    ///< Reject update.

   374             EAutoRename,    ///< Rename automatically.

   375             ESuppressCheck  ///< Suppress name conflict checking (accept any).

   376             };

   377 

   378     protected:  // custom cleanup

   379 

   380         /**

   381         * Orphaned files cleanup: delete files that has the proper format name

   382         * but do not have an item associated to them.

   383         */

   384         void DeleteOrphanedFilesL();

   385 

   386     protected:  // new methods

   387 

   388         /**

   389         * BeginL an explicit transaction if there is none in progress.

   390         * @param aWrite If ETrue, write-lock is placed immediately.

   391         * @param aOwnTransaction Placeholder for result. If the value is

   392         * ETrue on return, a transaction was started. To be used as the

   393         * input parameter for the corresponding CommitIfNeeded(...) call.

   394         */

   395         void BeginIfNeededL( TBool aWrite, TBool& aOwnTransaction );

   396 

   397         /**

   398         * Commit the transaction if aOwnTransaction is ETrue.

   399         * @param aOwnTransaction If ETrue, Commit will be performed.

   400         * @return Error code.

   401         */

   402         void CommitIfNeededL( TBool aOwnTransaction );

   403 

   404     private:    // new methods

   405 

   406         /**

   407         * Create the database file, make the database, and the root

   408         * folder. If anything goes wrong during this, leave. This method

   409         * expects everything to exist and be open/ready for use.

   410         * @param aDbFile Parsed filename to use.

   411         */

   412         void CreateDatabaseL( TParse& aDbFile, TBool aDoImport );

   413 

   414         /**

   415         * Create the root entry. Expects the database to be

   416         * open and not used by anyone else.

   417         */

   418         void CreateRootFolderL();

   419 

   420         /**

   421         * Get the used database. Friend classes use this method.

   422         * @return Reference to the used database.

   423         */

   424         inline RDbDatabase& Database();

   425 

   426         /**

   427         * Delete the item under the cursor. If it is a folder, delete contents

   428         * also.

   429         * Expects a transaction; expects a valid row.

   430         * @param aDeletedUids Uids of deleted items will be appended to this

   431         * list.

   432         */

   433         void DeleteCurrentL( CArrayFix<TInt>& aDeletedUids );

   434 

   435         /**

   436         * Update the item under the cursor.

   437         * Expects a transaction; expects a valid row. Row data not gotten.

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

   439         * update the item. Must be of type what is returned by CreateItemL().

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

   441         * updated on return.

   442         * The cursor is left on the updated row.

   443         * @param aRenameType What to do in case of name conflict.

   444         */

   445         void UpdateCurrentL

   446             ( CFavouritesItemImpl& aItem, TRenameType aRenameType );

   447 

   448         /**

   449         * Add a new item to the database. Expects a transaction.

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

   451         * updated on return.

   452         * The cursor is left on the added row.

   453         * @param aItem The item to add.

   454         * @param aRenameType What to do in case of name conflict.

   455         * @param aFactoryItem If ETrue, "Factory item" flag will be set.

   456         * @param aReadOnly If ETrue, "Read-only" flag will be set.

   457         */

   458         void DoAddL

   459             (

   460             CFavouritesItemImpl& aItem,

   461             TRenameType aRenameType,

   462             TBool aFactoryItem = EFalse,

   463             TBool aReadOnly = EFalse

   464             );

   465 

   466         /**

   467         * Check that aName (which has not yet been added/modified in the

   468         * database) is unique name in aFolder.

   469         * No sanity check. Expects the folder to exist. Expects a transaction.

   470         * Overwrites filters.

   471         * @param aName Name to check. Must be OK.

   472         * @param aFolder Folder to check in. Must exist.

   473         * @param aAcceptUid This uid is accepted (in case of update, this is

   474         * the existing item's own uid).

   475         * @return ETrue if aName is unique.

   476         */

   477         TBool IsUniqueNameL

   478             ( const TDesC& aName, TInt aFolder, TInt aAcceptUid );

   479 

   480         /**

   481         * Make a unique name. No sanity checks. Expects a transaction.

   482         * Expects the name be really conflicting (with some item other than

   483         * aAcceptUid). Overwrites filters.

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

   485         * the resulting unique name.

   486         * @param aFolder Folder to be used for uniqueness-checking. Must exist.

   487         * @param aAcceptUid Exclude this item from checking (used when

   488         * updating aAcceptUid).

   489         */

   490         void MakeUniqueNameL( TDes& aName, TInt aFolder, TInt aAcceptUid );

   491 

   492         /**

   493         * Allocate a buffer and make a unique name in it. No sanity checks.

   494         * Expects a transaction. Expects the name be really conflicting

   495         * (with some item other than aAcceptUid). Overwrites filters.

   496         * @param aName Descriptor containing the original name.

   497         * @param aFolder Folder to be used for uniqueness-checking. Must exist.

   498         * @param aAcceptUid Exclude this item from checking (used when

   499         * updating aAcceptUid).

   500         * @return A newly allocated buffer, containing the new name. Caller

   501         * must free this.

   502         */

   503         HBufC* AllocUniqueNameLC

   504             ( const TDesC& aName, TInt aFolder, TInt aAcceptUid );

   505 

   506         /**

   507         * Static wrapper arounf Rollback().

   508         * @param aDb The database (CFavouritesDb*) as TAny*.

   509         */

   510         static void StaticRollback( TAny* aDb );

   511 

   512     protected:  // RFS support

   513 

   514         /**

   515         * User-level Restore Factory Settings operation.

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

   517         * ones from reference database. In case of name conflicts, new

   518         * names are generated. Leaves on any error.

   519         * @param aRefTable Reference data table.

   520         * @param aApMap AP map. Filled with AP data: iUid1 = UID of item;

   521         * iUid2 = current AP id. These AP-s are to be mapped, then

   522         * SetAccessPointsL is to be called to update.

   523         * Expects a transaction.

   524         */

   525         void RestoreFactorySettingsL

   526             ( RFavouritesSrvTable& aReferenceTable, CUidMap& aApMap );

   527 

   528     public:     // RFS support

   529 

   530         /**

   531         * "Batch" setting of Access points - RFS part 2.

   532         * @param aApMap Access Point map: iUid1 = UID of item; iUid2 = AP id.

   533         * Expects a transaction.

   534         */

   535         void SetAccessPointsL( const CUidMap& aApMap );

   536 

   537     private:    // friends

   538         

   539         /// Access to iDbs is granted for this.

   540         friend class CFavouritesSrvDbNotifier;

   541         /// Access to iDbs is granted for this.

   542         friend class CFavouritesSrvDbIncremental;

   543 

   544     private:        // Data

   545 

   546         RFs& iFs;                       ///< File server sess. handle. Not own.

   547         RDbs& iDbs;                     ///< DBMS session handle. Not own.

   548         RDbNamedDatabase iDatabase;     ///< Database handle. Own.

   549         RFavouritesSrvTable iTable;     ///< Database table handle. Own.

   550         TBool iOpen;                    ///< ETrue if opened.

   551         TBool iInTransaction;           ///< ETrue in transaction.

   552         TInt iUpdatesSinceLastCompact;  ///< Updates since last compaction.

   553         HBufC* iPath;                   ///< Database path. Own.

   554         HBufC* iSavedFilePath;                   ///< Saved File  path. Own.        

   555         RBuf iSecureDbFormat;

   556 // -----------------------------------------

   557 // New methods from Bookmarks import utility

   558 // -----------------------------------------

   559     public:     // New methods

   560 

   561         /**

   562         * Import bookmarks from Unicode file (comma-separated list).

   563         * @param aFileName File Name.

   564         */

   565         void ImportL( const TDesC& aFileName );

   566 

   567     private:    

   568 

   569         /**

   570         * Get next character and store it in iCurCh.

   571         */

   572         inline void GetCharL();

   573 

   574         /**

   575         * Process next line.

   576         * @return ETrue if more lines to go, EFalse on EOF.

   577         */

   578         TBool NextLineL();

   579 

   580         /**

   581         * Parse next token. Next token spans from current character up to (but

   582         * excluding) to the next stop character.

   583         * @param aStopCharSet Stop characters (terminate the token).

   584         * @return Pointer to token. This may be empty string. Note that the

   585         * returned pointer is valid until next call (consecutive calls reuse

   586         * the same buffer).

   587         */

   588         TPtrC NextTokenL( const TDesC& aStopCharSet );

   589 

   590         /**

   591         * Parse next token, which expected to be an integer.

   592         * @param aStopCharSet Stop characters (terminate the token).

   593         * @return Numeric value of token (0 for empty token).

   594         */

   595         TInt NextIntTokenL( const TDesC& aStopCharSet );

   596 

   597         /**

   598         * Parse next token, which expected to be a hexadecimal number.

   599         * @param aStopCharSet Stop characters (terminate the token).

   600         * @return Numeric value of token (0 for empty token).

   601         */

   602         TInt32 NextHexTokenL( const TDesC& aStopCharSet );

   603 

   604         /**

   605         * @param aStopCharSet Stop characters (terminate the token).

   606         */

   607         void SkipL( const TDesC& aStopCharSet );

   608 

   609         /**

   610         * Parse comma separated list of bookmark values; create and add a

   611         * bookmark to the bookmark database.

   612         */

   613         void AttrsL();

   614 

   615         /**

   616         * Lookup uid of folder by name.

   617         * @param aName Name of folder to be found.

   618         * @return Uid of folder with name aName.

   619         */

   620         TInt FolderByNameL( const TDesC& aName );

   621         

   622         /**

   623          * Lookup IAP id by name.

   624          * @param aName Name of IAP

   625          * @aIapId contain return value of IAP id

   626          * @return error status.

   627          */ 

   628         TInt IAPIdByNameL( TDesC& aName, TInt& aIapId );

   629 

   630     private:    // data added with integration of bookmark import capability

   631 

   632         RFavouritesSession iSess;   ///< Favourites Engine session.

   633         RFavouritesDb iDb;          ///< Favourites database. Owned.

   634         CArrayFixFlat<CFavouritesFolder>*  iFolderNames; // pointer to struct of array of folder name and UID

   635 

   636         RUnicodeFile iFile;         ///< Input file. Owned.

   637         TUint iCurCh;               ///< Current (lookahead) character.

   638         TText16* iBuf;              ///< Token buffer.

   639         TText16* iNextCh;           ///< Next character is stored here.

   640         TText16* iMaxCh;            ///< Points past the buffer.

   641     };

   642 

   643 #include "FavouritesSrvDb.inl"

   644 

   645 #endif

   646             

   647 // End of File