/*

* Copyright (c) 2005-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:  CPosLandmark class

*

*/

#ifndef CPOSLANDMARK_H

#define CPOSLANDMARK_H

#include <e32base.h>

#include <lbsfields.h>

#include <badesca.h>

#include "EPos_Landmarks.h"

class TLocality;

/**

*  This is a container class for a landmark.

*

*  A landmark is principally a location with a name.

*

*  The landmark object can either be created by a client or retrieved from

*  @ref CPosLandmarkDatabase.

*

*  A landmark consists of a number of landmark attributes, e.g. landmark name,

*  landmark position, coverage area, etc.

*

*  A landmark may also contain generic position fields. These position fields

*  are defined in LbsFieldIds.h. Only text fields are supported.If the client 

*  wants to store a non-text field, the value must first be converted to a 

*  textual representation.

*  EPositionPlaceId position field added in extension of TPositionFieldId to support Place id

*  EPositionTimeStamp position field added in extension of TPositionFieldId to support TimeStamp

*

*  CPosLandmark contains functions for setting and getting landmark attributes

*  and position fields.

*

*  Note: CPosLandmark is only a local representation of the landmark. To

*  update the database, call @ref CPosLandmarkDatabase::UpdateLandmarkL (or

*  @ref CPosLandmarkDatabase::AddLandmarkL for a new landmark).

*

*  @lib eposlandmarks.lib

*  @since S60 3.0

*/

class CPosLandmark : public CBase

    {

    public:

        /**

        *  Bitmap for specifying a group of landmark attributes. Bit values are

        *  defined by @ref _TAttributes.

        */

        typedef TUint32 TAttributes;

        /**

        *  Specifies a landmark attribute such as landmark name or landmark

        *  position.

        */

        enum _TAttributes

            {

						/**

            * No attribute specified. 

						*/

            ENoAttribute        = 0x0000  ,

						/**

            * The name of the landmark.

            */

            ELandmarkName       = 0x0001  ,

						/**

            * The position of the landmark. 

						*/

            EPosition           = 0x0002  ,

						/**

            * The landmark coverage radius. 

						*/

            ECoverageRadius     = 0x0004  ,

            /**

            * The categories of the landmark. 

						*/

            ECategoryInfo       = 0x0008  ,

            /**

            * The icon that represents the landmark in a UI. 

            */

            EIcon               = 0x0010  ,

            /**

            * A description of the landmark. 

            */

            EDescription        = 0x0020  ,

            /**

            * PlaceId for the landmark

            */    

            EPlaceId						= 0x0040  ,

            /**

            * Timestamp associated with the landmark

            */

            ETimeStamp					= 0x0080  ,

            /*

            * All landmark attributes. 

            */

            EAllAttributes      = 0xFFFF  

            };

    public:

        /**

        * Two-phased constructor.

        *

        * @returns A new instance of this class.

        */

        IMPORT_C static CPosLandmark* NewLC();

        /**

        * Two-phased constructor.

        *

        * @returns A new instance of this class.

        */

        IMPORT_C static CPosLandmark* NewL();

        /**

        * Two-phased copy constructor.

        *

        * @param[in] aLandmark The landmark to copy.

        * @returns A copy of the specified landmark object.

        */

        IMPORT_C static CPosLandmark* NewLC(

               const CPosLandmark&  aLandmark

        );

        /**

        * Two-phased copy constructor.

        *

        * @param[in] aLandmark The landmark to copy.

        * @returns A copy of the specified landmark object.

        */

        IMPORT_C static CPosLandmark* NewL(

               const CPosLandmark&  aLandmark

        );

        /**

        * Destructor.

        */

        virtual ~CPosLandmark();

    public:

        /**

        * Reads the ID of the landmark entry in the database.

        *

        * @returns The ID of the landmark entry in the database, or

        *   @p KPosLmNullItemId if the landmark has not been added to the

        *   database yet.

        */

        IMPORT_C TPosLmItemId LandmarkId() const;

        /**

        * Checks if the landmark is partial.

        *

        * A client can read partial information about a landmark from the

        * database. This function checks if only partial information is

        * included in the landmark object. Partial landmark can not be used

        * with @ref CPosLandmarkDatabase::UpdateLandmarkL().

        *

        * For more about partial landmarks, see

        * @ref CPosLandmarkDatabase::ReadPartialLandmarkLC().

        *

        * @returns @p EFalse if the landmark contains all the landmark

        *   information, otherwise @p ETrue.

        */

        IMPORT_C TBool IsPartial() const;

        /**

        * Reads the name of the landmark.

        *

        * This function returns error code @p KErrNotFound if the landmark

        * name is not set in this landmark object. This will be the case if

        * the landmark is read from the database using partial read and

        * landmark name is excluded. Note that if a landmark is fully read

        * from the database, the landmark name will always be included. If no

        * name has been set for the landmark in the database, it will

        * have an empty name string "".

        *

        * @param[out] aLandmarkName On return contains the landmark name.

        * @returns @p KErrNone if successful, @p KErrNotFound if the landmark

        *   name is not specified.

        */

        IMPORT_C TInt GetLandmarkName(

               TPtrC&  aLandmarkName

        ) const;

        /**

        * Sets the name of the landmark.

        *

        * If no name is set for the landmark when it is written to the database,

        * the landmark in the database will have an empty name string "".

        *

        * @param[in] aLandmarkName The landmark name.

        *

        * @leave KErrArgument If the name of the landmark is longer than

        * @p KPosLmMaxTextFieldLength

        */

        IMPORT_C void SetLandmarkNameL(

               const TDesC&  aLandmarkName

        );

        /**

        * Reads the landmark position.

        *

        * @param[out] aPosition On return contains the landmark position.

        * @returns @p KErrNone if successful, @p KErrNotFound if the landmark

        *   position is not set.

        */

        IMPORT_C TInt GetPosition(

               TLocality&  aPosition

        ) const;

        /**

        * Sets the landmark position.

        *

        * Latitude and longitude must be set in the position.

        *

        * Only WGS 84 coordinates are allowed. @p KPositionDatumWgs84 must be set as datum.

        *

        * @param[in] aPosition The landmark position.

        *

        * @leave KErrArgument Latitude and/or longitude is not set or other datum 

        *   than @p KPositionDatumWgs84 is used in @p aPosition.

        */

        IMPORT_C void SetPositionL(

               const TLocality& aPosition

        );

        /**

        * Reads the landmark coverage radius.

        *

        * Coverage radius is set if the landmark is big, e.g. a city. It

        * defines the size of the area which the landmark represents.

        *

        * @param[out] aCoverageRadius On return contains the coverage radius.

        * @returns @p KErrNone if successful, @p KErrNotFound if the landmark

        *   coverage radius is not set.

        */

        IMPORT_C TInt GetCoverageRadius(

               TReal32&  aCoverageRadius

        ) const;

        /**

        * Sets the landmark coverage radius.

        *

        * Coverage radius is set if the landmark is big, e.g. a city. It

        * defines the size of the area which the landmark represents.

        *

        * If coverage radius is set to NaN, then the coverage radius will be

        * removed.

        *

        * @param aCoverageRadius The coverage radius.

        */

        IMPORT_C void SetCoverageRadius(

               TReal32  aCoverageRadius

        );

        /**

        * Adds a category to the landmark.

        *

        * If the specified category has already been added, nothing happens.

        *

        * @param aCategoryId The category to add.

        */

        IMPORT_C void AddCategoryL(

               TPosLmItemId  aCategoryId

        );

        /**

        * Removes a category from the landmark.

        *

        * If the specified category is not in the landmark, nothing happens.

        *

        * @param aCategoryId The category to remove

        */

        IMPORT_C void RemoveCategory(

               TPosLmItemId  aCategoryId

        );

        /**

        * Retrieves the database item IDs for the categories contained in this

        * landmark.

        *

        * @param[out] aCategoryIdArray On return contains the list of this 

        *   landmark's categories.

        */

        IMPORT_C void GetCategoriesL(

               RArray<TPosLmItemId>&  aCategoryIdArray

        ) const;

        /**

        * Checks if the landmark contains a specific position field.

        *

        * @param aFieldId The position field.

        * @returns @p ETrue if the landmark contains the field, otherwise

        *   @p EFalse.

        */

        IMPORT_C TBool IsPositionFieldAvailable(

               TPositionFieldId aFieldId

        ) const;

        /**

        * Returns the number of position fields set in the landmark.

        *

        * @returns The number of position fields set in the landmark.

        */

        IMPORT_C TUint NumOfAvailablePositionFields() const;

        /**

        * Returns the first position field contained in the landmark.

        *

        * This function is used to initiate iteration over the position fields.

        * @ref NextPositionFieldId() is called to continue the iteration.

        *

        * @returns The first position field contained by the landmark, or

        *   @p EPositionFieldNone if there are no position fields in the

        *   landmark.

        */

        IMPORT_C TPositionFieldId FirstPositionFieldId() const;

        /**

        * Returns the next position field contained in the landmark.

        *

        * This function is used to iterate the position fields in the landmark.

        * @ref FirstPositionFieldId() is called to get the first ID. This ID is

        * passed to @ref NextPositionFieldId() to obtain the second ID, etc.

        *

        * If the client specifies an ID which is not contained in the landmark,

        * this function will panic with code @p EPosInvalidPositionFieldId. It

        * is therefore important that the client does not remove the current

        * field while iterating. If the client still removes the current field,

        * the client must pass the previous field.

        *

        * @param aFieldId The last position field which was read.

        * @returns The next position field contained by the landmark, or

        *   @p EPositionFieldNone if there are no more position fields in the

        *   landmark.

        *

        * @panic "Landmarks Client"-EPosInvalidPositionFieldId Client specified a field ID,

        *   which is not contained in the landmark.

        */

        IMPORT_C TPositionFieldId NextPositionFieldId(

               TPositionFieldId aFieldId

        ) const;

        /**

        * Reads the value of a position field.

        *

        * @param[in] aFieldId The position field to read.

        * @param[out] aFieldValue On return contains the value of the position field.

        * @returns @p KErrNone if successful, @p KErrNotFound if the landmark

        *   does not contain the specified position field.

        */

        IMPORT_C TInt GetPositionField(

               TPositionFieldId aFieldId,

               TPtrC& aFieldValue

        ) const;

        /**

        * Sets a position field in the landmark.

        *

        * @param[in] aFieldId The position field to set.

        * @param[in] aFieldValue The new value for the position field.

        *

        * @leave KErrArgument If the position field text is longer than

        *   @p KPosLmMaxTextFieldLength.

        */

        IMPORT_C void SetPositionFieldL(

               TPositionFieldId aFieldId,

               const TDesC& aFieldValue

        );

        /**

        * Removes a position field from the landmark.

        *

        * If the specified position field is not contained in the landmark,

        * nothing will happen.

        *

        * @param aFieldId The position field to remove.

        */

        IMPORT_C void RemovePositionField(

               TPositionFieldId  aFieldId

        );

        /**

        * Associates the landmark with an icon.

        *

        * Icons are found in icon files. To set an icon, the client

        * must specify the name of the icon file and the index of the

        * icon within the file.

        *

        * The landmark is not affected if the icon file is changed or

        * removed. It only contains a link to the icon.

        *

        * @param[in] aIconFileName The full icon file name.

        * @param[in] aIconIndex The index of the icon within the icon file.

        * @param[in] aIconMaskIndex The index of the icon mask within the

        *   icon file.

        *

        * @leave KErrArgument The icon file name is longer than @p KMaxFileName.

        *

        * @panic "Landmarks Client"-EPosLmInvalidArgument The icon index is negative or

        *   the icon mask index is negative and not equal to @p KPosLmIconMaskNotUsed.

        */

        IMPORT_C void SetIconL(

               const TDesC&  aIconFileName,

               TInt  aIconIndex,

               TInt  aIconMaskIndex

        );

        /**

        * Returns the link to the icon associated with the landmark.

        *

        * Icons are found in icon files. It is referenced by the name of

        * the icon file and the index of the icon within the file.

        *

        * The landmark is not affected if the icon file is changed or

        * removed. It only contains a link to the icon. This means that the

        * link could be invalid.

        *

        * @param[out] aIconFileName The full icon file name.

        * @param[out] aIconIndex The index of the icon within the icon file.

        * @param[out] aIconMaskIndex The index of the icon mask within the

        *   icon file. If no icon mask index is defined @p KPosLmIconMaskNotUsed

        *   is returned.

        *

        * @returns @p KErrNone if successful, @p KErrNotFound if the icon is

        *   not set.

        */

        IMPORT_C TInt GetIcon(

               TPtrC& aIconFileName,

               TInt&  aIconIndex,

               TInt&  aIconMaskIndex

        ) const;

        /**

        * Reads the description of the landmark.

        *

        * This function returns error code @p KErrNotFound if the landmark

        * description is not set in this landmark object. This will be the case

        * if the landmark is read from the database using partial read and

        * landmark description is excluded. Note that if a landmark is fully

        * read from the database, the landmark description is always

        * included. If no description has been set for the landmark in

        * the database, it is set to an empty string "".

        *

        * @param[out] aLandmarkDescription On return contains the landmark description.

        * @returns @p KErrNone if successful, @p KErrNotFound if the landmark

        *   description is not specified.

        */

        IMPORT_C TInt GetLandmarkDescription(

               TPtrC&  aLandmarkDescription

        ) const;

        /**

        * Sets a description for the landmark.

        *

        * If no description is set for the landmark when it is written to the

        * database, the landmark in the database will have an empty description

        * string "".

        *

        * @param[in] aLandmarkDescription The landmark description.

        *

        * @leave KErrArgument The name of the landmark is longer than

        *   @p KPosLmMaxDescriptionLength.

        */

        IMPORT_C void SetLandmarkDescriptionL(

               const TDesC&  aLandmarkDescription

        );

        /**

        * Removes landmark attributes from the landmark.

        *

        * @param aAttributes A bitmap specifying which landmark attributes to

        *   remove.

        */

        IMPORT_C void RemoveLandmarkAttributes(

               TAttributes  aAttributes

        );

        /**

        * @internal */

        /*

        * Sets the partial update flag to the landmark.

        * This flag is used to indicate if only partial information is included

        * in the landmark object.

        *

        * @param aPartial @p EFalse if the landmark contains all the landmark

        *   information, otherwise @p ETrue.

        */

        void SetPartialL(

               TBool aPartial

        );

        /**

        * @internal */

        /*

        * Sets the landmark ID to the landmark.

        *

        * @param aId The landmark ID to set.

        */

        void SetLandmarkIdL(

               TPosLmItemId aId

        );

				/**

				* Sets the PlaceId for the landmark

				* @param[in]  aPId The place id of the landmark

				* @leave  Symbian error codes

				*/

				IMPORT_C void SetPlaceIdL( const TDesC& aPId );

				/**

				* Gets the PlaceId of the landmark

				* @param[out] aPId On return contains the place id of the landmark

				* @return KErrNone if successful , else KErrNotFound if PlaceId is 

				*					not specified.

				*/

				IMPORT_C TInt GetPlaceId( TPtrC& aPId ) const;

				/**

				* Sets the timestamp of the landmark.

				* @param[in] aTimeStamp Timestamp of the landmark(Full date & time)

				* @leave KErrArgument If the full date & time have not been specified.

				*/

				IMPORT_C void SetTimeStampL( const TTime aTimeStamp );

				/**

				* Gets the timestamp of the landmark

				* @param[out] aTimeStamp On return contains the timestamp of the landamrk

				* @return KErrNone if successful , else KErrNotFound if TimeStamp is 

				*					not specified.

				*/

				IMPORT_C TInt GetTimeStamp( TTime& aTimeStamp )const;

    private:

        // C++ constructor.

        CPosLandmark();

        // Prohibit copy constructor

        CPosLandmark(const CPosLandmark&);

        // Prohibit assigment operator

        CPosLandmark& operator= (const CPosLandmark&);

        void ConstructL();

        void ConstructL(const CPosLandmark& aLandmark);

    private:

        // Landmark ID

        TPosLmItemId iId;

        // Partial landmark flag

        TBool iIsPartial;

        // Landmark name

        HBufC* iLandmarkName;

        // Landmark position information

        TLocality* iPosition;

        // Landmark coverage radius

        TReal32 iCoverageRadius;

        // Landmark categories

        RArray<TPosLmItemId> iCategoryArray;

        // Landmark position field IDs

        RArray<TUint> iPositionFieldIds;

        // Landmark position field strings

        CDesCArray* iPositionFieldStrings;

        // Landmark icon filename

        HBufC* iIconFileName;

        // Landmark icon index

        TInt iIconIndex;

        // Landmark icon mask index

        TInt iIconMaskIndex;

        // Landmark description

        HBufC* iLandmarkDescription;

    };

#endif      // CPOSLANDMARK_H