CPosLmCategoryManager Class Reference

API published in: S60 3rd Ed

Link against: eposlandmarks.lib

Capability Information

Required Capabilities

None

Exceptions

The capability ReadUserData is required in:

CPosLandmarkDatabase::OpenL();

CPosLandmarkDatabase::OpenL( const TDesC & aDatabaseUri );

CPosLandmarkDatabase::InitializeL();

CPosLandmarkDatabase::ReadLandmarkLC( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::LandmarkIteratorL();

CPosLandmarkDatabase::LandmarkIteratorL( const TPosLmSortPref & aSortPref );

CPosLandmarkDatabase::AddLandmarkL( CPosLandmark & aLandmark );

CPosLandmarkDatabase::UpdateLandmarkL( const CPosLandmark & aLandmark );

CPosLandmarkDatabase::RemoveLandmarkL( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::RemoveLandmarksL( const RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLandmarkDatabase::RemoveAllLandmarksL();

CPosLandmarkDatabase::ReadPartialLandmarkLC( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::PreparePartialLandmarksL( const RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLandmarkDatabase::SizeL();

CPosLandmarkDatabase::CompactL();

CPosLandmarkDatabase::NotifyDatabaseEvent( TPosLmEvent & aEvent, TRequestStatus & aStatus );

CPosLandmarkDatabase::CancelNotifyDatabaseEvent();

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, TTransferOptions aTransferOptions );

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, const RArray<TUint>& aLandmarkSelection, TTransferOptions aTransferOptions );

CPosLmCategoryManager::ReadCategoryLC( TPosLmItemId aCategoryId );

CPosLmCategoryManager::CategoryIteratorL( TCategorySortPref aSortPref );

CPosLmCategoryManager::ReferencedCategoryIteratorL( TCategorySortPref aSortPref )

CPosLmCategoryManager::AddCategoryL( CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::UpdateCategoryL( const CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::RemoveCategoryL( TPosLmItemId aCategoryId );

CPosLmCategoryManager::RemoveCategoriesL( const RArray< TPosLmItemId > & aCategoryIdArray );

CPosLmCategoryManager::AddCategoryToLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::RemoveCategoryFromLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::GetCategoryL( const TDesC & aCategoryName );

CPosLmCategoryManager::GetGlobalCategoryL( TPosLmGlobalCategory aGlobalCategory );

CPosLmCategoryManager::ResetGlobalCategoriesL();

The capability WriteUserData is required in:

CPosLandmarkDatabase::AddLandmarkL( CPosLandmark& aLandmark );

CPosLandmarkDatabase::UpdateLandmarkL( const CPosLandmark& aLandmark );

CPosLandmarkDatabase::RemoveLandmarkL( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::RemoveLandmarksL( const RArray<TPosLmItemId>& aLandmarkIdArray );

CPosLandmarkDatabase::RemoveAllLandmarksL();

CPosLandmarkDatabase::CompactL();

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, TTransferOptions aTransferOptions );

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, const RArray<TUint>& aLandmarkSelection, TTransferOptions aTransferOptions );

CPosLmCategoryManager::AddCategoryL( CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::UpdateCategoryL( const CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::RemoveCategoryL( TPosLmItemId aCategoryId );

CPosLmCategoryManager::RemoveCategoriesL( const RArray< TPosLmItemId > & aCategoryIdArray );

CPosLmCategoryManager::AddCategoryToLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::RemoveCategoryFromLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::ResetGlobalCategoriesL();

Other Information

The capability NetworkServices is required to work with remote databases.

#include <epos_cposlmcategorymanager.h>

Detailed Description

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.

NetworkServices capability is required for remote databases.


Public Types
enum	TCategorySortPref { ECategorySortOrderNone = 0, ECategorySortOrderNameAscending, ECategorySortOrderNameDescending }
	Specifies the sort preference for landmark categories. More...
Public Member Functions
virtual IMPORT_C	~CPosLmCategoryManager ()
	Destructor.
virtual CPosLandmarkCategory *	ReadCategoryLC (TPosLmItemId aCategoryId)=0
	Reads a landmark category from the database.
virtual CPosLmItemIterator *	CategoryIteratorL (TCategorySortPref aSortPref=ECategorySortOrderNone)=0
	Returns an object for iterating the landmark categories in the database.
virtual CPosLmItemIterator *	ReferencedCategoryIteratorL (TCategorySortPref aSortPref=ECategorySortOrderNone)=0
	Returns an object for iterating referenced landmark categories in the database.
virtual TPosLmItemId	AddCategoryL (CPosLandmarkCategory &aCategory)=0
	Adds a landmark category to the database and returns its ID.
virtual void	UpdateCategoryL (const CPosLandmarkCategory &aCategory)=0
	Updates a landmark category in the database.
virtual CPosLmOperation *	RemoveCategoryL (TPosLmItemId aCategoryId)=0
	Removes a landmark category from the database.
virtual CPosLmOperation *	RemoveCategoriesL (const RArray< TPosLmItemId > &aCategoryIdArray)=0
	Remove a set of landmark categories from the database.
virtual CPosLmOperation *	AddCategoryToLandmarksL (TPosLmItemId aCategoryId, RArray< TPosLmItemId > &aLandmarkIdArray)=0
	Adds a category to a set of landmarks.
virtual CPosLmOperation *	RemoveCategoryFromLandmarksL (TPosLmItemId aCategoryId, RArray< TPosLmItemId > &aLandmarkIdArray)=0
	Removes a category from a set of landmarks.
virtual TPosLmItemId	GetCategoryL (const TDesC &aCategoryName)=0
	Gets a category by name.
virtual TPosLmItemId	GetGlobalCategoryL (TPosLmGlobalCategory aGlobalCategory)=0
	Gets the ID of a global category.
virtual HBufC *	GlobalCategoryNameL (TPosLmGlobalCategory aGlobalCategory)=0
	Gets the predefined name of a global category.
virtual CPosLmOperation *	ResetGlobalCategoriesL ()=0
	Resets the information for all global categories.
Static Public Member Functions
static IMPORT_C CPosLmCategoryManager *	NewL (CPosLandmarkDatabase &aLandmarkDatabase)
	Two-phased constructor.
Protected Member Functions
IMPORT_C	CPosLmCategoryManager ()

Member Enumeration Documentation

enum CPosLmCategoryManager::TCategorySortPref

Specifies the sort preference for landmark categories.

Enumerator:

ECategorySortOrderNone	Categories not sorted.
ECategorySortOrderNameAscending	Sorted ascending by category name.
ECategorySortOrderNameDescending	Sorted descending by category name.

Constructor & Destructor Documentation

virtual IMPORT_C CPosLmCategoryManager::~CPosLmCategoryManager ( ) [virtual]

Destructor.

IMPORT_C CPosLmCategoryManager::CPosLmCategoryManager ( ) [protected]

Member Function Documentation

virtual TPosLmItemId CPosLmCategoryManager::AddCategoryL ( CPosLandmarkCategory & aCategory ) [pure virtual]

Adds a landmark category to the database and returns its ID.

Precondition:: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded).

Note: Clients are not allowed to create global categories.

This function requires ReadUserData and WriteUserData capabilities.

Postcondition:: Category is added to the database and category object has database item set (CPosLandmarkCategory::CategoryId()).

Parameters:

[in,out] aCategory The landmark category to add.

Returns:: 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 CPosLmOperation* CPosLmCategoryManager::AddCategoryToLandmarksL	(	TPosLmItemId	aCategoryId,
		RArray< TPosLmItemId > &	aLandmarkIdArray
	)	`[pure virtual]`

Adds a category to a set of landmarks.

Precondition:: Database is initialized (see 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 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 CPosLandmarkDatabase::UpdateLandmark for this change to take place.

If the database is read only, the returned operation will fail with error code KErrAccessDenied.

While adding the category to the landmarks, this operation will acquire a write-lock on the database.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

`[in]`	aCategoryId	The category to add to the set of landmarks.
`[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 CPosLmItemIterator* CPosLmCategoryManager::CategoryIteratorL ( TCategorySortPref aSortPref = ECategorySortOrderNone ) [pure virtual]

Returns an object for iterating the landmark categories in the database.

Precondition:: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded).

The iterator object is reset, so that the first CPosLmItemIterator::NextL call will return the first landmark category.

The client takes ownership of the returned iterator object.

This function requires ReadUserData capability.

Parameters:

[in] aSortPref How to sort the categories. Default is no sorting.

Returns:: The landmark iterator.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

Panic:: "Landmarks Client"-EPosInvalidEnumValue Client specified invalid sort preference.

virtual TPosLmItemId CPosLmCategoryManager::GetCategoryL ( const TDesC & aCategoryName ) [pure virtual]

Gets a category by name.

Precondition:: Database is initialized (see 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 ReadUserData capability.

Parameters:

[in] aCategoryName The name of the category to get.

Returns:: 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 CPosLmCategoryManager::GetGlobalCategoryL ( TPosLmGlobalCategory aGlobalCategory ) [pure virtual]

Gets the ID of a global category.

Precondition:: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded).

This function requires ReadUserData capability.

Parameters:

[in] aGlobalCategory The global category to look for.

Returns:: 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 HBufC* CPosLmCategoryManager::GlobalCategoryNameL ( TPosLmGlobalCategory aGlobalCategory ) [pure virtual]

Gets the predefined name of a global category.

Precondition:: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded).

Parameters:

[in] aGlobalCategory The global category to get a name for.

Returns:: The name of the global category or NULL if the category is not recognized.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

static IMPORT_C CPosLmCategoryManager* CPosLmCategoryManager::NewL ( CPosLandmarkDatabase & aLandmarkDatabase ) [static]

Two-phased constructor.

The client takes ownership of the category manager.

Parameters:

[in] aLandmarkDatabase The landmark database to manage categories in.

Returns:: A new instance of this class.

virtual CPosLandmarkCategory* CPosLmCategoryManager::ReadCategoryLC ( TPosLmItemId aCategoryId ) [pure virtual]

Reads a landmark category from the database.

Precondition:: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded).

The client takes ownership of the returned category object.

This function requires ReadUserData capability.

Parameters:

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 CPosLmItemIterator* CPosLmCategoryManager::ReferencedCategoryIteratorL ( TCategorySortPref aSortPref = ECategorySortOrderNone ) [pure virtual]

Returns an object for iterating referenced landmark categories in the database.

Precondition:: Database is initialized (see 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 CPosLmItemIterator::NextL call will return the first landmark category.

The client takes ownership of the returned iterator object.

This function requires ReadUserData capability.

Parameters:

[in] aSortPref How to sort the categories. Default is no sorting.

Returns:: The landmark iterator.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

Panic:: "Landmarks Client"-EPosInvalidEnumValue Client specified invalid sort preference.

virtual CPosLmOperation* CPosLmCategoryManager::RemoveCategoriesL ( const RArray< TPosLmItemId > & aCategoryIdArray ) [pure virtual]

Remove a set of landmark categories from the database.

Precondition:: Database is initialized (see 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 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 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 ReadUserData and WriteUserData capabilities.

Parameters:

aCategoryIdArray

The IDs of the landmark categories to delete.

Returns:: A handle to the operation.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual CPosLmOperation* CPosLmCategoryManager::RemoveCategoryFromLandmarksL	(	TPosLmItemId	aCategoryId,
		RArray< TPosLmItemId > &	aLandmarkIdArray
	)	`[pure virtual]`

Removes a category from a set of landmarks.

Precondition:: Database is initialized (see 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 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 KErrAccessDenied.

While removing the category from the landmarks, this operation will acquire a write-lock on the database.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

`[in]`	aCategoryId	The category to remove from the set of landmarks.
`[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* CPosLmCategoryManager::RemoveCategoryL ( TPosLmItemId aCategoryId ) [pure virtual]

Removes a landmark category from the database.

Precondition:: Database is initialized (see 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 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 ReadUserData and WriteUserData capabilities.

Parameters:

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* CPosLmCategoryManager::ResetGlobalCategoriesL ( ) [pure virtual]

Resets the information for all global categories.

Precondition:: Database is initialized (see 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 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 ReadUserData and WriteUserData capabilities.

Returns:: A handle to the operation.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual void CPosLmCategoryManager::UpdateCategoryL ( const CPosLandmarkCategory & aCategory ) [pure virtual]

Updates a landmark category in the database.

Precondition:: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded).

Note: Clients are not allowed to change the global category identifier in the category object.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

[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.

The documentation for this class was generated from the following file:

epos_cposlmcategorymanager.h

Copyright © Nokia Corporation 2001-2008