/*

* 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:  CPosLmNearestCriteria class

*

*/

#ifndef CPOSLMNEARESTCRITERIA_H

#define CPOSLMNEARESTCRITERIA_H

#include <e32base.h>

#include <lbsposition.h>

#include "EPos_CPosLmSearchCriteria.h"

/**

*  Criterion for finding the landmarks which are closest to a certain

*  coordinate, called "center coordinate".

*

*  When using @ref CPosLmNearestCriteria, the matches returned in the search

*  are sorted in ascending distance order if the client does not specify

*  other sort preferences.

*

*  By default, this search returns all landmarks in the database, except

*  those which have no coordinates. It is recommended to specify a maximum

*  distance to narrow down the search. This is done by @ref SetMaxDistance.

*

*  The client can specify if the coverage radius should be used.

*  If coverage radius is used, the distance to the landmark coverage area

*  border is used instead of the distance to the landmark coverage area

*  center. If the source coordinate is inside the landmark coverage area,

*  the distance is considered zero. By default, the coverage radius is not

*  used.

*

*  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 CPosLmNearestCriteria : public CPosLmSearchCriteria

    {

    public:

        /**

        * Two-phased constructor.

        *

        * Latitude and longitude must be set in the coordinate (not NaN).

        * Altitude is ignored.

        *

        * @param[in] aCoordinate The center coordinate of the landmark search.

        * @param[in] aUseCoverageRadius @p ETrue if coverage radius should be

        *   considered in the search.

        *

        * @panic "Landmarks Client"-EPosNaNCoordinate Latitude and/or longitude is NaN.

        */

        IMPORT_C static CPosLmNearestCriteria* NewLC(

            const TCoordinate& aCoordinate,

            TBool aUseCoverageRadius = EFalse

        );

        /**

        * Destructor.

        */

        virtual ~CPosLmNearestCriteria();

    public:

        /**

        * Returns the center coordinate of the search.

        *

        * @param[out] aCoordinate On return, contains the center coordinate.

        */

        IMPORT_C void GetCoordinate( TCoordinate& aCoordinate ) const;

        /**

        * Set the center coordinate of the search.

        *

        * Latitude and longitude must be set in the coordinate (not NaN).

        * Altitude is ignored.

        *

        * @param[in] aCoordinate The center coordinate of the landmarks search.

        *

        * @panic "Landmarks Client"-EPosNaNCoordinate Latitude and/or longitude is NaN.

        */

        IMPORT_C void SetCoordinate( const TCoordinate& aCoordinate );

        /**

        * Returns if coverage radius is considered in the search.

        *

        * @return @p ETrue if coverage radius is considered in the search.

        *   @p EFalse otherwise.

        */

        IMPORT_C TBool UseCoverageRadius() const;

        /**

        * Set if coverage radius should be considered in the search.

        *

        * @param aUseCoverageRadius @p ETrue if coverage radius should be

        *   considered in the search. @p EFalse otherwise.

        */

        IMPORT_C void SetUseCoverageRadius( TBool aUseCoverageRadius );

        /**

        * Returns whether the search should be limited to landmarks which are

        * closer than a maximum distance.

        *

        * By default the maximum distance is set to NaN which means that the

        * distance is unlimited.

        *

        * @return The maximum distance or NaN if the distance is unlimited.

        */

        IMPORT_C TReal32 MaxDistance() const;

        /**

        * Set a maximum distance for the search.

        *

        * Only landmarks, which are closer to the center coordinate than the

        * maximum distance are considered matches.

        *

        * @param aMaxDistance The maximum distance or NaN if the distance

        *   should be unlimited.

        */

        IMPORT_C void SetMaxDistance( TReal32 aMaxDistance );

    private:

        CPosLmNearestCriteria(TBool aUseCoverageRadius);

        void ConstructL(const TCoordinate& aCoordinate);

        // Prohibit copy constructor

        CPosLmNearestCriteria( const CPosLmNearestCriteria& );

        // Prohibit assigment operator

        CPosLmNearestCriteria& operator= ( const CPosLmNearestCriteria& );

    private:

        TCoordinate iCenterCoordinate;

        TBool       iUseCoverageRadius;

        TReal32     iMaxDistance;

    };

#endif      // CPOSLMNEARESTCRITERIA_H