RFavouritesDb Class Reference

API published in: S60 1st Ed

Link against: favouritesengine.lib

Capability Information

Required Capabilities

ReadUserData WriteUserData

#include <favouritesdb.h>

Inherits RFavouritesHandle.

Detailed Description

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.


Public Member Functions
IMPORT_C TInt	Open (RFavouritesSession &aSess, const TDesC &aName)
	Open the database.
IMPORT_C TVersion	Version () const
	Get version information.
IMPORT_C TInt	IsDamaged (TBool &aIsDamaged)
	Check if the database to be recovered is fully functional.
IMPORT_C TInt	Recover ()
	Perform database synchronous recovery.
IMPORT_C TInt	Compact ()
	Perform databas synchronous compaction.
IMPORT_C TInt	Size (RDbDatabase::TSize &aSize) const
	Get available database size.
IMPORT_C TInt	UpdateStats ()
	Update database statistics.
IMPORT_C TInt	Begin (TBool aWrite=EFalse)
	Explicitly begin a transaction.
IMPORT_C TInt	Commit ()
	Commit the transaction.
IMPORT_C void	Rollback ()
	Roll back the transaction.
IMPORT_C void	CleanupRollbackPushL ()
	Push a rollback on the cleanup stack.
IMPORT_C TInt	Get (TInt aUid, CFavouritesItem &aItem)
	Get the item with this Uid.
IMPORT_C TInt	GetAll (CFavouritesItemList &aItemList, TInt aParentFolderFilter=KFavouritesNullUid, CFavouritesItem::TType aTypeFilter=CFavouritesItem::ENone, const TDesC *aNameFilter=NULL, TInt32 aContextIdFilter=KFavouritesNullContextId)
	Get all items matching the supplied criteria.
IMPORT_C TInt	GetUids (CArrayFix< TInt > &aUids, TInt aParentFolderFilter=KFavouritesNullUid, CFavouritesItem::TType aTypeFilter=CFavouritesItem::ENone, const TDesC *aNameFilter=NULL, TInt32 aContextIdFilter=KFavouritesNullContextId)
	Get uids of all items matching the supplied criteria.
IMPORT_C TInt	PreferredUid (TInt aFolder, TInt &aPreferredUid)
	Get preferred Uid for a folder.
IMPORT_C TInt	Delete (TInt aUid)
	Delete item by Uid.
IMPORT_C TInt	Update (CFavouritesItem &aItem, TInt aUid, TBool aAutoRename)
	Update an item.
IMPORT_C TInt	Add (CFavouritesItem &aItem, TBool aAutoRename)
	Add a new item to the database.
IMPORT_C TInt	SetHomepage (CFavouritesItem &aItem)
	Update the Homepage item.
IMPORT_C TInt	SetLastVisited (CFavouritesItem &aItem)
	Update the Last Visited.
IMPORT_C TInt	SetFactoryItem (TInt aUid, TBool aFactoryItem)
	Set factory item flag on an item.
IMPORT_C TInt	SetReadOnly (TInt aUid, TBool aReadOnly)
	Set read-only flag on an item.
IMPORT_C TInt	SetModified (TInt aUid, TTime aModified)
	Manual setting of Last Modification Time of an item.
IMPORT_C TInt	SetPreferredUid (TInt aFolder, TInt aUid)
	Set preferred Uid for a folder.
IMPORT_C TInt	ItemExists (TInt aUid, TBool &aItemExists)
	Check if we already have this item.
IMPORT_C TInt	FolderExists (TInt aFolder, TBool &aFolderExists)
	Check if the folder exists.
IMPORT_C TInt	Count (TInt &aCount, TInt aParentFolderFilter=KFavouritesNullUid, CFavouritesItem::TType aTypeFilter=CFavouritesItem::ENone, const TDesC *aNameFilter=NULL, TInt32 aContextIdFilter=KFavouritesNullContextId)
	Count all items matching the supplied criteria.
IMPORT_C TInt	SetData (TInt aUid, const MFavouritesItemData &aData)
	Set data associated with an item.
IMPORT_C TInt	GetData (TInt aUid, MFavouritesItemData &aData)
	Get data associated with an item.
IMPORT_C TInt	SetBrowserData (TInt aUid, const MFavouritesItemData &aData)
	Set Browser data associated with an item.
IMPORT_C TInt	GetBrowserData (TInt aUid, MFavouritesItemData &aData)
	Get Browser associated with an item.
IMPORT_C TInt	MakeUniqueName (TDes &aName, TInt aFolder)
	Check if aName is unique in aFolder; and if not, change to an unique one, appending a number.
IMPORT_C TInt	MakeUniqueName (CFavouritesItem &aItem)
	Check if aName is unique in its folder; and if not, change to an unique one, appending a number.
IMPORT_C CFavouritesItem *	CreateStartPageItemL ()
	Create an empty item with uid KFavouritesStartPageUid.
IMPORT_C CFavouritesItem *	CreateAdaptiveItemsFolderL ()
	Create a folder with uid KFavouritesAdaptiveItemsFolderUid.
IMPORT_C TInt	DeleteFile (TInt aUid)
	Delete file.
Static Public Member Functions
static IMPORT_C void	RestoreFactorySettingsL (const TDesC &aName, const TDesC &aReferenceDbPath, MRfsApMapper &aApMapper)
	User-level Restore Factory Settings operation.

Member Function Documentation

IMPORT_C TInt RFavouritesDb::Add	(	CFavouritesItem &	aItem,
		TBool	aAutoRename
	)

Add a new item to the database.

If successful, its Uid, Last-Mod-Time (and possibly its name) is updated on return.

Parameters:

	aItem	The item to add.
	aAutoRename	If this is ETrue, and the name already exists, the item will be renamed to a non-conflicting name.

Returns:

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 RFavouritesDb::Begin ( TBool aWrite = EFalse )

Explicitly begin a transaction.

Parameters:

aWrite

Access mode.

Returns:: Error code.

IMPORT_C void RFavouritesDb::CleanupRollbackPushL

(

)

Push a rollback on the cleanup stack.

Call this after Begin() call, to make the transaction leave-safe.

Returns:: void

IMPORT_C TInt RFavouritesDb::Commit

(

)

Commit the transaction.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::Compact

(

)

Perform databas synchronous compaction.

This function requires exclusive access to the database.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::Count	(	TInt &	aCount,
		TInt	aParentFolderFilter = `KFavouritesNullUid`,
		CFavouritesItem::TType	aTypeFilter = `CFavouritesItem::ENone`,
		const TDesC *	aNameFilter = `NULL`,
		TInt32	aContextIdFilter = `KFavouritesNullContextId`
	)

Count all items matching the supplied criteria.

Parameters:

	aCount	Placeholder for the returned item count. In case of any error, existing value is unchanged.
	aParentFolderFilter	Uid value to filter. KFavouritesNullUid clears (all accepted); this is the default.
	aTypeFilter	EItem or EFolder to use filter; ENone to clear filter (all accepted); this is the default.
	aNameFilter	Wildcard pattern to be used for name matching. NULL clears (all accepted); this is the default.
	aContextIdFilter	ContextId value to filter. KFavouritesNullContextId clears (all accepted); this is the default.

Returns:: Error code.

IMPORT_C CFavouritesItem* RFavouritesDb::CreateAdaptiveItemsFolderL

(

)

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.

Returns:: The created item.

IMPORT_C CFavouritesItem* RFavouritesDb::CreateStartPageItemL

(

)

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.

Returns:: The created item.

IMPORT_C TInt RFavouritesDb::Delete

(

TInt

aUid

)

Delete item by Uid.

If this is a folder, all descendants and the contents of them are deleted. Homepage or root cannot be deleted.

Parameters:

aUid

Uid of item to delete.

Returns:

Error code, including:

KErrNotFound if the item is not found.
KErrAccessDenied if the item's cannot be deleted.

IMPORT_C TInt RFavouritesDb::DeleteFile

(

TInt

aUid

)

Delete file.

See RFavouritesFile.

Parameters:

aUid

Uid of the item.

Returns:: Errro code.

IMPORT_C TInt RFavouritesDb::FolderExists	(	TInt	aFolder,
		TBool &	aFolderExists
	)

Check if the folder exists.

Parameters:

	aFolder	The folder to be checked.
	aFolderExists	Returned value.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::Get	(	TInt	aUid,
		CFavouritesItem &	aItem
	)

Get the item with this Uid.

Parameters:

	aUid	Uid or item to get.
	aItem	placeholder for the returned item data.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::GetAll	(	CFavouritesItemList &	aItemList,
		TInt	aParentFolderFilter = `KFavouritesNullUid`,
		CFavouritesItem::TType	aTypeFilter = `CFavouritesItem::ENone`,
		const TDesC *	aNameFilter = `NULL`,
		TInt32	aContextIdFilter = `KFavouritesNullContextId`
	)

Get all items matching the supplied criteria.

Parameters:

	aItemList	placeholder for the returned item data. Existing items remain (new ones appended).
	aParentFolderFilter	Uid value to filter. KFavouritesNullUid clears (all accepted); this is the default.
	aTypeFilter	EItem or EFolder to use filter; ENone to clear filter (all accepted); this is the default.
	aNameFilter	wildcard pattern to be used for name matching. NULL clears (all accepted); this is the default.
	aContextIdFilter	ContextId value to filter. KFavouritesNullContextId clears (all accepted); this is the default.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::GetBrowserData	(	TInt	aUid,
		MFavouritesItemData &	aData
	)

Get Browser associated with an item.

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

Parameters:

	aUid	The uid of the item, to which the data belongs.
	aData	Data object, which receives the data.

Returns:

Error code, including:

KErrNotFound No item is found with aUid.

IMPORT_C TInt RFavouritesDb::GetData	(	TInt	aUid,
		MFavouritesItemData &	aData
	)

Get data associated with an item.

Parameters:

	aUid	The uid of the item, to which the data belongs.
	aData	Data object, which receives the data.

Returns:

Error code, including:

KErrNotFound No item is found with aUid.

IMPORT_C TInt RFavouritesDb::GetUids	(	CArrayFix< TInt > &	aUids,
		TInt	aParentFolderFilter = `KFavouritesNullUid`,
		CFavouritesItem::TType	aTypeFilter = `CFavouritesItem::ENone`,
		const TDesC *	aNameFilter = `NULL`,
		TInt32	aContextIdFilter = `KFavouritesNullContextId`
	)

Get uids of all items matching the supplied criteria.

Parameters:

	aUids	placeholder for the returned item data. Existing items remain (new ones appended).
	aParentFolderFilter	Uid value to filter. KFavouritesNullUid clears (all accepted); this is the default.
	aTypeFilter	EItem or EFolder to use filter; ENone to clear filter (all accepted); this is the default.
	aNameFilter	wildcard pattern to be used for name matching. NULL clears (all accepted); this is the default.
	aContextIdFilter	ContextId value to filter. KFavouritesNullContextId clears (all accepted); this is the default.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::IsDamaged

(

TBool &

aIsDamaged

)

Check if the database to be recovered is fully functional.

Parameters:

aIsDamaged

Result is returned here.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::ItemExists	(	TInt	aUid,
		TBool &	aItemExists
	)

Check if we already have this item.

Parameters:

	aUid	The item Uid to be checked.
	aItemExists	Returned value.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::MakeUniqueName

(

CFavouritesItem &

aItem

)

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

Parameters:

aItem

Item to set unique name for.

Returns:

Error code, including:

KErrArgument aFolder is not found.
KErrBadName Current name is empty.

IMPORT_C TInt RFavouritesDb::MakeUniqueName	(	TDes &	aName,
		TInt	aFolder
	)

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

Parameters:

	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.)
	aFolder	Folder to be used for uniqueness-checking.

Returns:

Error code, including:

KErrArgument aFolder is not found.
KErrBadName aName is empty.

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

Open the database.

Created if does not exist.

Parameters:

	aSess	Session to be used.
	aName	Database name.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::PreferredUid	(	TInt	aFolder,
		TInt &	aPreferredUid
	)

Get preferred Uid for a folder.

Parameters:

	aFolder	Folder Uid.
	aPreferredUid	Uid of preferred item is returned here.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::Recover

(

)

Perform database synchronous recovery.

This function requires exclusive access to the database.

Returns:: Error code.

static IMPORT_C void RFavouritesDb::RestoreFactorySettingsL	(	const TDesC &	aName,
		const TDesC &	aReferenceDbPath,
		MRfsApMapper &	aApMapper
	)	`[static]`

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.

Parameters:

	aName	Database name.
	aReferenceDbPath	Full pathname of reference database.
	aApMapper	Access Point mapper to be used.

IMPORT_C void RFavouritesDb::Rollback

(

)

Roll back the transaction.

Returns:: void

IMPORT_C TInt RFavouritesDb::SetBrowserData	(	TInt	aUid,
		const MFavouritesItemData &	aData
	)

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.

Parameters:

	aUid	The uid of the item, to which the data belongs.
	aData	Data) which replaces existing data.

Returns:

Error code, including:

KErrNotFound No item is found with aUid.

IMPORT_C TInt RFavouritesDb::SetData	(	TInt	aUid,
		const MFavouritesItemData &	aData
	)

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.

Parameters:

	aUid	The uid of the item, to which the data belongs.
	aData	Data) which replaces existing data.

Returns:

Error code, including:

KErrNotFound No item is found with aUid.

IMPORT_C TInt RFavouritesDb::SetFactoryItem	(	TInt	aUid,
		TBool	aFactoryItem
	)

Set factory item flag on an item.

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

Parameters:

	aUid	Uid of item.
	aFactoryItem	Flag value to set.

Returns:

Error code, including:

KErrNotFound if the item is not found.

IMPORT_C TInt RFavouritesDb::SetHomepage

(

CFavouritesItem &

aItem

)

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.

Parameters:

aItem

Contents from this item (except Uid) will be used to update the Homepage Bookmark.

Returns:

Error code, including:

KErrArgument if the supplied item is not item, or is not in the root folder.

IMPORT_C TInt RFavouritesDb::SetLastVisited

(

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.

Parameters:

aItem

Contents from this item (except Uid) will be used to update the Last Visited Item.

Returns:

Error code, including:

KErrArgument if the supplied item is not item, or is not in the root folder.

IMPORT_C TInt RFavouritesDb::SetModified	(	TInt	aUid,
		TTime	aModified
	)

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.

Parameters:

	aUid	Uid of item.
	aModified	Last Modification Time to set.

Returns:

Error code, including:

KErrNotFound if the item is not found.

IMPORT_C TInt RFavouritesDb::SetPreferredUid	(	TInt	aFolder,
		TInt	aUid
	)

Set preferred Uid for a folder.

Parameters:

	aFolder	Folder Uid.
	aUid	Uid to be set as preferred. Not checked to exist in the folder.

Returns:

Error code, including:

KErrNotFound if aFolder is not found;
KErrArgument if aFolder is not a folder.

IMPORT_C TInt RFavouritesDb::SetReadOnly	(	TInt	aUid,
		TBool	aReadOnly
	)

Set read-only flag on an item.

Parameters:

	aUid	Uid of item.
	aReadOnly	Flag value to set.

Returns:

Error code, including:

KErrNotFound if the item is not found.

IMPORT_C TInt RFavouritesDb::Size

(

RDbDatabase::TSize &

aSize

)

const

Get available database size.

Parameters:

aSize

Database size returned here.

Returns:: Error code.

IMPORT_C TInt RFavouritesDb::Update	(	CFavouritesItem &	aItem,
		TInt	aUid,
		TBool	aAutoRename
	)

Update an item.

Remember Homapage or Last Visited Page cannot be updated using this method.

Parameters:

	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.
	aUid	Update this item.
	aAutoRename	If this is ETrue, and the name already exists, the item will be renamed to a non-conflicting name.

Returns:

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 RFavouritesDb::UpdateStats

(

)

Update database statistics.

Returns:: Error code.

IMPORT_C TVersion RFavouritesDb::Version

(

)

const

Get version information.

Returns:: Version object of this CFavouritesDb.

The documentation for this class was generated from the following file:

favouritesdb.h

RFavouritesDb Class Reference

Capability Information

Detailed Description

Public Member Functions

Static Public Member Functions

Member Function Documentation