1 epos_cposlmareacriteria.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:  CPosLmAreaCriteria class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLMAREACRITERIA_H

    20 #define CPOSLMAREACRITERIA_H

    21 

    22 #include <e32base.h>

    23 #include "EPos_CPosLmSearchCriteria.h"

    24 

    25 /**

    26 *  Criterion for searching for landmarks which reside in a certain area.

    27 *

    28 *  The search area is defined by providing two latitude and two longitude

    29 *  values which specify the borders of the area. Note that this search

    30 *  does not consider landmark coverage radius, see

    31 *  @p CPosLandmark::GetCoverageRadius.

    32 *

    33 *  The search area is defined as a spherical rectangle, limited by two

    34 *  longitude borders (WestLongitude and EastLongitude) and two latitude

    35 *  borders (SouthLatitude and NorthLatitude).

    36 *

    37 *  It is required that -90 =< SouthLatitude =< NorthLatitude =< 90.

    38 *  WestLongitude must be in the interval [-180, 180), i.e. not including +180.

    39 *  EastLongitude must be in the interval [-180, 180], i.e. including +180.

    40 *  It is allowed that EastLongitude < WestLongitude. This defines an area

    41 *  which crosses the 180 meridian. The area definition is inclusive, i.e.

    42 *  landmarks which lie on the border of the area will be considered as matches.

    43 *  If WestLongitude = EastLongitude and NorthLatitude = SouthLatitude then

    44 *  only landmarks which match the longitude and latitude respectively, are

    45 *  considered to be matches. If WestLongitude = -180 and EastLongitude = +180,

    46 *  all longitudes are included in the search.

    47 *

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

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

    50 *  will fail with error code @p KErrArgument.

    51 *

    52 *  @lib eposlmsearchlib.lib

    53 *  @since S60 3.0

    54 */

    55 class CPosLmAreaCriteria : public CPosLmSearchCriteria

    56     {

    57     public:

    58 

    59         /**

    60         * Two-phased constructor.

    61         *

    62         * The input parameters specify the area to search as described

    63         * in the class description.

    64         *

    65         * If one of the parameters is out of range, this function fails with

    66         * error code @p KErrArgument. The correct ranges are:

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

    68         *   -# -180 <= aWestLongitude < 180

    69         *   -# -180 <= aEastLongitude <= 180

    70         *

    71         * @param[in] aSouthLatitude The southern latitude border of the search area.

    72         * @param[in] aNorthLatitude The northern latitude border of the search area.

    73         * @param[in] aWestLongitude The western longitude border of the search area.

    74         * @param[in] aEastLongitude The eastern longitude border of the search area.

    75         * @returns A new instance of this class.

    76         */

    77         IMPORT_C static CPosLmAreaCriteria* NewLC(

    78             const TReal64& aSouthLatitude,

    79             const TReal64& aNorthLatitude,

    80             const TReal64& aWestLongitude,

    81             const TReal64& aEastLongitude

    82         );

    83 

    84         /**

    85         * Destructor.

    86         */

    87         virtual ~CPosLmAreaCriteria();

    88 

    89     public:

    90 

    91         /**

    92         * Returns the search area.

    93         *

    94         * @param[out] aSouthLatitude The southern latitude border of the search area.

    95         * @param[out] aNorthLatitude The northern latitude border of the search area.

    96         * @param[out] aWestLongitude The western longitude border of the search area.

    97         * @param[out] aEastLongitude The eastern longitude border of the search area.

    98         */

    99         IMPORT_C void GetSearchArea(

   100             TReal64& aSouthLatitude,

   101             TReal64& aNorthLatitude,

   102             TReal64& aWestLongitude,

   103             TReal64& aEastLongitude

   104         ) const;

   105 

   106         /**

   107         * Define the search area.

   108         *

   109         * The input parameters specify the area to search as described in the

   110         * class description.

   111         *

   112         * If one of the parameters is out of range, this function fails with

   113         * error code @p KErrArgument. The correct ranges are:

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

   115         *   -# -180 <= aWestLongitude < 180

   116         *   -# -180 <= aEastLongitude <= 180

   117         *

   118         * @param[in] aSouthLatitude The southern latitude border of the search area.

   119         * @param[in] aNorthLatitude The northern latitude border of the search area.

   120         * @param[in] aWestLongitude The western longitude border of the search area.

   121         * @param[in] aEastLongitude The eastern longitude border of the search area.

   122         * @returns @p KErrNone if successful, @p KErrArgument if the input

   123         *   parameters are invalid, otherwise a system wide error code.

   124         */

   125         IMPORT_C TInt SetSearchArea(

   126             const TReal64& aSouthLatitude,

   127             const TReal64& aNorthLatitude,

   128             const TReal64& aWestLongitude,

   129             const TReal64& aEastLongitude

   130         );

   131 

   132     private:

   133 

   134         // C++ constructor

   135         CPosLmAreaCriteria();

   136 

   137         void ConstructL(

   138             const TReal64&  aSouthLatitude,

   139             const TReal64&  aNorthLatitude,

   140             const TReal64&  aWestLongitude,

   141             const TReal64&  aEastLongitude

   142         );

   143 

   144         // Prohibit copy constructor

   145         CPosLmAreaCriteria( const CPosLmAreaCriteria& );

   146         // Prohibit assigment operator

   147         CPosLmAreaCriteria& operator= ( const CPosLmAreaCriteria& );

   148 

   149     private:

   150 

   151         TReal64 iSouthLatitude;

   152         TReal64 iNorthLatitude;

   153         TReal64 iWestLongitude;

   154         TReal64 iEastLongitude;

   155 

   156     };

   157 

   158 #endif      // CPOSLMAREACRITERIA_H

   159 

   160