diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/favouritesdb.h --- a/epoc32/include/mw/favouritesdb.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/favouritesdb.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,555 @@ -favouritesdb.h +/* +* 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 +#include +#include +#include +#include +#include + +// 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& 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