/*

* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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