CPosLmCategoryManager Class Reference

#include <mw/EPos_CPosLmCategoryManager.h>

Link against: eposlandmarks.lib

class CPosLmCategoryManager : public CBase

Inherits from

CPosLmCategoryManager

Public Member Enumerations
enum	TCategorySortPref { ECategorySortOrderNone, ECategorySortOrderNameAscending, ECategorySortOrderNameDescending }

Public Member Functions
virtual	~CPosLmCategoryManager()
pure virtual TPosLmItemId	AddCategoryL(CPosLandmarkCategory &)
pure virtual CPosLmOperation *	AddCategoryToLandmarksL(TPosLmItemId, RArray< TPosLmItemId > &)
pure virtual CPosLmItemIterator *	CategoryIteratorL(TCategorySortPref)
pure virtual TPosLmItemId	GetCategoryL(const TDesC &)
pure virtual TPosLmItemId	GetGlobalCategoryL(TPosLmGlobalCategory)
pure virtual HBufC *	GlobalCategoryNameL(TPosLmGlobalCategory)
IMPORT_C CPosLmCategoryManager *	NewL(CPosLandmarkDatabase &)
pure virtual CPosLandmarkCategory *	ReadCategoryLC(TPosLmItemId)
pure virtual CPosLmItemIterator *	ReferencedCategoryIteratorL(TCategorySortPref)
pure virtual CPosLmOperation *	RemoveCategoriesL(const RArray< TPosLmItemId > &)
pure virtual CPosLmOperation *	RemoveCategoryFromLandmarksL(TPosLmItemId, RArray< TPosLmItemId > &)
pure virtual CPosLmOperation *	RemoveCategoryL(TPosLmItemId)
pure virtual CPosLmOperation *	ResetGlobalCategoriesL()
pure virtual void	UpdateCategoryL(const CPosLandmarkCategory &)

Protected Member Functions
	CPosLmCategoryManager()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

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.

Since: S60 3.0

Member Enumeration Documentation

Enum TCategorySortPref

Specifies the sort preference for landmark categories.

Enumerator	Value	Description
ECategorySortOrderNone	0	Categories not sorted
ECategorySortOrderNameAscending		Sorted ascending by category name.
ECategorySortOrderNameDescending		Sorted descending by category name.

Constructor & Destructor Documentation

CPosLmCategoryManager ( )

IMPORT_C

CPosLmCategoryManager

(

)

[protected]

~CPosLmCategoryManager ( )

IMPORT_C

~CPosLmCategoryManager

(

)

[virtual]

Destructor.

Member Function Documentation

AddCategoryL ( CPosLandmarkCategory & )

TPosLmItemId

AddCategoryL

(

CPosLandmarkCategory &

aCategory

)

[pure virtual]

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

Pre-condition: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded ).

Note: Clients are not allowed to create global categories.

This function requires ReadUserData and WriteUserData capabilities.

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

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.

Parameter	Description
aCategory	The landmark category to add.

Returns: The ID of the new category.

AddCategoryToLandmarksL ( TPosLmItemId, RArray< TPosLmItemId > & )

CPosLmOperation *	AddCategoryToLandmarksL	(	TPosLmItemId	aCategoryId,
			RArray< TPosLmItemId > &	aLandmarkIdArray
		)	[pure virtual]

Adds a category to a set of landmarks.

Pre-condition: 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.

leave: KErrNotFound The specified category does not exist in database.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
aCategoryId	The category to add to the set of landmarks.
aLandmarkIdArray	The landmarks to add the category to.

Returns: A handle to the operation.

CategoryIteratorL ( TCategorySortPref )

CPosLmItemIterator *

CategoryIteratorL

(

TCategorySortPref

aSortPref = ECategorySortOrderNone

)

[pure virtual]

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

Pre-condition: 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.

leave: KErrPosLmNotInitialized Database is not yet initialized.

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

Parameter	Description
aSortPref	How to sort the categories. Default is no sorting.

Returns: The landmark iterator.

GetCategoryL ( const TDesC & )

TPosLmItemId

GetCategoryL

(

const TDesC &

aCategoryName

)

[pure virtual]

Gets a category by name.

Pre-condition: 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.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
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.

GetGlobalCategoryL ( TPosLmGlobalCategory )

TPosLmItemId

GetGlobalCategoryL

(

TPosLmGlobalCategory

aGlobalCategory

)

[pure virtual]

Gets the ID of a global category.

Pre-condition: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded ).

This function requires ReadUserData capability.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
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.

GlobalCategoryNameL ( TPosLmGlobalCategory )

HBufC *

GlobalCategoryNameL

(

TPosLmGlobalCategory

aGlobalCategory

)

[pure virtual]

Gets the predefined name of a global category.

Pre-condition: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded ).

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
aGlobalCategory	The global category to get a name for.

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

NewL ( CPosLandmarkDatabase & )

IMPORT_C CPosLmCategoryManager *

NewL

(

CPosLandmarkDatabase &

aLandmarkDatabase

)

[static]

Two-phased constructor.

The client takes ownership of the category manager.

Parameter	Description
aLandmarkDatabase	The landmark database to manage categories in.

Returns: A new instance of this class.

ReadCategoryLC ( TPosLmItemId )

CPosLandmarkCategory *

ReadCategoryLC

(

TPosLmItemId

aCategoryId

)

[pure virtual]

Reads a landmark category from the database.

Pre-condition: Database is initialized (see CPosLandmarkDatabase::IsInitializingNeeded ).

The client takes ownership of the returned category object.

This function requires ReadUserData capability.

leave: KErrNotFound The landmark category does not exist in the database.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
aCategoryId	The ID of the landmark category to read.

Returns: The requested landmark category. The category object is put on the cleanup stack.

ReferencedCategoryIteratorL ( TCategorySortPref )

CPosLmItemIterator *

ReferencedCategoryIteratorL

(

TCategorySortPref

aSortPref = ECategorySortOrderNone

)

[pure virtual]

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

Pre-condition: 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.

leave: KErrPosLmNotInitialized Database is not yet initialized.

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

Parameter	Description
aSortPref	How to sort the categories. Default is no sorting.

Returns: The landmark iterator.

RemoveCategoriesL ( const RArray< TPosLmItemId > & )

CPosLmOperation *

RemoveCategoriesL

(

const RArray< TPosLmItemId > &

aCategoryIdArray

)

[pure virtual]

Remove a set of landmark categories from the database.

Pre-condition: 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.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
aCategoryIdArray	The IDs of the landmark categories to delete.

Returns: A handle to the operation.

RemoveCategoryFromLandmarksL ( TPosLmItemId, RArray< TPosLmItemId > & )

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

Removes a category from a set of landmarks.

Pre-condition: 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.

leave: KErrNotFound The specified category does not exist in database.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
aCategoryId	The category to remove from the set of landmarks.
aLandmarkIdArray	The landmarks to remove the category from.

Returns: A handle to the operation.

RemoveCategoryL ( TPosLmItemId )

CPosLmOperation *

RemoveCategoryL

(

TPosLmItemId

aCategoryId

)

[pure virtual]

Removes a landmark category from the database.

Pre-condition: 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.

leave: KErrAccessDenied The database is read-only.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Parameter	Description
aCategoryId	The ID of the landmark category to delete.

Returns: A handle to the operation.

ResetGlobalCategoriesL ( )

CPosLmOperation *

ResetGlobalCategoriesL

(

)

[pure virtual]

Resets the information for all global categories.

Pre-condition: 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.

leave: KErrAccessDenied The database is read-only.

leave: KErrPosLmNotInitialized Database is not yet initialized.

Returns: A handle to the operation.

UpdateCategoryL ( const CPosLandmarkCategory & )

void

UpdateCategoryL

(

const CPosLandmarkCategory &

aCategory

)

[pure virtual]

Updates a landmark category in the database.

Pre-condition: 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.

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.

Parameter	Description
aCategory	The new landmark category data.