/*

 * 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