Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
/*
* 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