1 epos_cposlmnearestcriteria.h

     1 /*

     2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CPosLmNearestCriteria class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLMNEARESTCRITERIA_H

    20 #define CPOSLMNEARESTCRITERIA_H

    21 

    22 #include <e32base.h>

    23 #include <LbsPosition.h>

    24 #include "EPos_CPosLmSearchCriteria.h"

    25 

    26 

    27 /**

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

    29 *  coordinate, called "center coordinate".

    30 *

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

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

    33 *  other sort preferences.

    34 *

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

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

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

    38 *

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

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

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

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

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

    44 *  used.

    45 *

    46 *  This criterion is only valid when searching for landmarks, i.e. if it

    47 *  is passed to @p CPosLandmarkSearch::StartCategorySearchL, the function

    48 *  will fail with error code @p KErrArgument.

    49 *

    50 *  @lib eposlmsearchlib.lib

    51 *  @since S60 3.0

    52 */

    53 class CPosLmNearestCriteria : public CPosLmSearchCriteria

    54     {

    55     public:

    56 

    57         /**

    58         * Two-phased constructor.

    59         *

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

    61         * Altitude is ignored.

    62         *

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

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

    65         *   considered in the search.

    66         *

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

    68         */

    69         IMPORT_C static CPosLmNearestCriteria* NewLC(

    70             const TCoordinate& aCoordinate,

    71             TBool aUseCoverageRadius = EFalse

    72         );

    73 

    74         /**

    75         * Destructor.

    76         */

    77         virtual ~CPosLmNearestCriteria();

    78 

    79     public:

    80 

    81         /**

    82         * Returns the center coordinate of the search.

    83         *

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

    85         */

    86         IMPORT_C void GetCoordinate( TCoordinate& aCoordinate ) const;

    87 

    88         /**

    89         * Set the center coordinate of the search.

    90         *

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

    92         * Altitude is ignored.

    93         *

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

    95         *

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

    97         */

    98         IMPORT_C void SetCoordinate( const TCoordinate& aCoordinate );

    99 

   100         /**

   101         * Returns if coverage radius is considered in the search.

   102         *

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

   104         *   @p EFalse otherwise.

   105         */

   106         IMPORT_C TBool UseCoverageRadius() const;

   107 

   108         /**

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

   110         *

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

   112         *   considered in the search. @p EFalse otherwise.

   113         */

   114         IMPORT_C void SetUseCoverageRadius( TBool aUseCoverageRadius );

   115 

   116         /**

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

   118         * closer than a maximum distance.

   119         *

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

   121         * distance is unlimited.

   122         *

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

   124         */

   125         IMPORT_C TReal32 MaxDistance() const;

   126 

   127         /**

   128         * Set a maximum distance for the search.

   129         *

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

   131         * maximum distance are considered matches.

   132         *

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

   134         *   should be unlimited.

   135         */

   136         IMPORT_C void SetMaxDistance( TReal32 aMaxDistance );

   137 

   138     private:

   139 

   140         CPosLmNearestCriteria(TBool aUseCoverageRadius);

   141 

   142         void ConstructL(const TCoordinate& aCoordinate);

   143 

   144         // Prohibit copy constructor

   145         CPosLmNearestCriteria( const CPosLmNearestCriteria& );

   146         // Prohibit assigment operator

   147         CPosLmNearestCriteria& operator= ( const CPosLmNearestCriteria& );

   148 

   149     private:

   150 

   151         TCoordinate iCenterCoordinate;

   152         TBool       iUseCoverageRadius;

   153         TReal32     iMaxDistance;

   154 

   155     };

   156 

   157 #endif      // CPOSLMNEARESTCRITERIA_H

   158 

   159