/*
* 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