Collapse all Symbian^3 Product Developer Library

CPosLmCategoryManager Class Reference

class CPosLmCategoryManager : public CBase

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.

eposlandmarks.lib

Since: S60 3.0

Inherits from

CPosLmCategoryManager
- CBase

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

Protected Member Functions
	CPosLmCategoryManager()

Private Member Functions
	CPosLmCategoryManager(const CPosLmCategoryManager &)
CPosLmCategoryManager &	operator=(const 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()

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

Private Attributes
TUid	iDtorIdKey

Constructor & Destructor Documentation

CPosLmCategoryManager()

IMPORT_C

CPosLmCategoryManager

(

)

[protected]

CPosLmCategoryManager(const CPosLmCategoryManager &)

CPosLmCategoryManager

(

const CPosLmCategoryManager &

)

[private]

Parameters

const CPosLmCategoryManager &

~CPosLmCategoryManager()

IMPORT_C

~CPosLmCategoryManager

(

)

[virtual]

Destructor.

Member Functions 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.

Parameters

CPosLandmarkCategory & aCategory

The landmark category to add.

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.

Parameters

TPosLmItemId aCategoryId	The category to add to the set of landmarks.
RArray< TPosLmItemId > & aLandmarkIdArray	The landmarks to add the category to.

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.

Parameters

TCategorySortPref aSortPref = ECategorySortOrderNone

How to sort the categories. Default is no sorting.

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.

Parameters

const TDesC & aCategoryName

The name of the category to get.

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.

Parameters

TPosLmGlobalCategory aGlobalCategory

The global category to look for.

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.

Parameters

TPosLmGlobalCategory aGlobalCategory

The global category to get a name for.

NewL(CPosLandmarkDatabase &)

IMPORT_C CPosLmCategoryManager *

NewL

(

CPosLandmarkDatabase &

aLandmarkDatabase

)

[static]

Two-phased constructor.

The client takes ownership of the category manager.

Parameters

CPosLandmarkDatabase & aLandmarkDatabase

The landmark database to manage categories in.

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.

Parameters

TPosLmItemId aCategoryId

The ID of the landmark category to read.

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.

Parameters

TCategorySortPref aSortPref = ECategorySortOrderNone

How to sort the categories. Default is no sorting.

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.

Parameters

const RArray< TPosLmItemId > & aCategoryIdArray

The IDs of the landmark categories to delete.

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.

Parameters

TPosLmItemId aCategoryId	The category to remove from the set of landmarks.
RArray< TPosLmItemId > & aLandmarkIdArray	The landmarks to remove the category from.

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.

Parameters

TPosLmItemId aCategoryId

The ID of the landmark category to delete.

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.

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.

Parameters

const CPosLandmarkCategory & aCategory

The new landmark category data.

operator=(const CPosLmCategoryManager &)

CPosLmCategoryManager &

operator=

(

const CPosLmCategoryManager &

)

[private]

Parameters

const CPosLmCategoryManager &

Member Enumerations Documentation

Enum TCategorySortPref

Specifies the sort preference for landmark categories.

Enumerators

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

Member Data Documentation

TUid iDtorIdKey

TUid

iDtorIdKey

[private]