williamr@2: /*
williamr@2: * Copyright (c) 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:  Geographical circular area class definition.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef LBTGEOCIRCLE_H
williamr@2: #define LBTGEOCIRCLE_H
williamr@2: 
williamr@2: #include <lbtgeoareabase.h>
williamr@2: #include <lbsposition.h>
williamr@2: 
williamr@2: /**
williamr@2:  * Geographical circular area.
williamr@2:  *
williamr@2:  * A geographical circular area is defined by the center of the 
williamr@2:  * circle and the radius. The radius is in meters. The altitude in 
williamr@2:  * the center's coordinate is always ignored. It is optionally also possible 
williamr@2:  * to provide additional geographical area information of CLbtGeoCell 
williamr@2:  * type. Providing additional cell information would enable further 
williamr@2:  * optimization by reducing the number of GPS fixes required to
williamr@2:  * supervise the trigger, there by, reducing the impact on battery
williamr@2:  * consumption. Triggers would, initially, be monitored using the cell 
williamr@2:  * information provided. GPS would be used to check the coordinates 
williamr@2:  * only when the mobile terminal reaches the cell / cells specified. 
williamr@2:  * If a particular location is served by multiple cells, then it is 
williamr@2:  * important to mention all available cell information. If not, there 
williamr@2:  * is a possibility of missing triggers even when the mobile terminal 
williamr@2:  * reaches the location specified by the coordinates.
williamr@2:  *
williamr@2:  * @lib lbt.lib
williamr@2:  *
williamr@2:  * @since S60 5.1
williamr@2:  */
williamr@2: class CLbtGeoCircle : public CLbtGeoAreaBase
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:      * Allocates and constructs a new geographical circular area object.
williamr@2:      * In the returned object, the latitude, longitude and altitude 
williamr@2:      * are set to NaN, and the radius is set to NaN.
williamr@2:      *
williamr@2:      * @return Pointer to the new geographical circular area object.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtGeoCircle* NewL();
williamr@2: 
williamr@2:     /**
williamr@2:      * Constructs a new geographical circular area object and pushes
williamr@2:      * it onto cleanup stack. 
williamr@2:      * In the returned object, the latitude, longitude and altitude 
williamr@2:      * are set to NaN, and the radius is set to NaN.
williamr@2:      *
williamr@2:      * @return Pointer to the new geographical circular area object.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtGeoCircle* NewLC();
williamr@2: 
williamr@2:     /**
williamr@2:      * Allocates and constructs a new geographical circular area object
williamr@2:      * with specified center coordinate and radius.
williamr@2:      *
williamr@2:      * @panic ELbtErrArgument If the input radius is negative.
williamr@2:      *
williamr@2:      * @param[in] aCenter The coordinate of the center.
williamr@2:      * @param[in] aRadiusInMeters The radius of the circle in meters.
williamr@2:      * @return Pointer to the new geographical circle area object.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtGeoCircle* NewL( 
williamr@2:         const TCoordinate& aCenter,
williamr@2:         TReal aRadiusInMeters );
williamr@2: 
williamr@2:     /**
williamr@2:      * Allocates and constructs a new geographical circular area object
williamr@2:      * with specified center coordinate and radius. The constructed
williamr@2:      * object is pushed onto cleanup stack.
williamr@2:      *
williamr@2:      * @panic ELbtErrArgument If the input radius is negative.
williamr@2:      *
williamr@2:      * @param[in] aCenter The coordinate of the center.
williamr@2:      * @param[in] aRadiusInMeters The radius of the circle in meters.
williamr@2:      * @return Pointer to the new geographical circle area object.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtGeoCircle* NewLC( 
williamr@2:         const TCoordinate& aCenter,
williamr@2:         TReal aRadiusInMeters );
williamr@2: 
williamr@2:     /**
williamr@2:      * Destructor.
williamr@2:      */
williamr@2:     IMPORT_C ~CLbtGeoCircle();
williamr@2: 
williamr@2:     /**
williamr@2:      * Returns the type of geographical area, CLbtGeoAreaBase::ECircle
williamr@2:      *
williamr@2:      * @return CLbtGeoAreaBase::ECircle.
williamr@2:      */
williamr@2:     virtual TGeoAreaType Type() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the center of the area. If the center has not been set
williamr@2:      * before, the returned coordinate has latitude, longitude and
williamr@2:      * altitude set to NaN, 
williamr@2:      *
williamr@2:      * @return The center of the area.
williamr@2:      */
williamr@2:     virtual TCoordinate Center() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the center of the circle.
williamr@2:      *
williamr@2:      * @param[in] aCenter The coordinate of the center.
williamr@2:      */
williamr@2:     IMPORT_C void SetCenter(const TCoordinate& aCenter);
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the radius of the circle. If the radius has not been
williamr@2:      * set before, the returned value is NaN.
williamr@2:      *
williamr@2:      * @return The radius of the circle in meters.
williamr@2:      */
williamr@2:     IMPORT_C TReal Radius() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the radius of the circle.
williamr@2:      *
williamr@2:      * @panic ELbtErrArgument If the input radius is negative.
williamr@2:      *
williamr@2:      * @param[in] aRadiusInMeters The radius of the circle in meters.
williamr@2:      */
williamr@2:     IMPORT_C void SetRadius(TReal aRadiusInMeters);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets geographical area information. The following method is currently not 
williamr@2:      * supported. This method will only return empty array when invoked.
williamr@2:      *
williamr@2:      * @return An array of geographical area instances
williamr@2:      */
williamr@2:     IMPORT_C RPointerArray< CLbtGeoAreaBase >& GetAdditionalGeoAreaInfo();
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets additional geographical area information. The geographical 
williamr@2:      * information provided can only be of CLbtGeoCell type. This is optional
williamr@2:      * and clients may specify this information when available.The following method 
williamr@2:      * is currently not supported.
williamr@2:      *
williamr@2:      * @panic ELbtErrArgument if argument passed is NULL or if the argument
williamr@2:      * passed is of any other type other than CLbtGeoCell.
williamr@2:      *
williamr@2:      * @param[in] aGeoArea A pointer representing a geographical area.
williamr@2:      */
williamr@2:     IMPORT_C void SetAdditionalGeoAreaInfo(CLbtGeoAreaBase* aGeoArea);
williamr@2:     
williamr@2:     /**
williamr@2:      * Validates cell information.
williamr@2:      *
williamr@2:      * @leave KErrArgument if any of the mandatory parameters have not
williamr@2:      * been specified.
williamr@2:      */
williamr@2:     void ValidateCircleInformationL();  
williamr@2:     
williamr@2: protected:
williamr@2:     
williamr@2:    /**
williamr@2:     * Externalize method that subclass must implement.
williamr@2:     * @param[in] aStream Stream to which the object should be externalized.
williamr@2:     */
williamr@2:    virtual void DoExternalizeL(RWriteStream& aStream) const ;
williamr@2:    
williamr@2:    /**
williamr@2:     * Internalize method that subclass must implement.
williamr@2:     * @param[in] aStream Stream from which the object should be internalized.
williamr@2:     */
williamr@2:    virtual void DoInternalizeL(RReadStream& aStream)  ;
williamr@2: 
williamr@2: private:
williamr@2:     /**
williamr@2:      * Default constructor
williamr@2:      */
williamr@2:     CLbtGeoCircle();
williamr@2: 
williamr@2:     /**
williamr@2:      * By default, prohibit copy constructor
williamr@2:      */
williamr@2:     CLbtGeoCircle(const CLbtGeoCircle&);
williamr@2:    
williamr@2:     /**
williamr@2:      * Prohibit assigment operator
williamr@2:      */
williamr@2:     CLbtGeoCircle& operator= (const CLbtGeoCircle&);
williamr@2:     
williamr@2:     /**
williamr@2:      * Symbian 2nd phase constructor
williamr@2:      */
williamr@2:     void ConstructL();
williamr@2:     
williamr@2:     /**
williamr@2:      * Symbian 2nd phase constructor
williamr@2:      */
williamr@2:     void ConstructL(TCoordinate aCenter,TReal aRadius);
williamr@2:     
williamr@2:         
williamr@2: private:
williamr@2:     /**
williamr@2:      * The center of the circle.
williamr@2:      */
williamr@2:     TCoordinate iCenter;
williamr@2: 
williamr@2:     /**
williamr@2:      * Radius of the circle in meters.
williamr@2:      */
williamr@2:     TReal iRadius;
williamr@2:     
williamr@2:     /**
williamr@2:      * An array of instances representing additional geographical area 
williamr@2:      * information
williamr@2:      */
williamr@2:     RPointerArray< CLbtGeoAreaBase > iAdditionalGeoAreaInfo;
williamr@2:     };
williamr@2: 
williamr@2: #endif // LBTGEOCIRCLE_H