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 +#include +#include + +#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& 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 iCategoryArray; + + // Landmark position field IDs + RArray 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 + +