Collapse all Symbian^3 Application Developer Library

CPosLandmark Class Reference

class CPosLandmark : public CBase

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 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 CPosLandmarkDatabase::UpdateLandmarkL (or CPosLandmarkDatabase::AddLandmarkL for a new landmark).

eposlandmarks.lib

Since: S60 3.0

Inherits from

CPosLandmark
- CBase

Public Member Functions
	~CPosLandmark ()
IMPORT_C void	AddCategoryL ( TPosLmItemId )
IMPORT_C TPositionFieldId	FirstPositionFieldId ()
IMPORT_C void	GetCategoriesL ( RArray < TPosLmItemId > &)
IMPORT_C TInt	GetCoverageRadius ( TReal32 &)
IMPORT_C TInt	GetIcon ( TPtrC &, TInt &, TInt &)
IMPORT_C TInt	GetLandmarkDescription ( TPtrC &)
IMPORT_C TInt	GetLandmarkName ( TPtrC &)
IMPORT_C TInt	GetPlaceId ( TPtrC &)
IMPORT_C TInt	GetPosition ( TLocality &)
IMPORT_C TInt	GetPositionField ( TPositionFieldId , TPtrC &)
IMPORT_C TInt	GetTimeStamp ( TTime &)
IMPORT_C TBool	IsPartial ()
IMPORT_C TBool	IsPositionFieldAvailable ( TPositionFieldId )
IMPORT_C TPosLmItemId	LandmarkId ()
IMPORT_C CPosLandmark *	NewL ()
IMPORT_C CPosLandmark *	NewL (const CPosLandmark &)
IMPORT_C CPosLandmark *	NewLC ()
IMPORT_C CPosLandmark *	NewLC (const CPosLandmark &)
IMPORT_C TPositionFieldId	NextPositionFieldId ( TPositionFieldId )
IMPORT_C TUint	NumOfAvailablePositionFields ()
IMPORT_C void	RemoveCategory ( TPosLmItemId )
IMPORT_C void	RemoveLandmarkAttributes ( TAttributes )
IMPORT_C void	RemovePositionField ( TPositionFieldId )
IMPORT_C void	SetCoverageRadius ( TReal32 )
IMPORT_C void	SetIconL (const TDesC &, TInt , TInt )
IMPORT_C void	SetLandmarkDescriptionL (const TDesC &)
void	SetLandmarkIdL ( TPosLmItemId )
IMPORT_C void	SetLandmarkNameL (const TDesC &)
void	SetPartialL ( TBool )
IMPORT_C void	SetPlaceIdL (const TDesC &)
IMPORT_C void	SetPositionFieldL ( TPositionFieldId , const TDesC &)
IMPORT_C void	SetPositionL (const TLocality &)
IMPORT_C void	SetTimeStampL (const TTime )

Private Member Functions
	CPosLandmark ()
	CPosLandmark (const CPosLandmark &)
void	ConstructL ()
void	ConstructL (const CPosLandmark &)
CPosLandmark &	operator= (const CPosLandmark &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Public Member Enumerations
enum	_TAttributes { ENoAttribute = 0x0000, ELandmarkName = 0x0001, EPosition = 0x0002, ECoverageRadius = 0x0004, ECategoryInfo = 0x0008, EIcon = 0x0010, EDescription = 0x0020, EPlaceId = 0x0040, ETimeStamp = 0x0080, EAllAttributes = 0xFFFF }

Public Member Type Definitions
typedef	TUint32 TAttributes

Private Attributes
RArray < TPosLmItemId >	iCategoryArray
TReal32	iCoverageRadius
HBufC *	iIconFileName
TInt	iIconIndex
TInt	iIconMaskIndex
TPosLmItemId	iId
TBool	iIsPartial
HBufC *	iLandmarkDescription
HBufC *	iLandmarkName
TLocality *	iPosition
RArray < TUint >	iPositionFieldIds
CDesCArray *	iPositionFieldStrings

Constructor & Destructor Documentation

CPosLandmark()

CPosLandmark

(

)

[private]

CPosLandmark(const CPosLandmark &)

CPosLandmark

(

const CPosLandmark &

)

[private]

Parameters

const CPosLandmark &

~CPosLandmark()

~CPosLandmark

(

)

[virtual]

Destructor.

Member Functions Documentation

AddCategoryL(TPosLmItemId)

IMPORT_C void

AddCategoryL

(

TPosLmItemId

aCategoryId

)

Adds a category to the landmark.

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

Parameters

TPosLmItemId aCategoryId

The category to add.

ConstructL()

void

ConstructL

(

)

[private]

ConstructL(const CPosLandmark &)

void

ConstructL

(

const CPosLandmark &

aLandmark

)

[private]

Parameters

const CPosLandmark & aLandmark

FirstPositionFieldId()

IMPORT_C TPositionFieldId

FirstPositionFieldId

(

)

const

Returns the first position field contained in the landmark.

This function is used to initiate iteration over the position fields. NextPositionFieldId() is called to continue the iteration.

GetCategoriesL(RArray< TPosLmItemId > &)

IMPORT_C void

GetCategoriesL

(

RArray < TPosLmItemId > &

aCategoryIdArray

)

const

Retrieves the database item IDs for the categories contained in this landmark.

Parameters

RArray < TPosLmItemId > & aCategoryIdArray

On return contains the list of this landmark's categories.

GetCoverageRadius(TReal32 &)

IMPORT_C TInt

GetCoverageRadius

(

TReal32 &

aCoverageRadius

)

const

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.

Parameters

TReal32 & aCoverageRadius

On return contains the coverage radius.

GetIcon(TPtrC &, TInt &, TInt &)

IMPORT_C TInt	GetIcon	(	TPtrC &	aIconFileName,
			TInt &	aIconIndex,
			TInt &	aIconMaskIndex
		)	const

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.

Parameters

TPtrC & aIconFileName	The full icon file name.
TInt & aIconIndex	The index of the icon within the icon file.
TInt & aIconMaskIndex	The index of the icon mask within the icon file. If no icon mask index is defined KPosLmIconMaskNotUsed is returned.

GetLandmarkDescription(TPtrC &)

IMPORT_C TInt

GetLandmarkDescription

(

TPtrC &

aLandmarkDescription

)

const

Reads the description of the landmark.

This function returns error code 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 "".

Parameters

TPtrC & aLandmarkDescription

On return contains the landmark description.

GetLandmarkName(TPtrC &)

IMPORT_C TInt

GetLandmarkName

(

TPtrC &

aLandmarkName

)

const

Reads the name of the landmark.

This function returns error code 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 "".

Parameters

TPtrC & aLandmarkName

On return contains the landmark name.

GetPlaceId(TPtrC &)

IMPORT_C TInt

GetPlaceId

(

TPtrC &

aPId

)

const

Gets the PlaceId of the landmark

Parameters

TPtrC & aPId

On return contains the place id of the landmark

GetPosition(TLocality &)

IMPORT_C TInt

GetPosition

(

TLocality &

aPosition

)

const

Reads the landmark position.

Parameters

TLocality & aPosition

On return contains the landmark position.

GetPositionField(TPositionFieldId, TPtrC &)

IMPORT_C TInt	GetPositionField	(	TPositionFieldId	aFieldId,
			TPtrC &	aFieldValue
		)	const

Reads the value of a position field.

Parameters

TPositionFieldId aFieldId	The position field to read.
TPtrC & aFieldValue	On return contains the value of the position field.

GetTimeStamp(TTime &)

IMPORT_C TInt

GetTimeStamp

(

TTime &

aTimeStamp

)

const

Gets the timestamp of the landmark

Parameters

TTime & aTimeStamp

On return contains the timestamp of the landamrk

IsPartial()

IMPORT_C TBool

IsPartial

(

)

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 CPosLandmarkDatabase::UpdateLandmarkL() .

For more about partial landmarks, see CPosLandmarkDatabase::ReadPartialLandmarkLC() .

IsPositionFieldAvailable(TPositionFieldId)

IMPORT_C TBool

IsPositionFieldAvailable

(

TPositionFieldId

aFieldId

)

const

Checks if the landmark contains a specific position field.

Parameters

TPositionFieldId aFieldId

The position field.

LandmarkId()

IMPORT_C TPosLmItemId

LandmarkId

(

)

const

Reads the ID of the landmark entry in the database.

NewL()

IMPORT_C CPosLandmark *

NewL

(

)

[static]

Two-phased constructor.

NewL(const CPosLandmark &)

IMPORT_C CPosLandmark *

NewL

(

const CPosLandmark &

aLandmark

)

[static]

Two-phased copy constructor.

Parameters

const CPosLandmark & aLandmark

The landmark to copy.

NewLC()

IMPORT_C CPosLandmark *

NewLC

(

)

[static]

Two-phased constructor.

NewLC(const CPosLandmark &)

IMPORT_C CPosLandmark *

NewLC

(

const CPosLandmark &

aLandmark

)

[static]

Two-phased copy constructor.

Parameters

const CPosLandmark & aLandmark

The landmark to copy.

NextPositionFieldId(TPositionFieldId)

IMPORT_C TPositionFieldId

NextPositionFieldId

(

TPositionFieldId

aFieldId

)

const

Returns the next position field contained in the landmark.

This function is used to iterate the position fields in the landmark. FirstPositionFieldId() is called to get the first ID. This ID is passed to 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 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.

panic: "Landmarks Client"-EPosInvalidPositionFieldId Client specified a field ID, which is not contained in the landmark.

Parameters

TPositionFieldId aFieldId

The last position field which was read.

NumOfAvailablePositionFields()

IMPORT_C TUint

NumOfAvailablePositionFields

(

)

const

Returns the number of position fields set in the landmark.

RemoveCategory(TPosLmItemId)

IMPORT_C void

RemoveCategory

(

TPosLmItemId

aCategoryId

)

Removes a category from the landmark.

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

Parameters

TPosLmItemId aCategoryId

The category to remove

RemoveLandmarkAttributes(TAttributes)

IMPORT_C void

RemoveLandmarkAttributes

(

TAttributes

aAttributes

)

Removes landmark attributes from the landmark.

Parameters

TAttributes aAttributes

A bitmap specifying which landmark attributes to remove.

RemovePositionField(TPositionFieldId)

IMPORT_C void

RemovePositionField

(

TPositionFieldId

aFieldId

)

Removes a position field from the landmark.

If the specified position field is not contained in the landmark, nothing will happen.

Parameters

TPositionFieldId aFieldId

The position field to remove.

SetCoverageRadius(TReal32)

IMPORT_C void

SetCoverageRadius

(

TReal32

aCoverageRadius

)

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.

Parameters

TReal32 aCoverageRadius

The coverage radius.

SetIconL(const TDesC &, TInt, TInt)

IMPORT_C void	SetIconL	(	const TDesC &	aIconFileName,
			TInt	aIconIndex,
			TInt	aIconMaskIndex
		)

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.

leave: KErrArgument The icon file name is longer than KMaxFileName .

panic: "Landmarks Client"-EPosLmInvalidArgument The icon index is negative or the icon mask index is negative and not equal to KPosLmIconMaskNotUsed .

Parameters

const TDesC & aIconFileName	The full icon file name.
TInt aIconIndex	The index of the icon within the icon file.
TInt aIconMaskIndex	The index of the icon mask within the icon file.

SetLandmarkDescriptionL(const TDesC &)

IMPORT_C void

SetLandmarkDescriptionL

(

const TDesC &

aLandmarkDescription

)

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 "".

leave: KErrArgument The name of the landmark is longer than KPosLmMaxDescriptionLength .

Parameters

const TDesC & aLandmarkDescription

The landmark description.

SetLandmarkIdL(TPosLmItemId)

void

SetLandmarkIdL

(

TPosLmItemId

aId

)

Parameters

TPosLmItemId aId

SetLandmarkNameL(const TDesC &)

IMPORT_C void

SetLandmarkNameL

(

const TDesC &

aLandmarkName

)

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 "".

leave: KErrArgument If the name of the landmark is longer than KPosLmMaxTextFieldLength

Parameters

const TDesC & aLandmarkName

The landmark name.

SetPartialL(TBool)

void

SetPartialL

(

TBool

aPartial

)

Parameters

TBool aPartial

SetPlaceIdL(const TDesC &)

IMPORT_C void

SetPlaceIdL

(

const TDesC &

aPId

)

Sets the PlaceId for the landmark

leave: Symbian error codes

Parameters

const TDesC & aPId

The place id of the landmark

SetPositionFieldL(TPositionFieldId, const TDesC &)

IMPORT_C void	SetPositionFieldL	(	TPositionFieldId	aFieldId,
			const TDesC &	aFieldValue
		)

Sets a position field in the landmark.

leave: KErrArgument If the position field text is longer than KPosLmMaxTextFieldLength .

Parameters

TPositionFieldId aFieldId	The position field to set.
const TDesC & aFieldValue	The new value for the position field.

SetPositionL(const TLocality &)

IMPORT_C void

SetPositionL

(

const TLocality &

aPosition

)

Sets the landmark position.

Latitude and longitude must be set in the position.

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

leave: KErrArgument Latitude and/or longitude is not set or other datum than KPositionDatumWgs84 is used in aPosition .

Parameters

const TLocality & aPosition

The landmark position.

SetTimeStampL(const TTime)

IMPORT_C void

SetTimeStampL

(

const TTime

aTimeStamp

)

Sets the timestamp of the landmark.

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

Parameters

const TTime aTimeStamp

Timestamp of the landmark(Full date & time)

operator=(const CPosLandmark &)

CPosLandmark &

operator=

(

const CPosLandmark &

)

[private]

Parameters

const CPosLandmark &

Member Enumerations Documentation

Enum _TAttributes

Specifies a landmark attribute such as landmark name or landmark position.

Enumerators

ENoAttribute = 0x0000	No attribute specified.
ELandmarkName = 0x0001	The name of the landmark.
EPosition = 0x0002	The position of the landmark.
ECoverageRadius = 0x0004	The landmark coverage radius.
ECategoryInfo = 0x0008	The categories of the landmark.
EIcon = 0x0010	The icon that represents the landmark in a UI.
EDescription = 0x0020	A description of the landmark.
EPlaceId = 0x0040	PlaceId for the landmark
ETimeStamp = 0x0080	Timestamp associated with the landmark
EAllAttributes = 0xFFFF