/*
* Copyright (c) 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:  Geographical circular area class definition.
*
*/


#ifndef LBTGEOCIRCLE_H
#define LBTGEOCIRCLE_H

#include <lbtgeoareabase.h>
#include <lbsposition.h>

/**
 * Geographical circular area.
 *
 * A geographical circular area is defined by the center of the 
 * circle and the radius. The radius is in meters. The altitude in 
 * the center's coordinate is always ignored. It is optionally also possible 
 * to provide additional geographical area information of CLbtGeoCell 
 * type. Providing additional cell information would enable further 
 * optimization by reducing the number of GPS fixes required to
 * supervise the trigger, there by, reducing the impact on battery
 * consumption. Triggers would, initially, be monitored using the cell 
 * information provided. GPS would be used to check the coordinates 
 * only when the mobile terminal reaches the cell / cells specified. 
 * If a particular location is served by multiple cells, then it is 
 * important to mention all available cell information. If not, there 
 * is a possibility of missing triggers even when the mobile terminal 
 * reaches the location specified by the coordinates.
 *
 * @lib lbt.lib
 *
 * @since S60 5.1
 */
class CLbtGeoCircle : public CLbtGeoAreaBase
    {
public:
    /**
     * Allocates and constructs a new geographical circular area object.
     * In the returned object, the latitude, longitude and altitude 
     * are set to NaN, and the radius is set to NaN.
     *
     * @return Pointer to the new geographical circular area object.
     */
    IMPORT_C static CLbtGeoCircle* NewL();

    /**
     * Constructs a new geographical circular area object and pushes
     * it onto cleanup stack. 
     * In the returned object, the latitude, longitude and altitude 
     * are set to NaN, and the radius is set to NaN.
     *
     * @return Pointer to the new geographical circular area object.
     */
    IMPORT_C static CLbtGeoCircle* NewLC();

    /**
     * Allocates and constructs a new geographical circular area object
     * with specified center coordinate and radius.
     *
     * @panic ELbtErrArgument If the input radius is negative.
     *
     * @param[in] aCenter The coordinate of the center.
     * @param[in] aRadiusInMeters The radius of the circle in meters.
     * @return Pointer to the new geographical circle area object.
     */
    IMPORT_C static CLbtGeoCircle* NewL( 
        const TCoordinate& aCenter,
        TReal aRadiusInMeters );

    /**
     * Allocates and constructs a new geographical circular area object
     * with specified center coordinate and radius. The constructed
     * object is pushed onto cleanup stack.
     *
     * @panic ELbtErrArgument If the input radius is negative.
     *
     * @param[in] aCenter The coordinate of the center.
     * @param[in] aRadiusInMeters The radius of the circle in meters.
     * @return Pointer to the new geographical circle area object.
     */
    IMPORT_C static CLbtGeoCircle* NewLC( 
        const TCoordinate& aCenter,
        TReal aRadiusInMeters );

    /**
     * Destructor.
     */
    IMPORT_C ~CLbtGeoCircle();

    /**
     * Returns the type of geographical area, CLbtGeoAreaBase::ECircle
     *
     * @return CLbtGeoAreaBase::ECircle.
     */
    virtual TGeoAreaType Type() const;

    /**
     * Gets the center of the area. If the center has not been set
     * before, the returned coordinate has latitude, longitude and
     * altitude set to NaN, 
     *
     * @return The center of the area.
     */
    virtual TCoordinate Center() const;

    /**
     * Sets the center of the circle.
     *
     * @param[in] aCenter The coordinate of the center.
     */
    IMPORT_C void SetCenter(const TCoordinate& aCenter);

    /**
     * Gets the radius of the circle. If the radius has not been
     * set before, the returned value is NaN.
     *
     * @return The radius of the circle in meters.
     */
    IMPORT_C TReal Radius() const;

    /**
     * Sets the radius of the circle.
     *
     * @panic ELbtErrArgument If the input radius is negative.
     *
     * @param[in] aRadiusInMeters The radius of the circle in meters.
     */
    IMPORT_C void SetRadius(TReal aRadiusInMeters);
    
    /**
     * Gets geographical area information. The following method is currently not 
     * supported. This method will only return empty array when invoked.
     *
     * @return An array of geographical area instances
     */
    IMPORT_C RPointerArray< CLbtGeoAreaBase >& GetAdditionalGeoAreaInfo();
    
    /**
     * Sets additional geographical area information. The geographical 
     * information provided can only be of CLbtGeoCell type. This is optional
     * and clients may specify this information when available.The following method 
     * is currently not supported.
     *
     * @panic ELbtErrArgument if argument passed is NULL or if the argument
     * passed is of any other type other than CLbtGeoCell.
     *
     * @param[in] aGeoArea A pointer representing a geographical area.
     */
    IMPORT_C void SetAdditionalGeoAreaInfo(CLbtGeoAreaBase* aGeoArea);
    
    /**
     * Validates cell information.
     *
     * @leave KErrArgument if any of the mandatory parameters have not
     * been specified.
     */
    void ValidateCircleInformationL();  
    
protected:
    
   /**
    * Externalize method that subclass must implement.
    * @param[in] aStream Stream to which the object should be externalized.
    */
   virtual void DoExternalizeL(RWriteStream& aStream) const ;
   
   /**
    * Internalize method that subclass must implement.
    * @param[in] aStream Stream from which the object should be internalized.
    */
   virtual void DoInternalizeL(RReadStream& aStream)  ;

private:
    /**
     * Default constructor
     */
    CLbtGeoCircle();

    /**
     * By default, prohibit copy constructor
     */
    CLbtGeoCircle(const CLbtGeoCircle&);
   
    /**
     * Prohibit assigment operator
     */
    CLbtGeoCircle& operator= (const CLbtGeoCircle&);
    
    /**
     * Symbian 2nd phase constructor
     */
    void ConstructL();
    
    /**
     * Symbian 2nd phase constructor
     */
    void ConstructL(TCoordinate aCenter,TReal aRadius);
    
        
private:
    /**
     * The center of the circle.
     */
    TCoordinate iCenter;

    /**
     * Radius of the circle in meters.
     */
    TReal iRadius;
    
    /**
     * An array of instances representing additional geographical area 
     * information
     */
    RPointerArray< CLbtGeoAreaBase > iAdditionalGeoAreaInfo;
    };

#endif // LBTGEOCIRCLE_H