CPosLandmark Class Reference

API published in: S60 3rd Ed

Link against: eposlandmarks.lib

Capability Information

Required Capabilities

None

Exceptions

The capability ReadUserData is required in:

CPosLandmarkDatabase::OpenL();

CPosLandmarkDatabase::OpenL( const TDesC & aDatabaseUri );

CPosLandmarkDatabase::InitializeL();

CPosLandmarkDatabase::ReadLandmarkLC( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::LandmarkIteratorL();

CPosLandmarkDatabase::LandmarkIteratorL( const TPosLmSortPref & aSortPref );

CPosLandmarkDatabase::AddLandmarkL( CPosLandmark & aLandmark );

CPosLandmarkDatabase::UpdateLandmarkL( const CPosLandmark & aLandmark );

CPosLandmarkDatabase::RemoveLandmarkL( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::RemoveLandmarksL( const RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLandmarkDatabase::RemoveAllLandmarksL();

CPosLandmarkDatabase::ReadPartialLandmarkLC( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::PreparePartialLandmarksL( const RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLandmarkDatabase::SizeL();

CPosLandmarkDatabase::CompactL();

CPosLandmarkDatabase::NotifyDatabaseEvent( TPosLmEvent & aEvent, TRequestStatus & aStatus );

CPosLandmarkDatabase::CancelNotifyDatabaseEvent();

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, TTransferOptions aTransferOptions );

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, const RArray<TUint>& aLandmarkSelection, TTransferOptions aTransferOptions );

CPosLmCategoryManager::ReadCategoryLC( TPosLmItemId aCategoryId );

CPosLmCategoryManager::CategoryIteratorL( TCategorySortPref aSortPref );

CPosLmCategoryManager::ReferencedCategoryIteratorL( TCategorySortPref aSortPref )

CPosLmCategoryManager::AddCategoryL( CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::UpdateCategoryL( const CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::RemoveCategoryL( TPosLmItemId aCategoryId );

CPosLmCategoryManager::RemoveCategoriesL( const RArray< TPosLmItemId > & aCategoryIdArray );

CPosLmCategoryManager::AddCategoryToLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::RemoveCategoryFromLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::GetCategoryL( const TDesC & aCategoryName );

CPosLmCategoryManager::GetGlobalCategoryL( TPosLmGlobalCategory aGlobalCategory );

CPosLmCategoryManager::ResetGlobalCategoriesL();

The capability WriteUserData is required in:

CPosLandmarkDatabase::AddLandmarkL( CPosLandmark& aLandmark );

CPosLandmarkDatabase::UpdateLandmarkL( const CPosLandmark& aLandmark );

CPosLandmarkDatabase::RemoveLandmarkL( TPosLmItemId aLandmarkId );

CPosLandmarkDatabase::RemoveLandmarksL( const RArray<TPosLmItemId>& aLandmarkIdArray );

CPosLandmarkDatabase::RemoveAllLandmarksL();

CPosLandmarkDatabase::CompactL();

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, TTransferOptions aTransferOptions );

CPosLandmarkDatabase::ImportLandmarksL( CPosLandmarkParser& aLandmarkParser, const RArray<TUint>& aLandmarkSelection, TTransferOptions aTransferOptions );

CPosLmCategoryManager::AddCategoryL( CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::UpdateCategoryL( const CPosLandmarkCategory & aCategory );

CPosLmCategoryManager::RemoveCategoryL( TPosLmItemId aCategoryId );

CPosLmCategoryManager::RemoveCategoriesL( const RArray< TPosLmItemId > & aCategoryIdArray );

CPosLmCategoryManager::AddCategoryToLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::RemoveCategoryFromLandmarksL( TPosLmItemId aCategoryId, RArray< TPosLmItemId > & aLandmarkIdArray );

CPosLmCategoryManager::ResetGlobalCategoriesL();

Other Information

The capability NetworkServices is required to work with remote databases.

#include <epos_cposlandmark.h>

Detailed Description

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.

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


Public Types
typedef TUint32	TAttributes
	Bitmap for specifying a group of landmark attributes.
enum	_TAttributes { ENoAttribute = 0x0000, ELandmarkName = 0x0001, EPosition = 0x0002, ECoverageRadius = 0x0004, ECategoryInfo = 0x0008, EIcon = 0x0010, EDescription = 0x0020, EAllAttributes = 0xFFFF }
	Specifies a landmark attribute such as landmark name or landmark position. More...
Public Member Functions
virtual	~CPosLandmark ()
	Destructor.
IMPORT_C TPosLmItemId	LandmarkId () const
	Reads the ID of the landmark entry in the database.
IMPORT_C TBool	IsPartial () const
	Checks if the landmark is partial.
IMPORT_C TInt	GetLandmarkName (TPtrC &aLandmarkName) const
	Reads the name of the landmark.
IMPORT_C void	SetLandmarkNameL (const TDesC &aLandmarkName)
	Sets the name of the landmark.
IMPORT_C TInt	GetPosition (TLocality &aPosition) const
	Reads the landmark position.
IMPORT_C void	SetPositionL (const TLocality &aPosition)
	Sets the landmark position.
IMPORT_C TInt	GetCoverageRadius (TReal32 &aCoverageRadius) const
	Reads the landmark coverage radius.
IMPORT_C void	SetCoverageRadius (TReal32 aCoverageRadius)
	Sets the landmark coverage radius.
IMPORT_C void	AddCategoryL (TPosLmItemId aCategoryId)
	Adds a category to the landmark.
IMPORT_C void	RemoveCategory (TPosLmItemId aCategoryId)
	Removes a category from the landmark.
IMPORT_C void	GetCategoriesL (RArray< TPosLmItemId > &aCategoryIdArray) const
	Retrieves the database item IDs for the categories contained in this landmark.
IMPORT_C TBool	IsPositionFieldAvailable (TPositionFieldId aFieldId) const
	Checks if the landmark contains a specific position field.
IMPORT_C TUint	NumOfAvailablePositionFields () const
	Returns the number of position fields set in the landmark.
IMPORT_C TPositionFieldId	FirstPositionFieldId () const
	Returns the first position field contained in the landmark.
IMPORT_C TPositionFieldId	NextPositionFieldId (TPositionFieldId aFieldId) const
	Returns the next position field contained in the landmark.
IMPORT_C TInt	GetPositionField (TPositionFieldId aFieldId, TPtrC &aFieldValue) const
	Reads the value of a position field.
IMPORT_C void	SetPositionFieldL (TPositionFieldId aFieldId, const TDesC &aFieldValue)
	Sets a position field in the landmark.
IMPORT_C void	RemovePositionField (TPositionFieldId aFieldId)
	Removes a position field from the landmark.
IMPORT_C void	SetIconL (const TDesC &aIconFileName, TInt aIconIndex, TInt aIconMaskIndex)
	Associates the landmark with an icon.
IMPORT_C TInt	GetIcon (TPtrC &aIconFileName, TInt &aIconIndex, TInt &aIconMaskIndex) const
	Returns the link to the icon associated with the landmark.
IMPORT_C TInt	GetLandmarkDescription (TPtrC &aLandmarkDescription) const
	Reads the description of the landmark.
IMPORT_C void	SetLandmarkDescriptionL (const TDesC &aLandmarkDescription)
	Sets a description for the landmark.
IMPORT_C void	RemoveLandmarkAttributes (TAttributes aAttributes)
	Removes landmark attributes from the landmark.
void	SetPartialL (TBool aPartial)
void	SetLandmarkIdL (TPosLmItemId aId)
Static Public Member Functions
static IMPORT_C CPosLandmark *	NewLC ()
	Two-phased constructor.
static IMPORT_C CPosLandmark *	NewL ()
	Two-phased constructor.
static IMPORT_C CPosLandmark *	NewLC (const CPosLandmark &aLandmark)
	Two-phased copy constructor.
static IMPORT_C CPosLandmark *	NewL (const CPosLandmark &aLandmark)
	Two-phased copy constructor.

Member Typedef Documentation

typedef TUint32 CPosLandmark::TAttributes

Bitmap for specifying a group of landmark attributes.

Bit values are defined by _TAttributes.

Member Enumeration Documentation

enum CPosLandmark::_TAttributes

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

Enumerator:

ENoAttribute	No attribute specified.
ELandmarkName	The name of the landmark.
EPosition	The position of the landmark.
ECoverageRadius	The landmark coverage radius.
ECategoryInfo	The categories of the landmark.
EIcon	The icon that represents the landmark in a UI.
EDescription	A description of the landmark.
EAllAttributes	All landmark attributes.

Constructor & Destructor Documentation

virtual CPosLandmark::~CPosLandmark ( ) [virtual]

Destructor.

Member Function Documentation

IMPORT_C void CPosLandmark::AddCategoryL

(

TPosLmItemId

aCategoryId

)

Adds a category to the landmark.

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

Parameters:

aCategoryId

The category to add.

IMPORT_C TPositionFieldId CPosLandmark::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.

Returns:: The first position field contained by the landmark, or EPositionFieldNone if there are no position fields in the landmark.

IMPORT_C void CPosLandmark::GetCategoriesL

(

RArray< TPosLmItemId > &

aCategoryIdArray

)

const

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

Parameters:

[out] aCategoryIdArray On return contains the list of this landmark's categories.

IMPORT_C TInt CPosLandmark::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:

[out] aCoverageRadius On return contains the coverage radius.

Returns:: KErrNone if successful, KErrNotFound if the landmark coverage radius is not set.

IMPORT_C TInt CPosLandmark::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:

`[out]`	aIconFileName	The full icon file name.
`[out]`	aIconIndex	The index of the icon within the icon file.
`[out]`	aIconMaskIndex	The index of the icon mask within the icon file. If no icon mask index is defined `KPosLmIconMaskNotUsed` is returned.

Returns:: KErrNone if successful, KErrNotFound if the icon is not set.

IMPORT_C TInt CPosLandmark::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:

[out] aLandmarkDescription On return contains the landmark description.

Returns:: KErrNone if successful, KErrNotFound if the landmark description is not specified.

IMPORT_C TInt CPosLandmark::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:

[out] aLandmarkName On return contains the landmark name.

Returns:: KErrNone if successful, KErrNotFound if the landmark name is not specified.

IMPORT_C TInt CPosLandmark::GetPosition

(

TLocality &

aPosition

)

const

Reads the landmark position.

Parameters:

[out] aPosition On return contains the landmark position.

Returns:: KErrNone if successful, KErrNotFound if the landmark position is not set.

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

Reads the value of a position field.

Parameters:

`[in]`	aFieldId	The position field to read.
`[out]`	aFieldValue	On return contains the value of the position field.

Returns:: KErrNone if successful, KErrNotFound if the landmark does not contain the specified position field.

IMPORT_C TBool CPosLandmark::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().

Returns:: EFalse if the landmark contains all the landmark information, otherwise ETrue.

IMPORT_C TBool CPosLandmark::IsPositionFieldAvailable

(

TPositionFieldId

aFieldId

)

const

Checks if the landmark contains a specific position field.

Parameters:

aFieldId

The position field.

Returns:: ETrue if the landmark contains the field, otherwise EFalse.

IMPORT_C TPosLmItemId CPosLandmark::LandmarkId

(

)

const

Reads the ID of the landmark entry in the database.

Returns:: The ID of the landmark entry in the database, or KPosLmNullItemId if the landmark has not been added to the database yet.

static IMPORT_C CPosLandmark* CPosLandmark::NewL ( const CPosLandmark & aLandmark ) [static]

Two-phased copy constructor.

Parameters:

[in] aLandmark The landmark to copy.

Returns:: A copy of the specified landmark object.

static IMPORT_C CPosLandmark* CPosLandmark::NewL ( ) [static]

Two-phased constructor.

Returns:: A new instance of this class.

static IMPORT_C CPosLandmark* CPosLandmark::NewLC ( const CPosLandmark & aLandmark ) [static]

Two-phased copy constructor.

Parameters:

[in] aLandmark The landmark to copy.

Returns:: A copy of the specified landmark object.

static IMPORT_C CPosLandmark* CPosLandmark::NewLC ( ) [static]

Two-phased constructor.

Returns:: A new instance of this class.

IMPORT_C TPositionFieldId CPosLandmark::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.

Parameters:

aFieldId

The last position field which was read.

Returns:: The next position field contained by the landmark, or 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 TUint CPosLandmark::NumOfAvailablePositionFields

(

)

const

Returns the number of position fields set in the landmark.

Returns:: The number of position fields set in the landmark.

IMPORT_C void CPosLandmark::RemoveCategory

(

TPosLmItemId

aCategoryId

)

Removes a category from the landmark.

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

Parameters:

aCategoryId

The category to remove

IMPORT_C void CPosLandmark::RemoveLandmarkAttributes

(

TAttributes

aAttributes

)

Removes landmark attributes from the landmark.

Parameters:

aAttributes

A bitmap specifying which landmark attributes to remove.

IMPORT_C void CPosLandmark::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:

aFieldId

The position field to remove.

IMPORT_C void CPosLandmark::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:

aCoverageRadius

The coverage radius.

IMPORT_C void CPosLandmark::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.

Parameters:

`[in]`	aIconFileName	The full icon file name.
`[in]`	aIconIndex	The index of the icon within the icon file.
`[in]`	aIconMaskIndex	The index of the icon mask within the icon file.

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.

IMPORT_C void CPosLandmark::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 "".

Parameters:

[in] aLandmarkDescription The landmark description.

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

void CPosLandmark::SetLandmarkIdL

(

TPosLmItemId

aId

)

IMPORT_C void CPosLandmark::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 "".

Parameters:

[in] aLandmarkName The landmark name.

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

void CPosLandmark::SetPartialL

(

TBool

aPartial

)

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

Sets a position field in the landmark.

Parameters:

`[in]`	aFieldId	The position field to set.
`[in]`	aFieldValue	The new value for the position field.

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

IMPORT_C void CPosLandmark::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.

Parameters:

[in] aPosition The landmark position.

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

The documentation for this class was generated from the following file:

epos_cposlandmark.h

Copyright © Nokia Corporation 2001-2008