1 epos_cposlmcategorycriteria.h

     1 /*

     2 * Copyright (c) 2005-2006 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:  CPosLmCategoryCriteria class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLMCATEGORYCRITERIA_H

    20 #define CPOSLMCATEGORYCRITERIA_H

    21 

    22 #include <e32base.h>

    23 #include <EPos_Landmarks.h>

    24 

    25 #include "EPos_CPosLmSearchCriteria.h"

    26 

    27 /**

    28 *  Criterion used for searching for landmarks which belong to a certain

    29 *  category.

    30 *

    31 *  A category has an ID in the database and it has also a unique name. There

    32 *  are also some global categories which are known by all databases. It is

    33 *  possible to specify either a local category in a specific landmark

    34 *  database, a global category or the name of the category. If one is set,

    35 *  the others are reset and not used.

    36 *

    37 *  It is also possible to search for uncategorized landmarks, i.e. landmarks

    38 *  which do not contain any categories. If neither item ID, global ID nor name

    39 *  are set, then @ref CPosLandmarkSearch::StartLandmarkSearchL will search for

    40 *  uncategorized landmarks.

    41 *

    42 *  This criterion is only valid when searching for landmarks, i.e. if it

    43 *  is passed to @p CPosLandmarkSearch::StartCategorySearchL, the function

    44 *  will fail with error code @p KErrArgument.

    45 *

    46 *  @lib eposlmsearchlib.lib

    47 *  @since S60 3.0

    48 */

    49 class CPosLmCategoryCriteria : public CPosLmSearchCriteria

    50     {

    51     public:

    52 

    53         /**

    54         * Two-phased constructor.

    55         *

    56         * @returns A new instance of this class.

    57         */

    58         IMPORT_C static CPosLmCategoryCriteria* NewLC();

    59 

    60         /**

    61         * Destructor.

    62         */

    63         virtual ~CPosLmCategoryCriteria();

    64 

    65     public:

    66 

    67         /**

    68         * Returns the item ID of the category which should be used as

    69         * landmark search criterion.

    70         *

    71         * @return The item ID of the category or @p KPosLmNullItemId

    72         *   if not set.

    73         */

    74         IMPORT_C TPosLmItemId CategoryItemId() const;

    75 

    76         /**

    77         * Returns the global category which should be used as landmark search

    78         * criterion.

    79         *

    80         * @return The global category or @p KPosLmNullGlobalCategory if not

    81         *   set.

    82         */

    83         IMPORT_C TPosLmGlobalCategory GlobalCategory() const;

    84 

    85         /**

    86         * Returns the name of the category which should be used as landmark

    87         * search criterion.

    88         *

    89         * @return The category name or empty descriptor if not

    90         *   set.

    91         */

    92         IMPORT_C TPtrC CategoryName() const;

    93 

    94         /**

    95         * Sets the item ID of the category which should be used as landmark

    96         * search criterion.

    97         *

    98         * Passing @p KPosLmNullItemId means uncategorized landmarks search.

    99         *

   100         * @param aItemId The item ID of the category.

   101         */

   102         IMPORT_C void SetCategoryItemId( TPosLmItemId aItemId );

   103 

   104         /**

   105         * Sets the global category which should be used as landmark search

   106         * criterion.

   107         *

   108         * Passing @p KPosLmNullGlobalCategory means uncategorized landmarks

   109         * search.

   110         *

   111         * @param aGlobalCategory The global category.

   112         */

   113         IMPORT_C void SetGlobalCategory( TPosLmGlobalCategory aGlobalCategory );

   114 

   115         /**

   116         * Sets the name of the category which should be used as landmark

   117         * search criterion.

   118         *

   119         * The exact category name must be specified. Wild-card characters are

   120         * not used as such, they will be considered as ordinary characters.

   121         * It is possible to use @ref CPosLmCatNameCriteria to

   122         * list categories which match a category name pattern containing

   123         * wild-card characters.

   124         *

   125         * The matching is case sensitive.

   126         *

   127         * An empty descriptor means uncategorized landmarks search.

   128         *

   129         * @param aCategoryName The category name.

   130         *

   131         * @leave KErrArgument The category name is longer than @p KPosLmMaxCategoryNameLength.

   132         */

   133         IMPORT_C void SetCategoryNameL( const TDesC&  aCategoryName );

   134 

   135     private:

   136 

   137         // C++ constructor

   138         CPosLmCategoryCriteria();

   139 

   140         void ConstructL();

   141 

   142         // Prohibit copy constructor

   143         CPosLmCategoryCriteria( const CPosLmCategoryCriteria& );

   144         // Prohibit assigment operator

   145         CPosLmCategoryCriteria& operator= ( const CPosLmCategoryCriteria& );

   146 

   147     private:

   148 

   149         TPosLmItemId            iItemId;

   150         TPosLmGlobalCategory    iGlobalCategory;

   151         HBufC*                  iCategoryName;

   152 

   153     };

   154 

   155 #endif      // CPOSLMCATEGORYCRITERIA_H

   156 

   157