/*

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

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  CPosLmCategoryCriteria class

 *

 */

 #ifndef CPOSLMCATEGORYCRITERIA_H

 #define CPOSLMCATEGORYCRITERIA_H

 #include <e32base.h>

 #include <EPos_Landmarks.h>

 #include "EPos_CPosLmSearchCriteria.h"

 /**

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

 *  category.

 *

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

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

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

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

 *  the others are reset and not used.

 *

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

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

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

 *  uncategorized landmarks.

 *

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

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

 *  will fail with error code @p KErrArgument.

 *

 *  @lib eposlmsearchlib.lib

 *  @since S60 3.0

 */

 class CPosLmCategoryCriteria : public CPosLmSearchCriteria

     {

     public:

         /**

         * Two-phased constructor.

         *

         * @returns A new instance of this class.

         */

         IMPORT_C static CPosLmCategoryCriteria* NewLC();

         /**

         * Destructor.

         */

         virtual ~CPosLmCategoryCriteria();

     public:

         /**

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

         * landmark search criterion.

         *

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

         *   if not set.

         */

         IMPORT_C TPosLmItemId CategoryItemId() const;

         /**

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

         * criterion.

         *

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

         *   set.

         */

         IMPORT_C TPosLmGlobalCategory GlobalCategory() const;

         /**

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

         * search criterion.

         *

         * @return The category name or empty descriptor if not

         *   set.

         */

         IMPORT_C TPtrC CategoryName() const;

         /**

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

         * search criterion.

         *

         * Passing @p KPosLmNullItemId means uncategorized landmarks search.

         *

         * @param aItemId The item ID of the category.

         */

         IMPORT_C void SetCategoryItemId( TPosLmItemId aItemId );

         /**

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

         * criterion.

         *

         * Passing @p KPosLmNullGlobalCategory means uncategorized landmarks

         * search.

         *

         * @param aGlobalCategory The global category.

         */

         IMPORT_C void SetGlobalCategory( TPosLmGlobalCategory aGlobalCategory );

         /**

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

         * search criterion.

         *

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

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

         * It is possible to use @ref CPosLmCatNameCriteria to

         * list categories which match a category name pattern containing

         * wild-card characters.

         *

         * The matching is case sensitive.

         *

         * An empty descriptor means uncategorized landmarks search.

         *

         * @param aCategoryName The category name.

         *

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

         */

         IMPORT_C void SetCategoryNameL( const TDesC&  aCategoryName );

     private:

         // C++ constructor

         CPosLmCategoryCriteria();

         void ConstructL();

         // Prohibit copy constructor

         CPosLmCategoryCriteria( const CPosLmCategoryCriteria& );

         // Prohibit assigment operator

         CPosLmCategoryCriteria& operator= ( const CPosLmCategoryCriteria& );

     private:

         TPosLmItemId            iItemId;

         TPosLmGlobalCategory    iGlobalCategory;

         HBufC*                  iCategoryName;

     };

 #endif      // CPOSLMCATEGORYCRITERIA_H