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