CPosLmCategoryManager Class Reference

#include <mw/EPos_CPosLmCategoryManager.h>

Link against: eposlandmarks.lib

class CPosLmCategoryManager : public CBase

Inherits from

  • CPosLmCategoryManager

    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.

    EnumeratorValueDescription
    ECategorySortOrderNone0

    Categories not sorted

    ECategorySortOrderNameAscending

    Sorted ascending by category name.

    ECategorySortOrderNameDescending

    Sorted descending by category name.

    Constructor & Destructor Documentation

    CPosLmCategoryManager ( )

    IMPORT_CCPosLmCategoryManager()[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.
    ParameterDescription
    aCategoryThe landmark category to add.

    Returns: The ID of the new category.

    AddCategoryToLandmarksL ( TPosLmItemId, RArray< TPosLmItemId > & )

    CPosLmOperation *AddCategoryToLandmarksL(TPosLmItemIdaCategoryId,
    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.
    ParameterDescription
    aCategoryIdThe category to add to the set of landmarks.
    aLandmarkIdArrayThe landmarks to add the category to.

    Returns: A handle to the operation.

    CategoryIteratorL ( TCategorySortPref )

    CPosLmItemIterator *CategoryIteratorL(TCategorySortPrefaSortPref = 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.
    ParameterDescription
    aSortPrefHow 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.
    ParameterDescription
    aCategoryNameThe 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(TPosLmGlobalCategoryaGlobalCategory)[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.
    ParameterDescription
    aGlobalCategoryThe 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(TPosLmGlobalCategoryaGlobalCategory)[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.
    ParameterDescription
    aGlobalCategoryThe 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.

    ParameterDescription
    aLandmarkDatabaseThe landmark database to manage categories in.

    Returns: A new instance of this class.

    ReadCategoryLC ( TPosLmItemId )

    CPosLandmarkCategory *ReadCategoryLC(TPosLmItemIdaCategoryId)[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.
    ParameterDescription
    aCategoryIdThe 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(TCategorySortPrefaSortPref = 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.
    ParameterDescription
    aSortPrefHow 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.
    ParameterDescription
    aCategoryIdArrayThe IDs of the landmark categories to delete.

    Returns: A handle to the operation.

    RemoveCategoryFromLandmarksL ( TPosLmItemId, RArray< TPosLmItemId > & )

    CPosLmOperation *RemoveCategoryFromLandmarksL(TPosLmItemIdaCategoryId,
    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.
    ParameterDescription
    aCategoryIdThe category to remove from the set of landmarks.
    aLandmarkIdArrayThe landmarks to remove the category from.

    Returns: A handle to the operation.

    RemoveCategoryL ( TPosLmItemId )

    CPosLmOperation *RemoveCategoryL(TPosLmItemIdaCategoryId)[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.
    ParameterDescription
    aCategoryIdThe 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 & )

    voidUpdateCategoryL(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.
    ParameterDescription
    aCategoryThe new landmark category data.