Symbian^3 Application 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

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]

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.