williamr@2: /* williamr@2: * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: CPosLmCategoryManager class williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef CPOSLMCATEGORYMANAGER_H williamr@2: #define CPOSLMCATEGORYMANAGER_H williamr@2: williamr@2: #include williamr@4: #include "EPos_CPosLandmarkDatabase.h" williamr@4: #include "EPos_CPosLandmarkCategory.h" williamr@4: #include "EPos_CPosLmItemIterator.h" williamr@4: #include "EPos_CPosLmOperation.h" williamr@2: williamr@2: /** williamr@2: * Category management for a landmark database. williamr@2: * williamr@2: * A landmark database can contain a number of categories which can be williamr@2: * assigned to the landmarks in the database. A landmark can be associated williamr@2: * with multiple categories, e.g. a landmark can be a "Restaurant" and a "Pub". williamr@2: * Categories also enable filtered searches, e.g. a client could search for williamr@2: * nearby restaurants. williamr@2: * williamr@2: * This class contains functions for managing landmark categories. This includes williamr@2: * reading, listing, creating and updating landmark categories. williamr@2: * williamr@2: * @p NetworkServices capability is required for remote databases. williamr@2: * williamr@2: * @lib eposlandmarks.lib williamr@2: * @since S60 3.0 williamr@2: */ williamr@2: class CPosLmCategoryManager : public CBase williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Specifies the sort preference for landmark categories. williamr@2: */ williamr@2: enum TCategorySortPref williamr@2: { williamr@2: ECategorySortOrderNone = 0 /**< williamr@2: Categories not sorted */, williamr@2: ECategorySortOrderNameAscending /**< williamr@2: Sorted ascending by category name. */, williamr@2: ECategorySortOrderNameDescending /**< williamr@2: Sorted descending by category name. */ williamr@2: }; williamr@2: williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * williamr@2: * The client takes ownership of the category manager. williamr@2: * williamr@2: * @param[in] aLandmarkDatabase The landmark database to manage categories in. williamr@2: * @returns A new instance of this class. williamr@2: */ williamr@2: IMPORT_C static CPosLmCategoryManager* NewL( williamr@2: CPosLandmarkDatabase& aLandmarkDatabase williamr@2: ); williamr@2: williamr@2: /** williamr@2: * Destructor. williamr@2: */ williamr@2: IMPORT_C virtual ~CPosLmCategoryManager(); williamr@2: williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Reads a landmark category from the database. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * The client takes ownership of the returned category object. williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param aCategoryId The ID of the landmark category to read. williamr@2: * @returns The requested landmark category. The category object is put williamr@2: * on the cleanup stack. williamr@2: * williamr@2: * @leave KErrNotFound The landmark category does not exist in the database. williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual CPosLandmarkCategory* ReadCategoryLC( TPosLmItemId aCategoryId ) = 0; williamr@2: williamr@2: /** williamr@2: * Returns an object for iterating the landmark categories in the williamr@2: * database. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * The iterator object is reset, so that the first williamr@2: * @ref CPosLmItemIterator::NextL call will return the first landmark williamr@2: * category. williamr@2: * williamr@2: * The client takes ownership of the returned iterator object. williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param[in] aSortPref How to sort the categories. Default is no sorting. williamr@2: * @return The landmark iterator. williamr@2: * williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: * williamr@2: * @panic "Landmarks Client"-EPosInvalidEnumValue williamr@2: * Client specified invalid sort preference. williamr@2: */ williamr@2: virtual CPosLmItemIterator* CategoryIteratorL( williamr@2: TCategorySortPref aSortPref = ECategorySortOrderNone williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Returns an object for iterating referenced landmark categories in williamr@2: * the database. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * A category is referenced if there are landmarks in the database which williamr@2: * contains this category. williamr@2: * williamr@2: * The iterator object is reset, so that the first williamr@2: * @ref CPosLmItemIterator::NextL call will return the first landmark williamr@2: * category. williamr@2: * williamr@2: * The client takes ownership of the returned iterator object. williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param[in] aSortPref How to sort the categories. Default is no sorting. williamr@2: * @return The landmark iterator. williamr@2: * williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: * williamr@2: * @panic "Landmarks Client"-EPosInvalidEnumValue williamr@2: * Client specified invalid sort preference. williamr@2: */ williamr@2: virtual CPosLmItemIterator* ReferencedCategoryIteratorL( williamr@2: TCategorySortPref aSortPref = ECategorySortOrderNone williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Adds a landmark category to the database and returns its ID. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * Note: Clients are not allowed to create global categories. williamr@2: * williamr@2: * This function requires @p ReadUserData and @p WriteUserData williamr@2: * capabilities. williamr@2: * williamr@2: * @post Category is added to the database and category object williamr@2: * has database item set (CPosLandmarkCategory::CategoryId()). williamr@2: * williamr@2: * @param[in,out] aCategory The landmark category to add. williamr@2: * @return The ID of the new category. williamr@2: * williamr@2: * @leave KErrArgument 1) Input category does not have a name set or williamr@2: * 2) if a global category is set in the category object. williamr@2: * @leave KErrAlreadyExists A category with the same name williamr@2: * already exists in the database. williamr@2: * @leave KErrAccessDenied The database is read-only. williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual TPosLmItemId AddCategoryL( williamr@2: CPosLandmarkCategory& aCategory williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Updates a landmark category in the database. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * Note: Clients are not allowed to change the global category identifier in williamr@2: * the category object. williamr@2: * williamr@2: * This function requires @p ReadUserData and @p WriteUserData williamr@2: * capabilities. williamr@2: * williamr@2: * @param[in] aCategory The new landmark category data. williamr@2: * williamr@2: * @leave KErrArgument 1) Input category does not have a name set or williamr@2: * 2) if a global category identifier is changed in the category object. williamr@2: * @leave KErrAlreadyExists A category with the same name williamr@2: * already exists in the database. williamr@2: * @leave KErrAccessDenied The database is read-only. williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual void UpdateCategoryL( williamr@2: const CPosLandmarkCategory& aCategory williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Removes a landmark category from the database. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * If the landmark category does not exist in the database, nothing williamr@2: * happens. williamr@2: * williamr@2: * This call will also remove the category from all landmarks which williamr@2: * contained it. williamr@2: * williamr@2: * The function returns an operation object which can be run in either williamr@2: * synchronous or asynchronous mode. If it is run in asynchronous mode williamr@2: * the client can supervise the progress of the operation. williamr@2: * williamr@2: * If the @ref CPosLmOperation object is deleted before the operation williamr@2: * is complete, it is possible that the category has not been removed, williamr@2: * but some landmarks may no longer contain this category williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * While removing the category, this operation will acquire a williamr@2: * write-lock on the database. williamr@2: * williamr@2: * This function requires @p ReadUserData and @p WriteUserData williamr@2: * capabilities. williamr@2: * williamr@2: * @param aCategoryId The ID of the landmark category to delete. williamr@2: * @returns A handle to the operation. williamr@2: * williamr@2: * @leave KErrAccessDenied The database is read-only. williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual CPosLmOperation* RemoveCategoryL( TPosLmItemId aCategoryId ) = 0; williamr@2: williamr@2: /** williamr@2: * Remove a set of landmark categories from the database. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * If any of the landmark categories does not exist in the database, it williamr@2: * is ignored. williamr@2: * williamr@2: * This call will also remove the categories from all landmarks which williamr@2: * contained them. williamr@2: * williamr@2: * The function returns an operation object which can be run in either williamr@2: * synchronous or asynchronous mode. If it is run in asynchronous mode williamr@2: * the client can supervise the progress of the operation. williamr@2: * williamr@2: * If the @ref CPosLmOperation object is deleted before the operation williamr@2: * is complete, it is possible that only a subset of the landmark williamr@2: * categories have been deleted. williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * If the database is read only, the returned operation will fail with error williamr@2: * code @p KErrAccessDenied. williamr@2: * williamr@2: * This call will also remove the categories from all landmarks which williamr@2: * contained them. williamr@2: * williamr@2: * While removing the category, this operation will acquire a williamr@2: * write-lock on the database. williamr@2: * williamr@2: * This function requires @p ReadUserData and @p WriteUserData williamr@2: * capabilities. williamr@2: * williamr@2: * @param aCategoryIdArray The IDs of the landmark categories to delete. williamr@2: * @returns A handle to the operation. williamr@2: * williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual CPosLmOperation* RemoveCategoriesL( williamr@2: const RArray& aCategoryIdArray williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Adds a category to a set of landmarks. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * If any of the specified landmarks does not exist, the category will williamr@2: * be added to the other landmarks. No error will be reported though. williamr@2: * williamr@2: * If the category is already contained in one of the landmarks, nothing williamr@2: * will be further added to that landmark. williamr@2: * williamr@2: * The function returns an operation object which can be run in either williamr@2: * synchronous or asynchronous mode. If it is run in asynchronous mode williamr@2: * the client can supervise the progress of the operation. williamr@2: * williamr@2: * If the @ref CPosLmOperation object is deleted before the operation williamr@2: * is complete, it is possible that the category has only been added williamr@2: * to a subset of the landmarks. williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * Note: There is no need to call williamr@2: * @p CPosLandmarkDatabase::UpdateLandmark for this change to take williamr@2: * place. williamr@2: * williamr@2: * If the database is read only, the returned operation will fail with error williamr@2: * code @p KErrAccessDenied. williamr@2: * williamr@2: * While adding the category to the landmarks, this operation will williamr@2: * acquire a write-lock on the database. williamr@2: * williamr@2: * This function requires @p ReadUserData and @p WriteUserData williamr@2: * capabilities. williamr@2: * williamr@2: * @param[in] aCategoryId The category to add to the set of landmarks. williamr@2: * @param[in] aLandmarkIdArray The landmarks to add the category to. williamr@2: * @returns A handle to the operation. williamr@2: * williamr@2: * @leave KErrNotFound The specified category does not exist in database. williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual CPosLmOperation* AddCategoryToLandmarksL( williamr@2: TPosLmItemId aCategoryId, williamr@2: RArray& aLandmarkIdArray williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Removes a category from a set of landmarks. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * If any of the specified landmarks does not exist, the category will williamr@2: * be removed from the other landmarks. No error will be reported though. williamr@2: * williamr@2: * If the category is not found in one of the landmarks, nothing will williamr@2: * happen for that landmark. williamr@2: * williamr@2: * The function returns an operation object which can be run in either williamr@2: * synchronous or asynchronous mode. If it is run in asynchronous mode williamr@2: * the client can supervise the progress of the operation. williamr@2: * williamr@2: * If the @ref CPosLmOperation object is deleted before the operation williamr@2: * is complete, it is possible that the category has only been removed williamr@2: * from a subset of the landmarks. williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * If the database is read only, the returned operation will fail with error williamr@2: * code @p KErrAccessDenied. williamr@2: * williamr@2: * While removing the category from the landmarks, this operation will williamr@2: * acquire a write-lock on the database. williamr@2: * williamr@2: * This function requires @p ReadUserData and @p WriteUserData williamr@2: * capabilities. williamr@2: * williamr@2: * @param[in] aCategoryId The category to remove from the set of landmarks. williamr@2: * @param[in] aLandmarkIdArray The landmarks to remove the category from. williamr@2: * @returns A handle to the operation. williamr@2: * williamr@2: * @leave KErrNotFound The specified category does not exist in database. williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual CPosLmOperation* RemoveCategoryFromLandmarksL( williamr@2: TPosLmItemId aCategoryId, williamr@2: RArray& aLandmarkIdArray williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Gets a category by name. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * The category name must be unique in the database, so there cannot be williamr@2: * multiple matches. williamr@2: * williamr@2: * This function only looks for an exact match. williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param[in] aCategoryName The name of the category to get. williamr@2: * @return @p KPosLmNullItemId if the category was not found, otherwise williamr@2: * the ID of the category item in the database. williamr@2: * williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual TPosLmItemId GetCategoryL( williamr@2: const TDesC& aCategoryName williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Gets the ID of a global category. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param[in] aGlobalCategory The global category to look for. williamr@2: * @return @p KPosLmNullItemId if the category was not found, otherwise williamr@2: * the ID of the category item in the database. williamr@2: * williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual TPosLmItemId GetGlobalCategoryL( williamr@2: TPosLmGlobalCategory aGlobalCategory williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Gets the predefined name of a global category. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * @param[in] aGlobalCategory The global category to get a name for. williamr@2: * @return The name of the global category or @p NULL if the category williamr@2: * is not recognized. williamr@2: * williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual HBufC* GlobalCategoryNameL( williamr@2: TPosLmGlobalCategory aGlobalCategory williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Resets the information for all global categories. williamr@2: * williamr@2: * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded). williamr@2: * williamr@2: * Global categories usually has a default name and icon. The client williamr@2: * can change the name and icon. This function resets the name and williamr@2: * icon to the default ones. williamr@2: * williamr@2: * The function returns an operation object which can be run in either williamr@2: * synchronous or asynchronous mode. If it is run in asynchronous mode williamr@2: * the client can supervise the progress of the operation. williamr@2: * williamr@2: * If the @ref CPosLmOperation object is deleted before the operation williamr@2: * is complete, it is possible that that only a subset of the global williamr@2: * categories have been resetted. williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * While resetting, this operation will acquire a write-lock on the williamr@2: * database. williamr@2: * williamr@2: * This function requires @p ReadUserData and @p WriteUserData williamr@2: * capabilities. williamr@2: * williamr@2: * @returns A handle to the operation. williamr@2: * williamr@2: * @leave KErrAccessDenied The database is read-only. williamr@2: * @leave KErrPosLmNotInitialized Database is not yet initialized. williamr@2: */ williamr@2: virtual CPosLmOperation* ResetGlobalCategoriesL() = 0; williamr@2: williamr@2: protected: williamr@2: williamr@2: // C++ constructor. williamr@2: IMPORT_C CPosLmCategoryManager(); williamr@2: williamr@2: private: williamr@2: williamr@2: // Prohibit copy constructor williamr@2: CPosLmCategoryManager( const CPosLmCategoryManager& ); williamr@2: // Prohibit assigment operator williamr@2: CPosLmCategoryManager& operator= ( const CPosLmCategoryManager& ); williamr@2: williamr@2: private: williamr@2: williamr@2: // Implementation UID williamr@2: TUid iDtorIdKey; williamr@2: williamr@2: }; williamr@2: williamr@2: #endif // CPOSLMCATEGORYMANAGER_H williamr@2: williamr@2: