/*

* 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 RFavouritesDb.

*

*/

#ifndef FAVOURITES_DB_H

#define FAVOURITES_DB_H

//  INCLUDES

#include <e32base.h>

#include <d32dbms.h>

#include <favouritesitem.h>

#include <favouriteslimits.h>

#include <favouritessession.h>

#include <favouriteshandle.h>

// FORWARD DECLARATIONS

class CFavouritesItemList;

class MFavouritesItemData;

class MRfsApMapper;

// CLASS DECLARATION

/**

* RFavouritesDb is the representation of the favourites database.

* This class encapsulates a session with bookmark database server.

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

* (recovery, compaction) and explicit transaction support. 

*/

class RFavouritesDb: public RFavouritesHandle

    {

    public:     // New methods

        /**

        * Open the database. Created if does not exist.

        * @since 0.9 

        * @param aSess Session to be used.

        * @param aName Database name.

        * @return Error code.

        */

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

    public:     // Adminstration

        /**

        * Get version information.

        * @since 0.9 

        * @return Version object of this CFavouritesDb.

        */

        IMPORT_C TVersion Version() const;

        /**

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

        * @since 0.9 

        * @param aIsDamaged Result is returned here.

        * @return Error code.

        */

        IMPORT_C TInt IsDamaged( TBool& aIsDamaged );

        /**

        * Perform database synchronous recovery. This function requires exclusive access 

        * to the database.

        * @since 0.9 

        * @return Error code.

        */

        IMPORT_C TInt Recover();

        /**

        * Perform databas synchronous compaction. This function requires exclusive access 

        * to the database.

        * @since 0.9 

        * @return Error code.

        */

        IMPORT_C TInt Compact();

        /**

        * Get available database size.

        * @since 0.9 

        * @param aSize Database size returned here.

        * @return Error code.

        */

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

        /**

        * Update database statistics.

        * @since 0.9 

        * @return Error code.

        */

        IMPORT_C TInt UpdateStats();

    public:     // Transaction support

        /**

        * Explicitly begin a transaction.

        * @since 0.9 

        * @param aWrite Access mode.

        * @return Error code.

        */

        IMPORT_C TInt Begin( TBool aWrite = EFalse );

        /**

        * Commit the transaction.

        * @since 0.9 

        * @return Error code.

        */

        IMPORT_C TInt Commit();

        /**

        * Roll back the transaction.

        * @since 0.9 

        * @return void

        */

        IMPORT_C void Rollback();

        /**

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

        * to make the transaction leave-safe.

        * @since 0.9 

        * @return void

        */

        IMPORT_C void CleanupRollbackPushL();

    public:     // Data access / update / delete

        /**

        * Get the item with this Uid.

        * @since 0.9 

        * @param aUid Uid or item to get.

        * @param aItem placeholder for the returned item data.

        * @return Error code.

        */

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

        /**

        * Get all items matching the supplied criteria.

        * @since 0.9 

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

        * items remain (new ones appended).

        * @param aParentFolderFilter Uid value to filter. KFavouritesNullUid

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

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

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

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

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

        * @param aContextIdFilter ContextId value to filter.

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

        * @return Error code.

        */

        IMPORT_C TInt GetAll

            (

            CFavouritesItemList& aItemList,

            TInt aParentFolderFilter = KFavouritesNullUid,

            CFavouritesItem::TType aTypeFilter = CFavouritesItem::ENone,

            const TDesC* aNameFilter = NULL,

            TInt32 aContextIdFilter = KFavouritesNullContextId

            );

        /**

        * Get uids of all items matching the supplied criteria.

        * @since 0.9 

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

        * items remain (new ones appended).

        * @param aParentFolderFilter Uid value to filter. KFavouritesNullUid

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

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

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

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

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

        * @param aContextIdFilter ContextId value to filter.

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

        * @return Error code.

        */

        IMPORT_C TInt GetUids

            (

            CArrayFix<TInt>& aUids,

            TInt aParentFolderFilter = KFavouritesNullUid,

            CFavouritesItem::TType aTypeFilter = CFavouritesItem::ENone,

            const TDesC* aNameFilter = NULL,

            TInt32 aContextIdFilter = KFavouritesNullContextId

            );

        /**

        * Get preferred Uid for a folder.

        * @since 0.9 

        * @param aFolder Folder Uid.

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

        * @return Error code.

        */

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

        /**

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

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

        * @since 0.9 

        * @param aUid Uid of item to delete.

        * @return Error code, including:

        *   - KErrNotFound if the item is not found.

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

        */

        IMPORT_C TInt Delete( TInt aUid );

        /**

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

        * this method.

        * @since 0.9 

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

        * update the item.

        * 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.

        * @return Error code, including:

        *   - KErrNotFound if the item is not found.

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

        *     parent folder does not exist etc.).

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

        *   - KErrAccessDenied for read-only items.

        */

        IMPORT_C TInt Update

            ( CFavouritesItem& 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.

        * @since 0.9 

        * @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.

        * @return Error code, including:

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

        *     parent folder does not exist etc.).

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

        */

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

        /**

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

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

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

        * Name needs not be unique.

        * @since 0.9 

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

        * be used to update the Homepage Bookmark.

        * @return Error code, including:

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

        *     the root folder.

        */

        IMPORT_C TInt SetHomepage( CFavouritesItem& aItem );

        /**

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

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

        * If successful, its Uid is updated on return.

        * Name needs not be unique.

        * @since 0.9 

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

        * be used to update the Last Visited Item.

        * @return Error code, including:

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

        *     the root folder.

        */

        IMPORT_C TInt SetLastVisited( CFavouritesItem& aItem );

        /**

        * Set factory item flag on an item.

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

        * @since 0.9 

        * @param aUid Uid of item.

        * @param aFactoryItem Flag value to set.

        * @return Error code, including:

        *   - KErrNotFound if the item is not found.

        */

        IMPORT_C TInt SetFactoryItem( TInt aUid, TBool aFactoryItem );

        /**

        * Set read-only flag on an item.

        * @since 0.9 

        * @param aUid Uid of item.

        * @param aReadOnly Flag value to set.

        * @return Error code, including:

        *   - KErrNotFound if the item is not found.

        */

        IMPORT_C TInt SetReadOnly( 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.

        * @since 0.9 

        * @param aUid Uid of item.

        * @param aModified Last Modification Time to set.

        * @return Error code, including:

        *   - KErrNotFound if the item is not found.

        */

        IMPORT_C TInt SetModified( TInt aUid, TTime aModified );

        /**

        * Set preferred Uid for a folder.

        * @since 0.9 

        * @param aFolder Folder Uid.

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

        * @return Error code, including:

        * - KErrNotFound if aFolder is not found;

        * - KErrArgument if aFolder is not a folder.

        */

        IMPORT_C TInt SetPreferredUid( TInt aFolder, TInt aUid );

        /**

        * Check if we already have this item.

        * @since 0.9 

        * @param aUid The item Uid to be checked.

        * @param aItemExists Returned value.

        * @return Error code.

        */

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

        /**

        * Check if the folder exists.

        * @since 0.9 

        * @param aFolder The folder to be checked.

        * @param aFolderExists Returned value.

        * @return Error code.

        */

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

        /**

        * Count all items matching the supplied criteria.

        * @since 0.9 

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

        * any error, existing value is unchanged.

        * @param aParentFolderFilter Uid value to filter. KFavouritesNullUid

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

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

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

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

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

        * @param aContextIdFilter ContextId value to filter.

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

        * @return Error code.

        */

        IMPORT_C TInt Count

            (

            TInt& aCount,

            TInt aParentFolderFilter = KFavouritesNullUid,

            CFavouritesItem::TType aTypeFilter = CFavouritesItem::ENone,

            const TDesC* aNameFilter = NULL,

            TInt32 aContextIdFilter = KFavouritesNullContextId

            );

    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.

        * @since 0.9 

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

        * @param aData Data) which replaces existing data.

        * @return Error code, including:

        *   - KErrNotFound No item is found with aUid.

        */

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

        /**

        * Get data associated with an item.

        * @since 0.9 

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

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

        * @return Error code, including:

        *   - KErrNotFound No item is found with aUid.

        */

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

    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.

        * @since 0.9 

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

        * @param aData Data) which replaces existing data.

        * @return Error code, including:

        *   - KErrNotFound No item is found with aUid.

        */

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

        /**

        * Get Browser associated with an item.

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

        * @since 0.9 

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

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

        * @return Error code, including:

        *   - KErrNotFound No item is found with aUid.

        */

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

    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).

        * @since 0.9         

        * @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.

        * @return Error code, including:

        *   - KErrArgument aFolder is not found.

        *   - KErrBadName aName is empty.

        */

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

        /**

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

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

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

        * considered (can have conflicting names).

        * @since 0.9 

        * @param aItem Item to set unique name for.

        * @return Error code, including:

        *   - KErrArgument aFolder is not found.

        *   - KErrBadName Current name is empty.

        */

        IMPORT_C TInt MakeUniqueName( CFavouritesItem& aItem );

    public:     // Browser support

        /**

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

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

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

        * @since 0.9 

        * @return The created item.

        */

        IMPORT_C CFavouritesItem* CreateStartPageItemL();

        /**

        * Create a folder with uid KFavouritesAdaptiveItemsFolderUid.

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

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

        * that this item does not exist in the database.

        * @since 0.9 

        * @return The created item.

        */

        IMPORT_C CFavouritesItem* CreateAdaptiveItemsFolderL();

    public:     // Files

        /**

        * Delete file. See RFavouritesFile.

        * @since 0.9 

        * @param aUid Uid of the item.

        * @return Errro code.

        */

        IMPORT_C TInt DeleteFile( TInt aUid );

    public:     // RFS

        /**

        * 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 conflilcts, new

        * names are generated. Leaves on any error.

        * @since 0.9 

        * @param aName Database name.

        * @param aReferenceDbPath Full pathname of reference database.

        * @param aApMapper Access Point mapper to be used.

        */

        IMPORT_C static void RestoreFactorySettingsL

            (

            const TDesC& aName,

            const TDesC& aReferenceDbPath,

            MRfsApMapper& aApMapper

            );

    private:    // New methods

        /**

        * Set Homepage / Last Visited Page.

        * @since 0.9 

        * @param aItem Item data.

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

        * @return Error code.

        */

        TInt SetSpecialItem( CFavouritesItem& aItem, TInt aUid );

        /**

        * Set data associated with an item.

        * @since 0.9 

        * @param aFunction Function.

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

        * @param aData Data which replaces existing data.

        * @return Error code.

        */

        TInt SetData

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

        /**

        * Get data associated with an item.

        * @since 0.9 

        * @param aFunction Function.

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

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

        * @return Error code.

        */

        TInt GetData

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

        /**

        * Implementation of RestoreFactorySettingsL().

        * @since 0.9 

        * @param aReferenceDbPath Full pathname of reference database.

        * @param aApMapper Access Point mapper to be used.

        */

        void DoRestoreFactorySettingsL

            ( const TDesC& aReferenceDbPath, MRfsApMapper& aApMapper );

        /**

        * Cleanup helper, static wrapper around the rollback call.

        * @since 0.9 

        * @param aPtr This as TAny*.

        */

        static void StaticRollback( TAny* aPtr );

    };

#endif

// End of File