/*

* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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