diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/mw/EPos_CPosLandmark.h
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/mw/EPos_CPosLandmark.h Wed Mar 31 12:33:34 2010 +0100
@@ -0,0 +1,608 @@
+/*
+* 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
+
+