/*
* 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
#warning The Favorites API will be removed wk25. Please see http://wikis.in.nokia.com/Browser/APIMigration for more information
// 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