/*

* Copyright (c) 2008 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:  Defines a landmark search criteria

 *

*/

#ifndef TLAPISEARCHCRITERIA_H

#define TLAPISEARCHCRITERIA_H

// EXTERNAL INCLUDES

#include    <e32std.h>

/**

 * Defines a landmark search criteria

 *

 * The class is only a container class for the data. It does not own

 * any of the search attributes but delegates them to the search

 * provider

 *

 * @lib N/A

 * @since S60 3.2

 */

NONSHARABLE_CLASS(TLAPISearchCriteria)

{

public: // Constructors

    /**

     * Constructs a default search criteria. The default

     * will return all available items

     */

    inline TLAPISearchCriteria();

public: // New functions

    /**

     * Sets the attributes of a search text. The attributes

     * indicate that which text fields are searched from

     * each landmark to find the matching items.

     *

     * Currently, the only supported fields are name and description

     *

     * @param aTextAttributes The attributes of a search text

     */

    inline void SetTextAttributes(TUint aTextAttributes);

    /**

     * Sets the search string.

     *

     * The text must be a non-empty descriptor. Otherwise the search

     * will fail with 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 criteria if specified text is found anywhere

     * in selected attributes set using SetTextAttributes

     *

     * @param aText The text to search for.

     */

    inline void SetText(const TDesC* aText);

    /**

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

     * search criteria. The whole category name must be specified. Category

     * searching is not supported using wild cards and will be considered

     * as ordinary characters

     *

     * The matching is case sensitive. An empty descriptor means uncategorized

     * landmarks search.

     *

     * @param aCategoryName The category name.

     */

    inline void SetCategoryName(const TDesC* aCategoryName);

    /**

     * Define the search area from which the landmarks are searched

     *

     * If the parameters are out of range. The search will faile with KErrArgument

     * The correct ranges are:

     *   -# -90 =< aSouthLatitude =< aNorthLatitude =< 90

     *   -# -180 <= aWestLongitude < 180

     *   -# -180 <= aEastLongitude <= 180

     *

     * @param aSouthLatitude The southern latitude border of the search area.

     * @param aNorthLatitude The northern latitude border of the search area.

     * @param aWestLongitude The western longitude border of the search area.

     * @param aEastLongitude The eastern longitude border of the search area.

     */

    inline void SetArea(const TReal64& aSouthLatitude,

                        const TReal64& aNorthLatitude, const TReal64& aWestLongitude,

                        const TReal64& aEastLongitude);

    /**

     * Returns the search attributes of the search text

     */

    inline TUint TextAttributes() const;

    /**

     * Returns the search text. NULL if not set

     */

    inline const TDesC* Text() const;

    /**

     * Returns the search category name. NULL if not set

     */

    inline const TDesC* CategoryName() const;

    /**

     * Checks if the coordinates are set using SetArea

     */

    inline TBool HasValidCoordinates() const;

    /**

     * Gets the search area. The area may not have been set yet and

     * should be checked with HasValidCoordinates()

     */

    inline void GetArea(TReal64& aSouthLatitude, TReal64& aNorthLatitude,

                        TReal64& aWestLongitude, TReal64& aEastLongitude) const;

private: // Data

    // Search text. Not owned

    const TDesC* iText;

    // Search text attributes

    TUint iTextAttributes;

    // Searched category. Not owned

    const TDesC* iCategoryName;

    // Marks a search area

    TReal64 iSouthLatitude;

    TReal64 iNorthLatitude;

    TReal64 iWestLongitude;

    TReal64 iEastLongitude;

}

;

// Inline functions

#include    "tlapisearchcriteria.inl"

#endif // TLAPISEARCHCRITERIA_H

// End of file