1 epos_cposlmcategorymanager.h

     1 /*

     2 * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CPosLmCategoryManager class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLMCATEGORYMANAGER_H

    20 #define CPOSLMCATEGORYMANAGER_H

    21 

    22 #include <e32base.h>

    23 #include "epos_cposlandmarkdatabase.h"

    24 #include "epos_cposlandmarkcategory.h"

    25 #include "epos_cposlmitemiterator.h"

    26 #include "epos_cposlmoperation.h"

    27 

    28 /**

    29 *  Category management for a landmark database.

    30 *

    31 *  A landmark database can contain a number of categories which can be

    32 *  assigned to the landmarks in the database. A landmark can be associated

    33 *  with multiple categories, e.g. a landmark can be a "Restaurant" and a "Pub".

    34 *  Categories also enable filtered searches, e.g. a client could search for

    35 *  nearby restaurants.

    36 *

    37 *  This class contains functions for managing landmark categories. This includes

    38 *  reading, listing, creating and updating landmark categories.

    39 *

    40 *  @p NetworkServices capability is required for remote databases.

    41 *

    42 *  @lib eposlandmarks.lib

    43 *  @since S60 3.0

    44 */

    45 class CPosLmCategoryManager : public CBase

    46     {

    47     public:

    48 

    49         /**

    50         *  Specifies the sort preference for landmark categories.

    51         */

    52         enum TCategorySortPref

    53             {

    54             ECategorySortOrderNone = 0        /**<

    55                 Categories not sorted */,

    56             ECategorySortOrderNameAscending   /**<

    57                 Sorted ascending by category name. */,

    58             ECategorySortOrderNameDescending  /**<

    59                 Sorted descending by category name. */

    60             };

    61 

    62     public:

    63 

    64         /**

    65         * Two-phased constructor.

    66         *

    67         * The client takes ownership of the category manager.

    68         *

    69         * @param[in] aLandmarkDatabase The landmark database to manage categories in.

    70         * @returns A new instance of this class.

    71         */

    72         IMPORT_C static CPosLmCategoryManager* NewL(

    73             CPosLandmarkDatabase& aLandmarkDatabase

    74         );

    75 

    76         /**

    77         * Destructor.

    78         */

    79         IMPORT_C virtual ~CPosLmCategoryManager();

    80 

    81     public:

    82 

    83         /**

    84         * Reads a landmark category from the database.

    85         *

    86         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

    87         *

    88         * The client takes ownership of the returned category object.

    89         *

    90         * This function requires @p ReadUserData capability.

    91         *

    92         * @param aCategoryId The ID of the landmark category to read.

    93         * @returns The requested landmark category. The category object is put

    94         *   on the cleanup stack.

    95         *

    96         * @leave KErrNotFound The landmark category does not exist in the database.

    97         * @leave KErrPosLmNotInitialized Database is not yet initialized.

    98         */

    99         virtual CPosLandmarkCategory* ReadCategoryLC( TPosLmItemId aCategoryId ) = 0;

   100 

   101         /**

   102         * Returns an object for iterating the landmark categories in the

   103         * database.

   104         *

   105         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   106         *

   107         * The iterator object is reset, so that the first

   108         * @ref CPosLmItemIterator::NextL call will return the first landmark

   109         * category.

   110         *

   111         * The client takes ownership of the returned iterator object.

   112         *

   113         * This function requires @p ReadUserData capability.

   114         *

   115         * @param[in] aSortPref How to sort the categories. Default is no sorting.

   116         * @return The landmark iterator.

   117         *

   118         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   119         *

   120         * @panic "Landmarks Client"-EPosInvalidEnumValue

   121         *   Client specified invalid sort preference.

   122         */

   123         virtual CPosLmItemIterator* CategoryIteratorL(

   124             TCategorySortPref  aSortPref = ECategorySortOrderNone

   125         ) = 0;

   126 

   127         /**

   128         * Returns an object for iterating referenced landmark categories in

   129         * the database.

   130         *

   131         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   132         *

   133         * A category is referenced if there are landmarks in the database which

   134         * contains this category.

   135         *

   136         * The iterator object is reset, so that the first

   137         * @ref CPosLmItemIterator::NextL call will return the first landmark

   138         * category.

   139         *

   140         * The client takes ownership of the returned iterator object.

   141         *

   142         * This function requires @p ReadUserData capability.

   143         *

   144         * @param[in] aSortPref How to sort the categories. Default is no sorting.

   145         * @return The landmark iterator.

   146         *

   147         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   148         *

   149         * @panic "Landmarks Client"-EPosInvalidEnumValue

   150         *   Client specified invalid sort preference.

   151         */

   152         virtual CPosLmItemIterator* ReferencedCategoryIteratorL(

   153             TCategorySortPref  aSortPref = ECategorySortOrderNone

   154         ) = 0;

   155 

   156         /**

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

   158         *

   159         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   160         *

   161         * Note: Clients are not allowed to create global categories.

   162         *

   163         * This function requires @p ReadUserData and @p WriteUserData

   164         * capabilities.

   165         *

   166         * @post Category is added to the database and category object

   167         *   has database item set (CPosLandmarkCategory::CategoryId()).

   168         *

   169         * @param[in,out] aCategory The landmark category to add.

   170         * @return The ID of the new category.

   171         *

   172         * @leave KErrArgument 1) Input category does not have a name set or

   173         *   2) if a global category is set in the category object.

   174         * @leave KErrAlreadyExists A category with the same name

   175         *   already exists in the database.

   176         * @leave KErrAccessDenied The database is read-only.

   177         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   178         */

   179         virtual TPosLmItemId AddCategoryL(

   180             CPosLandmarkCategory& aCategory

   181         ) = 0;

   182 

   183         /**

   184         * Updates a landmark category in the database.

   185         *

   186         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   187         *

   188         * Note: Clients are not allowed to change the global category identifier in

   189         * the category object.

   190         *

   191         * This function requires @p ReadUserData and @p WriteUserData

   192         * capabilities.

   193         *

   194         * @param[in] aCategory The new landmark category data.

   195         *

   196         * @leave KErrArgument 1) Input category does not have a name set or

   197         *   2) if a global category identifier is changed in the category object.

   198         * @leave KErrAlreadyExists A category with the same name

   199         *   already exists in the database.

   200         * @leave KErrAccessDenied The database is read-only.

   201         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   202         */

   203         virtual void UpdateCategoryL(

   204             const CPosLandmarkCategory& aCategory

   205         ) = 0;

   206 

   207         /**

   208         * Removes a landmark category from the database.

   209         *

   210         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   211         *

   212         * If the landmark category does not exist in the database, nothing

   213         * happens.

   214         *

   215         * This call will also remove the category from all landmarks which

   216         * contained it.

   217         *

   218         * The function returns an operation object which can be run in either

   219         * synchronous or asynchronous mode. If it is run in asynchronous mode

   220         * the client can supervise the progress of the operation.

   221         *

   222         * If the @ref CPosLmOperation object is deleted before the operation

   223         * is complete, it is possible that the category has not been removed,

   224         * but some landmarks may no longer contain this category

   225         *

   226         * The client takes ownership of the returned operation object.

   227         *

   228         * While removing the category, this operation will acquire a

   229         * write-lock on the database.

   230         *

   231         * This function requires @p ReadUserData and @p WriteUserData

   232         * capabilities.

   233         *

   234         * @param aCategoryId The ID of the landmark category to delete.

   235         * @returns A handle to the operation.

   236         *

   237         * @leave KErrAccessDenied The database is read-only.

   238         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   239         */

   240         virtual CPosLmOperation* RemoveCategoryL( TPosLmItemId aCategoryId ) = 0;

   241 

   242         /**

   243         * Remove a set of landmark categories from the database.

   244         *

   245         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   246         *

   247         * If any of the landmark categories does not exist in the database, it

   248         * is ignored.

   249         *

   250         * This call will also remove the categories from all landmarks which

   251         * contained them.

   252         *

   253         * The function returns an operation object which can be run in either

   254         * synchronous or asynchronous mode. If it is run in asynchronous mode

   255         * the client can supervise the progress of the operation.

   256         *

   257         * If the @ref CPosLmOperation object is deleted before the operation

   258         * is complete, it is possible that only a subset of the landmark

   259         * categories have been deleted.

   260         *

   261         * The client takes ownership of the returned operation object.

   262         *

   263         * If the database is read only, the returned operation will fail with error

   264         * code @p KErrAccessDenied.

   265         *

   266         * This call will also remove the categories from all landmarks which

   267         * contained them.

   268         *

   269         * While removing the category, this operation will acquire a

   270         * write-lock on the database.

   271         *

   272         * This function requires @p ReadUserData and @p WriteUserData

   273         * capabilities.

   274         *

   275         * @param aCategoryIdArray The IDs of the landmark categories to delete.

   276         * @returns A handle to the operation.

   277         *

   278         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   279         */

   280         virtual CPosLmOperation* RemoveCategoriesL(

   281             const RArray<TPosLmItemId>& aCategoryIdArray

   282         ) = 0;

   283 

   284         /**

   285         * Adds a category to a set of landmarks.

   286         *

   287         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   288         *

   289         * If any of the specified landmarks does not exist, the category will

   290         * be added to the other landmarks. No error will be reported though.

   291         *

   292         * If the category is already contained in one of the landmarks, nothing

   293         * will be further added to that landmark.

   294         *

   295         * The function returns an operation object which can be run in either

   296         * synchronous or asynchronous mode. If it is run in asynchronous mode

   297         * the client can supervise the progress of the operation.

   298         *

   299         * If the @ref CPosLmOperation object is deleted before the operation

   300         * is complete, it is possible that the category has only been added

   301         * to a subset of the landmarks.

   302         *

   303         * The client takes ownership of the returned operation object.

   304         *

   305         * Note: There is no need to call

   306         * @p CPosLandmarkDatabase::UpdateLandmark for this change to take

   307         * place.

   308         *

   309         * If the database is read only, the returned operation will fail with error

   310         * code @p KErrAccessDenied.

   311         *

   312         * While adding the category to the landmarks, this operation will

   313         * acquire a write-lock on the database.

   314         *

   315         * This function requires @p ReadUserData and @p WriteUserData

   316         * capabilities.

   317         *

   318         * @param[in] aCategoryId The category to add to the set of landmarks.

   319         * @param[in] aLandmarkIdArray The landmarks to add the category to.

   320         * @returns A handle to the operation.

   321         *

   322         * @leave KErrNotFound The specified category does not exist in database.

   323         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   324         */

   325         virtual CPosLmOperation* AddCategoryToLandmarksL(

   326             TPosLmItemId aCategoryId,

   327             RArray<TPosLmItemId>& aLandmarkIdArray

   328         ) = 0;

   329 

   330         /**

   331         * Removes a category from a set of landmarks.

   332         *

   333         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   334         *

   335         * If any of the specified landmarks does not exist, the category will

   336         * be removed from the other landmarks. No error will be reported though.

   337         *

   338         * If the category is not found in one of the landmarks, nothing will

   339         * happen for that landmark.

   340         *

   341         * The function returns an operation object which can be run in either

   342         * synchronous or asynchronous mode. If it is run in asynchronous mode

   343         * the client can supervise the progress of the operation.

   344         *

   345         * If the @ref CPosLmOperation object is deleted before the operation

   346         * is complete, it is possible that the category has only been removed

   347         * from a subset of the landmarks.

   348         *

   349         * The client takes ownership of the returned operation object.

   350         *

   351         * If the database is read only, the returned operation will fail with error

   352         * code @p KErrAccessDenied.

   353         *

   354         * While removing the category from the landmarks, this operation will

   355         * acquire a write-lock on the database.

   356         *

   357         * This function requires @p ReadUserData and @p WriteUserData

   358         * capabilities.

   359         *

   360         * @param[in] aCategoryId The category to remove from the set of landmarks.

   361         * @param[in] aLandmarkIdArray The landmarks to remove the category from.

   362         * @returns A handle to the operation.

   363         *

   364         * @leave KErrNotFound The specified category does not exist in database.

   365         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   366         */

   367         virtual CPosLmOperation* RemoveCategoryFromLandmarksL(

   368             TPosLmItemId aCategoryId,

   369             RArray<TPosLmItemId>& aLandmarkIdArray

   370         ) = 0;

   371 

   372         /**

   373         * Gets a category by name.

   374         *

   375         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   376         *

   377         * The category name must be unique in the database, so there cannot be

   378         * multiple matches.

   379         *

   380         * This function only looks for an exact match.

   381         *

   382         * This function requires @p ReadUserData capability.

   383         *

   384         * @param[in] aCategoryName The name of the category to get.

   385         * @return @p KPosLmNullItemId if the category was not found, otherwise

   386         *   the ID of the category item in the database.

   387         *

   388         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   389         */

   390         virtual TPosLmItemId GetCategoryL(

   391             const TDesC& aCategoryName

   392         ) = 0;

   393 

   394         /**

   395         * Gets the ID of a global category.

   396         *

   397         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   398         *

   399         * This function requires @p ReadUserData capability.

   400         *

   401         * @param[in] aGlobalCategory The global category to look for.

   402         * @return @p KPosLmNullItemId if the category was not found, otherwise

   403         *   the ID of the category item in the database.

   404         *

   405         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   406         */

   407         virtual TPosLmItemId GetGlobalCategoryL(

   408             TPosLmGlobalCategory aGlobalCategory

   409         ) = 0;

   410 

   411         /**

   412         * Gets the predefined name of a global category.

   413         *

   414         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   415         *

   416         * @param[in] aGlobalCategory The global category to get a name for.

   417         * @return The name of the global category or @p NULL if the category

   418         *   is not recognized.

   419         *

   420         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   421         */

   422         virtual HBufC* GlobalCategoryNameL(

   423             TPosLmGlobalCategory aGlobalCategory

   424         ) = 0;

   425 

   426         /**

   427         * Resets the information for all global categories.

   428         *

   429         * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).

   430         *

   431         * Global categories usually has a default name and icon. The client

   432         * can change the name and icon. This function resets the name and

   433         * icon to the default ones.

   434         *

   435         * The function returns an operation object which can be run in either

   436         * synchronous or asynchronous mode. If it is run in asynchronous mode

   437         * the client can supervise the progress of the operation.

   438         *

   439         * If the @ref CPosLmOperation object is deleted before the operation

   440         * is complete, it is possible that that only a subset of the global

   441         * categories have been resetted.

   442         *

   443         * The client takes ownership of the returned operation object.

   444         *

   445         * While resetting, this operation will acquire a write-lock on the

   446         * database.

   447         *

   448         * This function requires @p ReadUserData and @p WriteUserData

   449         * capabilities.

   450         *

   451         * @returns A handle to the operation.

   452         *

   453         * @leave KErrAccessDenied The database is read-only.

   454         * @leave KErrPosLmNotInitialized Database is not yet initialized.

   455         */

   456         virtual CPosLmOperation* ResetGlobalCategoriesL() = 0;

   457 

   458     protected:

   459 

   460         // C++ constructor.

   461         IMPORT_C CPosLmCategoryManager();

   462 

   463     private:

   464 

   465         // Prohibit copy constructor

   466         CPosLmCategoryManager( const CPosLmCategoryManager& );

   467         // Prohibit assigment operator

   468         CPosLmCategoryManager& operator= ( const CPosLmCategoryManager& );

   469 

   470     private:

   471 

   472         // Implementation UID

   473         TUid iDtorIdKey;

   474 

   475     };

   476 

   477 #endif      // CPOSLMCATEGORYMANAGER_H

   478 

   479