/*
* 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:  CPosLmTextCriteria class
*
*/


#ifndef CPOSLMTEXTCRITERIA_H
#define CPOSLMTEXTCRITERIA_H

#include <e32base.h>
#include <lbsfields.h>
#include <EPos_CPosLandmark.h>
#include "EPos_CPosLmSearchCriteria.h"

const TInt KPosLmMaxSearchStringLength = 255;

/**
*  Criterion for searching for landmarks which contain a certain text.
*
*  The search is defined by providing a text to search for and the position
*  fields and text attributes to search.
*
*  If no attributes are specified for the search, all text attributes in the
*  landmarks are searched. If no position fields are specified, then all
*  fields are searched.
*
*  If this criterion is passed to
*  @ref CPosLandmarkSearch::StartLandmarkSearchL, only landmarks which contain
*  the specified text are returned.
*
*  Wild-card characters are supported.
*
*  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 CPosLmTextCriteria : public CPosLmSearchCriteria
    {
    public:

        /**
        * Two-phased constructor.
        * @returns A new instance of this class.
        */
        IMPORT_C static CPosLmTextCriteria* NewLC();

        /**
        * Destructor.
        */
        virtual ~CPosLmTextCriteria();

    public:

        /**
        * Retrieves the text to search for.
        *
        * @return The text to search for.
        */
        IMPORT_C TPtrC Text() const;

        /**
        * Sets the search string.
        *
        * A non-empty text string must be set, otherwise
        * @ref CPosLandmarkSearch::StartLandmarkSearchL will leave with error
        * code @p KErrArgument.
        *
        * The search is case insensitive.
        *
        * Wild-card characters "?" and "*" are supported in the search string.
        * "?" matches a single occurrence of any character and "*" matches
        * zero or more consecutive occurrences of any characters.
        *
        * A landmark matches the criterion if specified text is found anywhere
        * in selected attributes or position fields.
        *
        * @param aText The text to search for.
        *
        * @leave KErrArgument The search string is longer than @p KPosLmMaxSearchStringLength.
        */
        IMPORT_C void SetTextL( const TDesC& aText );

        /**
        * Retrieves the landmark attributes which should be searched.
        *
        * This function returns a bitmap of landmark attributes. The landmark
        * attributes are defined by @p CPosLandmark::_TAttributes. It is only
        * possible to search the @p ELandmarkName and @p EDescription
        * attributes.
        *
        * @return A bitmap indicating which landmark attributes should be
        *   searched.
        */
        IMPORT_C CPosLandmark::TAttributes AttributesToSearch() const;

        /**
        * Sets which landmark attributes to search.
        *
        * The client passes a bitmap of the landmark attributes to search. It
        * is only possible to search the @p ELandmarkName and @p EDescription
        * attributes.
        *
        * @param aAttributes A bitmap indicating which landmark attributes
        *   should be searched.
        *
        * @panic "Landmarks Client"-EPosInvalidLandmarkAttribute
        *   Unsupported attribute is passed.
        */
        IMPORT_C void SetAttributesToSearch(
            CPosLandmark::TAttributes aAttributes
        );

        /**
        * Retrieves a list of the position fields to search.
        *
        * @param[out] aFieldArray On return, contains a list of the position fields
        *   which are used in a search. If no position fields have been set,
        *   the array is empty. Position fields are identified by values defined
        *   in @p TPositionFieldId.
        */
        IMPORT_C void GetPositionFieldsToSearchL(
            RArray<TUint>& aFieldArray
        ) const;

        /**
        * Sets the position fields to search.
        *
        * Any previously set position fields are cleared by this call.
        *
        * @param[in] aFieldArray A list of the position fields to search.
        *   Position fields are identified by values defined in
        *   @p TPositionFieldId.
        */
        IMPORT_C void SetPositionFieldsToSearchL(
            const RArray<TUint>&  aFieldArray
        );

        /**
        * Clears the position fields list used in a search.
        */
        IMPORT_C void ClearPositionFieldsToSearch();

    private:

        CPosLmTextCriteria();

        void ConstructL();

        // Prohibit copy constructor
        CPosLmTextCriteria( const CPosLmTextCriteria& );
        // Prohibit assigment operator
        CPosLmTextCriteria& operator= ( const CPosLmTextCriteria& );

    private:

        HBufC*                      iText;
        RArray<TUint>               iPositionFieldArray;
        CPosLandmark::TAttributes   iAttributes;

    };

#endif      // CPOSLMTEXTCRITERIA_H