/*

 * 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 "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:  CPosLmCategoryManager class

 *

 */

 #ifndef CPOSLMCATEGORYMANAGER_H

 #define CPOSLMCATEGORYMANAGER_H

 #include <e32base.h>

 #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<TPosLmItemId>& 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<TPosLmItemId>& 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<TPosLmItemId>& 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