/*

* Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*      Declaration of class CFavouritesSrvDb.

*      

*

*/

#ifndef FAVOURITES_SRV_DB_H

#define FAVOURITES_SRV_DB_H

//  INCLUDES

#include <e32base.h>

#include <d32dbms.h>

#include <f32file.h>

#include "FavouritesSrvTable.h"

#include "UnicodeFile.h"

// FORWARD DECLARATIONS

class CFavouritesItemImpl;

class CFavouritesItemImplList;

class MFavouritesItemData;

class TFavouritesFilter;

class MStreamBuf;

class CUidMap;

class CFavouritesFolder;

// CLASS DECLARATION

/**

* Server side favourites database.

*/

NONSHARABLE_CLASS(CFavouritesSrvDb): public CBase

    {

    public:     // Constructors and destructor

        /**

        * Two-phased constructor. Leaves on failure.

        * @param aFs File server session handle.

        * @param aDbs DBMS session handle.

        * @param aPath Database path.

        * @param aDBName Database name.        

        * @return The constructed db.

        */

        static CFavouritesSrvDb* NewL

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

        /**

        * Destructor.

        */

        virtual ~CFavouritesSrvDb();

    public:     // Adminstration

        /**

        * Check if the database has to be recovered to be

        * fully functional.

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

        */

        TBool IsDamagedL();

        /**

        * Perform synchronous recovery. Requires exclusive access

        * to the database.

        */

        void RecoverL();

        /**

        * Perform synchronous compaction. Requires exclusive access

        * to the database.

        */

        void CompactL();

        /**

        * Get available database size.

        * @return Database size.

        */

        RDbDatabase::TSize Size() const;

        /**

        * Update database statistics.

        */

        void UpdateStatsL();

        /**

        * Check transaction.

        */

        inline TBool InTransaction();

    public:     // Transaction support

        /**

        * Explicitly begin a transaction.

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

        */

        void BeginL( TBool aWrite = EFalse );

        /**

        * Commit the transaction.

        */

        void CommitL();

        /**

        * Roll back the transaction.

        */

        void Rollback();

    public:     // Data access / update / delete

        /**

        * Get the item having this Uid.

        * @param aUid Uid or item to get.

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

        * what is returned by CreateItemL().

        */

        void GetL( TInt aUid, CFavouritesItemImpl& aItem );

        /**

        * Get all items matching the supplied criteria.

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

        * items remain (new ones appended).

        * @param aFilter Filters.

        */

        void GetAllL

            (

            CFavouritesItemImplList& aItemList,

            const TFavouritesFilter& aFilter

            );

        /**

        * Get uids of all items matching the supplied criteria.

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

        * items remain (new ones appended).

        * @param aFilter Filters.

        * @return Error code.

        */

        void GetUidsL

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

        /**

        * Get preferred Uid for a folder.

        * @param aFolder Folder Uid.

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

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

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

        */

        TInt PreferredUidL( TInt aFolder );

        /**

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

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

        * @param aUid Uid of item to delete.

        */

        void DeleteL( TInt aUid );

        /**

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

        * this method.

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

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

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

        * updated on return.

        * @param aUid Update this item.

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

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

        */

        void UpdateL

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

        /**

        * Add a new item to the database.

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

        * updated on return.

        * @param aItem The item to add.

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

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

        */

        void AddL( CFavouritesItemImpl& aItem, TBool aAutoRename );

        /**

        * Set Homepage / Last Visited Page.

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

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

        * added / updated row.

        * @param aItem Item data.

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

        * KFavouritesHomepageUid or KFavouritesLastVisitedUid.

        */

        void SetSpecialItemL( CFavouritesItemImpl& aItem, TInt aUid );

        /**

        * Set factory item flag on an item.

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

        * @param aUid Uid of item.

        * @param aFactoryItem Flag value to set.

        */

        void SetFactoryItemL( TInt aUid, TBool aFactoryItem );

        /**

        * Set read-only flag on an item.

        * @param aUid Uid of item.

        * @param aReadOnly Flag value to set.

        */

        void SetReadOnlyL( TInt aUid, TBool aReadOnly );

        /**

        * Manual setting of Last Modification Time of an item.

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

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

        * provided for administration purposes only.

        * @param aUid Uid of item.

        * @param aModified Last Modification Time to set.

        */

        void SetModifiedL( TInt aUid, TTime aModified );

        /**

        * Set preferred Uid for a folder.

        * @param aFolder Folder Uid.

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

        * folder.

        */

        void SetPreferredUidL( TInt aFolder, TInt aUid );

        /**

        * Check if we have this item.

        * @param aUid The item to check.

        * @return

        *   - ETrue if we have this item;

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

        */

        TBool ItemExistsL( TInt aUid );

        /**

        * Check if we have this folder.

        * @param aFolder The folder to check.

        * @return

        *   - ETrue if we have this folder;

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

        */

        TBool FolderExistsL( TInt aFolder );

        /**

        * Count all items matching the supplied criteria.

        * @param aFilter Filters.

        * @return Item count.

        */

        TInt CountL( const TFavouritesFilter& aFilter );

    public:     // extra data

        /**

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

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

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

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

        * @param aSource Data source.

        */

        void SetDataL( TInt aUid, MStreamBuf& aSource );

        /**

        * Get data associated with an item.

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

        * @param aSink Data sink.

        */

        void GetDataL( TInt aUid, MStreamBuf& aSink );

    public:     // Browser data

        /**

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

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

        * not changed.

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

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

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

        * @param aSource Data source.

        */

        void SetBrowserDataL( TInt aUid, MStreamBuf& aSource );

        /**

        * Get Browser associated with an item.

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

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

        * @param aSink Data sink.

        */

        void GetBrowserDataL( TInt aUid, MStreamBuf& aSink );

    public:     // unique name support

        /**

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

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

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

        * considered (can have conflicting names).

        * @param aName Descriptor containing the original name and receiving

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

        * result. (The appended text is KFavouritesMaxPostfix characters at

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

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

        */

        void MakeUniqueNameL( TDes& aName, TInt aFolder );

    public:     // new methods

        /**

        * User-level Restore Factory Settings operation.

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

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

        * names are generated. Leaves on any error.

        * @param aReferenceDbPath Full pathname of reference database.

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

        * is to be called.

        * Expects a transaction.

        */

        void RestoreFactorySettingsL

            ( const TDesC& aReferenceDbPath, CUidMap& aApMap );

        /**

        * Get filename for uid.

        * @param aUid Uid.

        * @param aParse Filename is returned here.

        */

        void InitSavedFilePathL(const TDesC&  aDBName );    

        void FilenameL( TInt aUid, TParse& aParse );

    protected:      // Constructors

        /**

        * Constructor.

        * @param aFs File server session handle.

        * @param aDbs DBMS session handle.

        */

        CFavouritesSrvDb( RFs& aFs, RDbs& aDbs );

        /**

        * Second-phase constructor.

        * @param aPath Database path.

        * @param aDBName Database name.

        */

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

    protected:  // types

        /**

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

        */

        enum TRenameType

            {

            EDontRename,    ///< Reject update.

            EAutoRename,    ///< Rename automatically.

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

            };

    protected:  // custom cleanup

        /**

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

        * but do not have an item associated to them.

        */

        void DeleteOrphanedFilesL();

    protected:  // new methods

        /**

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

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

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

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

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

        */

        void BeginIfNeededL( TBool aWrite, TBool& aOwnTransaction );

        /**

        * Commit the transaction if aOwnTransaction is ETrue.

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

        * @return Error code.

        */

        void CommitIfNeededL( TBool aOwnTransaction );

    private:    // new methods

        /**

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

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

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

        * @param aDbFile Parsed filename to use.

        */

        void CreateDatabaseL( TParse& aDbFile, TBool aDoImport );

        /**

        * Create the root entry. Expects the database to be

        * open and not used by anyone else.

        */

        void CreateRootFolderL();

        /**

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

        * @return Reference to the used database.

        */

        inline RDbDatabase& Database();

        /**

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

        * also.

        * Expects a transaction; expects a valid row.

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

        * list.

        */

        void DeleteCurrentL( CArrayFix<TInt>& aDeletedUids );

        /**

        * Update the item under the cursor.

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

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

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

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

        * updated on return.

        * The cursor is left on the updated row.

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

        */

        void UpdateCurrentL

            ( CFavouritesItemImpl& aItem, TRenameType aRenameType );

        /**

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

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

        * updated on return.

        * The cursor is left on the added row.

        * @param aItem The item to add.

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

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

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

        */

        void DoAddL

            (

            CFavouritesItemImpl& aItem,

            TRenameType aRenameType,

            TBool aFactoryItem = EFalse,

            TBool aReadOnly = EFalse

            );

        /**

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

        * database) is unique name in aFolder.

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

        * Overwrites filters.

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

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

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

        * the existing item's own uid).

        * @return ETrue if aName is unique.

        */

        TBool IsUniqueNameL

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

        /**

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

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

        * aAcceptUid). Overwrites filters.

        * @param aName Descriptor containing the original name and receiving

        * the resulting unique name.

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

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

        * updating aAcceptUid).

        */

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

        /**

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

        * Expects a transaction. Expects the name be really conflicting

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

        * @param aName Descriptor containing the original name.

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

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

        * updating aAcceptUid).

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

        * must free this.

        */

        HBufC* AllocUniqueNameLC

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

        /**

        * Static wrapper arounf Rollback().

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

        */

        static void StaticRollback( TAny* aDb );

    protected:  // RFS support

        /**

        * User-level Restore Factory Settings operation.

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

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

        * names are generated. Leaves on any error.

        * @param aRefTable Reference data table.

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

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

        * SetAccessPointsL is to be called to update.

        * Expects a transaction.

        */

        void RestoreFactorySettingsL

            ( RFavouritesSrvTable& aReferenceTable, CUidMap& aApMap );

    public:     // RFS support