--- 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 <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
+
+