williamr@2: /*
williamr@2: * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  CPosLmAreaCriteria class
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef CPOSLMAREACRITERIA_H
williamr@2: #define CPOSLMAREACRITERIA_H
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include "EPos_CPosLmSearchCriteria.h"
williamr@2: 
williamr@2: /**
williamr@2: *  Criterion for searching for landmarks which reside in a certain area.
williamr@2: *
williamr@2: *  The search area is defined by providing two latitude and two longitude
williamr@2: *  values which specify the borders of the area. Note that this search
williamr@2: *  does not consider landmark coverage radius, see
williamr@2: *  @p CPosLandmark::GetCoverageRadius.
williamr@2: *
williamr@2: *  The search area is defined as a spherical rectangle, limited by two
williamr@2: *  longitude borders (WestLongitude and EastLongitude) and two latitude
williamr@2: *  borders (SouthLatitude and NorthLatitude).
williamr@2: *
williamr@2: *  It is required that -90 =< SouthLatitude =< NorthLatitude =< 90.
williamr@2: *  WestLongitude must be in the interval [-180, 180), i.e. not including +180.
williamr@2: *  EastLongitude must be in the interval [-180, 180], i.e. including +180.
williamr@2: *  It is allowed that EastLongitude < WestLongitude. This defines an area
williamr@2: *  which crosses the 180 meridian. The area definition is inclusive, i.e.
williamr@2: *  landmarks which lie on the border of the area will be considered as matches.
williamr@2: *  If WestLongitude = EastLongitude and NorthLatitude = SouthLatitude then
williamr@2: *  only landmarks which match the longitude and latitude respectively, are
williamr@2: *  considered to be matches. If WestLongitude = -180 and EastLongitude = +180,
williamr@2: *  all longitudes are included in the search.
williamr@2: *
williamr@2: *  This criterion is only valid when searching for landmarks, i.e. if it
williamr@2: *  is passed to @p CPosLandmarkSearch::StartCategorySearchL, the function
williamr@2: *  will fail with error code @p KErrArgument.
williamr@2: *
williamr@2: *  @lib eposlmsearchlib.lib
williamr@2: *  @since S60 3.0
williamr@2: */
williamr@2: class CPosLmAreaCriteria : public CPosLmSearchCriteria
williamr@2:     {
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Two-phased constructor.
williamr@2:         *
williamr@2:         * The input parameters specify the area to search as described
williamr@2:         * in the class description.
williamr@2:         *
williamr@2:         * If one of the parameters is out of range, this function fails with
williamr@2:         * error code @p KErrArgument. The correct ranges are:
williamr@2:         *   -# -90 =< aSouthLatitude =< aNorthLatitude =< 90
williamr@2:         *   -# -180 <= aWestLongitude < 180
williamr@2:         *   -# -180 <= aEastLongitude <= 180
williamr@2:         *
williamr@2:         * @param[in] aSouthLatitude The southern latitude border of the search area.
williamr@2:         * @param[in] aNorthLatitude The northern latitude border of the search area.
williamr@2:         * @param[in] aWestLongitude The western longitude border of the search area.
williamr@2:         * @param[in] aEastLongitude The eastern longitude border of the search area.
williamr@2:         * @returns A new instance of this class.
williamr@2:         */
williamr@2:         IMPORT_C static CPosLmAreaCriteria* NewLC(
williamr@2:             const TReal64& aSouthLatitude,
williamr@2:             const TReal64& aNorthLatitude,
williamr@2:             const TReal64& aWestLongitude,
williamr@2:             const TReal64& aEastLongitude
williamr@2:         );
williamr@2: 
williamr@2:         /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         virtual ~CPosLmAreaCriteria();
williamr@2: 
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns the search area.
williamr@2:         *
williamr@2:         * @param[out] aSouthLatitude The southern latitude border of the search area.
williamr@2:         * @param[out] aNorthLatitude The northern latitude border of the search area.
williamr@2:         * @param[out] aWestLongitude The western longitude border of the search area.
williamr@2:         * @param[out] aEastLongitude The eastern longitude border of the search area.
williamr@2:         */
williamr@2:         IMPORT_C void GetSearchArea(
williamr@2:             TReal64& aSouthLatitude,
williamr@2:             TReal64& aNorthLatitude,
williamr@2:             TReal64& aWestLongitude,
williamr@2:             TReal64& aEastLongitude
williamr@2:         ) const;
williamr@2: 
williamr@2:         /**
williamr@2:         * Define the search area.
williamr@2:         *
williamr@2:         * The input parameters specify the area to search as described in the
williamr@2:         * class description.
williamr@2:         *
williamr@2:         * If one of the parameters is out of range, this function fails with
williamr@2:         * error code @p KErrArgument. The correct ranges are:
williamr@2:         *   -# -90 =< aSouthLatitude =< aNorthLatitude =< 90
williamr@2:         *   -# -180 <= aWestLongitude < 180
williamr@2:         *   -# -180 <= aEastLongitude <= 180
williamr@2:         *
williamr@2:         * @param[in] aSouthLatitude The southern latitude border of the search area.
williamr@2:         * @param[in] aNorthLatitude The northern latitude border of the search area.
williamr@2:         * @param[in] aWestLongitude The western longitude border of the search area.
williamr@2:         * @param[in] aEastLongitude The eastern longitude border of the search area.
williamr@2:         * @returns @p KErrNone if successful, @p KErrArgument if the input
williamr@2:         *   parameters are invalid, otherwise a system wide error code.
williamr@2:         */
williamr@2:         IMPORT_C TInt SetSearchArea(
williamr@2:             const TReal64& aSouthLatitude,
williamr@2:             const TReal64& aNorthLatitude,
williamr@2:             const TReal64& aWestLongitude,
williamr@2:             const TReal64& aEastLongitude
williamr@2:         );
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         // C++ constructor
williamr@2:         CPosLmAreaCriteria();
williamr@2: 
williamr@2:         void ConstructL(
williamr@2:             const TReal64&  aSouthLatitude,
williamr@2:             const TReal64&  aNorthLatitude,
williamr@2:             const TReal64&  aWestLongitude,
williamr@2:             const TReal64&  aEastLongitude
williamr@2:         );
williamr@2: 
williamr@2:         // Prohibit copy constructor
williamr@2:         CPosLmAreaCriteria( const CPosLmAreaCriteria& );
williamr@2:         // Prohibit assigment operator
williamr@2:         CPosLmAreaCriteria& operator= ( const CPosLmAreaCriteria& );
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         TReal64 iSouthLatitude;
williamr@2:         TReal64 iNorthLatitude;
williamr@2:         TReal64 iWestLongitude;
williamr@2:         TReal64 iEastLongitude;
williamr@2: 
williamr@2:     };
williamr@2: 
williamr@2: #endif      // CPOSLMAREACRITERIA_H
williamr@2: 
williamr@2: