CPosLandmarkDatabase 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_cposlandmarkdatabase.h>

Detailed Description

Handle to a landmark database.

This class contains functions for creating, iterating, reading, modifying and deleting landmarks.

Operations on the database may fail with error code KErrCorrupt if the database is damaged. The client can try to recover the database by calling CPosLandmarkDatabase::InitializeL().

Operations on the database may fail with error code KErrLocked if another client is writing to the database. Write operations can also fail with this error code if another client is currently reading from the database.

If CPosLandmarkDatabase is used, the client must call the global function ReleaseLandmarkResources() before terminating in order to release all used landmark resources, otherwise the client may receive an ALLOC panic.

NetworkServices capability is required for remote databases.


Public Types
typedef TUint	TTransferOptions
	Bitmap for specifying a group of transfer options defined by _TAttributes.
enum	_TTransferOptions { EDefaultOptions = 0, EIncludeCategories = 0x01, EIncludeGlobalCategoryNames = 0x02, ESupressCategoryCreation = 0x04 }
	Specifies options for importing and exporting landmarks. More...
Public Member Functions
virtual IMPORT_C	~CPosLandmarkDatabase ()
	Destructor.
virtual TBool	IsInitializingNeeded () const =0
	Checks if the database is in need of initialization.
virtual CPosLmOperation *	InitializeL ()=0
	Initializes the database.
virtual CPosLandmark *	ReadLandmarkLC (TPosLmItemId aLandmarkId)=0
	Reads a landmark from the database.
virtual CPosLmItemIterator *	LandmarkIteratorL ()=0
	Returns an object for iterating the landmarks in the database.
virtual CPosLmItemIterator *	LandmarkIteratorL (const TPosLmSortPref &aSortPref)=0
	Returns an object for iterating the landmarks in the database.
virtual TPosLmItemId	AddLandmarkL (CPosLandmark &aLandmark)=0
	Adds a new landmark to the database and returns its ID.
virtual void	UpdateLandmarkL (const CPosLandmark &aLandmark)=0
	Updates a landmark in the database.
virtual void	RemoveLandmarkL (TPosLmItemId aLandmarkId)=0
	Removes a landmark from the database.
virtual CPosLmOperation *	RemoveLandmarksL (const RArray< TPosLmItemId > &aLandmarkIdArray)=0
	Removes a set of landmarks from the database.
virtual CPosLmOperation *	RemoveAllLandmarksL ()=0
	Removes all landmarks from the database.
virtual CPosLmPartialReadParameters *	PartialReadParametersLC ()=0
	Returns the partial read parameters for this database handle.
virtual void	SetPartialReadParametersL (const CPosLmPartialReadParameters &aPartialSettings)=0
	Sets the partial read parameters for this database handle.
virtual CPosLandmark *	ReadPartialLandmarkLC (TPosLmItemId aLandmarkId)=0
	Reads partial data from a landmark in the database.
virtual CPosLmOperation *	PreparePartialLandmarksL (const RArray< TPosLmItemId > &aLandmarkIdArray)=0
	Reads partial data from a set of landmarks in the database.
virtual CArrayPtr< CPosLandmark > *	TakePreparedPartialLandmarksL (CPosLmOperation *aPreparePartialLandmarkOperation)=0
	Fetches the result from a call to PreparePartialLandmarksL.
virtual HBufC *	DatabaseUriLC ()=0
	Returns a URI which points to the landmark database storage.
virtual TSize	SizeL ()=0
	Returns size information for the database.
virtual CPosLmOperation *	CompactL ()=0
	Compacts the landmark database.
virtual void	NotifyDatabaseEvent (TPosLmEvent &aEvent, TRequestStatus &aStatus)=0
	Listens for database events.
virtual TInt	CancelNotifyDatabaseEvent ()=0
	Cancels a call to NotifyDatabaseEvent.
virtual CPosLmOperation *	ExportLandmarksL (CPosLandmarkEncoder &aLandmarkEncoder, const RArray< TPosLmItemId > &aLandmarkIdArray, TTransferOptions aTransferOptions)=0
	Exports a number of landmarks.
virtual CPosLmOperation *	ImportLandmarksL (CPosLandmarkParser &aLandmarkParser, TTransferOptions aTransferOptions)=0
	Import a set of landmarks.
virtual CPosLmOperation *	ImportLandmarksL (CPosLandmarkParser &aLandmarkParser, const RArray< TUint > &aLandmarkSelection, TTransferOptions aTransferOptions)=0
	Import a set of landmarks.
virtual CPosLmItemIterator *	ImportedLandmarksIteratorL (CPosLmOperation *aImportOperation)=0
	Returns an object for iterating the landmarks added in an import operation.
TUid	ImplementationId () const
Static Public Member Functions
static IMPORT_C CPosLandmarkDatabase *	OpenL ()
	Opens the default landmark database.
static IMPORT_C CPosLandmarkDatabase *	OpenL (const TDesC &aDatabaseUri)
	Opens a specific landmark database.
Protected Member Functions
IMPORT_C	CPosLandmarkDatabase ()
Data Structures
struct	TSize
	Encapsulates size information for a landmark database. More...

Member Typedef Documentation

typedef TUint CPosLandmarkDatabase::TTransferOptions

Bitmap for specifying a group of transfer options defined by _TAttributes.

Member Enumeration Documentation

enum CPosLandmarkDatabase::_TTransferOptions

Specifies options for importing and exporting landmarks.

Enumerator:

EDefaultOptions	None of the transfer option flags are set.
EIncludeCategories	Export/Import the categories of the landmarks.
EIncludeGlobalCategoryNames	Only useful in combination with EIncludeCategories. If set, global category names will be used in export/import even if user has renamed them. For import it means that the names of the global categories in the database are overwritten by the imported names. For export it means that predefined names of global categories in the current language will be exported instead of user-defined names.
ESupressCategoryCreation	Only useful in combination with EIncludeCategories. If set, no new categories are created in the database when importing landmarks. This means that connections from imported landmarks will be established only to already existing categories, according to the import information.

Constructor & Destructor Documentation

virtual IMPORT_C CPosLandmarkDatabase::~CPosLandmarkDatabase ( ) [virtual]

Destructor.

IMPORT_C CPosLandmarkDatabase::CPosLandmarkDatabase ( ) [protected]

Member Function Documentation

virtual TPosLmItemId CPosLandmarkDatabase::AddLandmarkL ( CPosLandmark & aLandmark ) [pure virtual]

Adds a new landmark to the database and returns its ID.

Precondition:: Database is initialized (see IsInitializingNeeded).

A landmark can contain the IDs of the categories it belongs to. If any of these categories does not exist in the database, the add operation will still complete successfully but the category which was not found will be ignored.

This function requires ReadUserData and WriteUserData capabilities.

Postcondition:: Landmark is added to the database and landmark object has database item set (CPosLandmark::LandmarkId()).

Parameters:

[in,out] aLandmark The landmark to add.

Returns:: The ID of the new landmark.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual TInt CPosLandmarkDatabase::CancelNotifyDatabaseEvent ( ) [pure virtual]

Cancels a call to NotifyDatabaseEvent.

This function requires ReadUserData capability.

Returns:: KErrNone if the request was successfully cancelled, otherwise a system wide error code.

virtual CPosLmOperation* CPosLandmarkDatabase::CompactL ( ) [pure virtual]

Compacts the landmark database.

Precondition:: Database is initialized (see IsInitializingNeeded).

Compaction means that any unused space in the database is removed.

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

The client takes ownership of the returned operation object.

This function requires ReadUserData and WriteUserData capabilities.

Returns:: A handle to the operation.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual HBufC* CPosLandmarkDatabase::DatabaseUriLC ( ) [pure virtual]

Returns a URI which points to the landmark database storage.

The URI may point to a file in the terminal file system or on a remote file.

The client takes ownership of the returned descriptor.

Returns:: The database URI. The URI is put on the cleanup stack.

virtual CPosLmOperation* CPosLandmarkDatabase::ExportLandmarksL	(	CPosLandmarkEncoder &	aLandmarkEncoder,
		const RArray< TPosLmItemId > &	aLandmarkIdArray,
		TTransferOptions	aTransferOptions
	)	`[pure virtual]`

Exports a number of landmarks.

Precondition:: Database is initialized (see IsInitializingNeeded).

To export a set of landmarks, the client must first create a CPosLandmarkEncoder object for the landmark content format in which the landmarks should be encoded. The client can add some information of the landmark collection in the encoder as well.

The client must also provide a list of the landmarks which should be exported. If one of the landmarks are not found in the database, the returned operation fails with error code KErrNotFound.

The client does not have to add any landmarks to the encoder object. This function will add the ones specified in the ID array.

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that only a subset of the landmarks have been exported.

The client takes ownership of the returned operation object.

When all landmarks have been exported the client must finalize encoding by calling CPosLandmarkEncoder::FinalizeEncodingL.

This function requires ReadUserData capability.

Parameters:

`[in]`	aLandmarkEncoder	A landmark encoder object.
`[in]`	aLandmarkIdArray	The landmarks which should be exported.
`[in]`	aTransferOptions	A bitmap representing the options for the export operation. The bitmap values are defined by _TTransferOptions.

Returns:: A handle to the operation.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

Panic:: "Landmarks Client"-EPosLmInvalidArgument Client specified invalid transfer option values.

TUid CPosLandmarkDatabase::ImplementationId

(

)

const

virtual CPosLmItemIterator* CPosLandmarkDatabase::ImportedLandmarksIteratorL ( CPosLmOperation * aImportOperation ) [pure virtual]

Returns an object for iterating the landmarks added in an import operation.

To import landmarks ImportLandmarksL is used.

If ImportedLandmarksIteratorL is called before the ImportLandmarksL operation has completed, the iterator will iterate the landmarks imported so far. Landmarks imported after the iterator is obtained will not affect the iterator. A new iterator must be obtained to iterate these new landmarks.

The client takes ownership of the returned iterator object.

Parameters:

[in] aImportOperation This object is returned by ImportLandmarksL methods.

Returns:: An object for iterating the landmarks added in the latest import operation.

virtual CPosLmOperation* CPosLandmarkDatabase::ImportLandmarksL	(	CPosLandmarkParser &	aLandmarkParser,
		const RArray< TUint > &	aLandmarkSelection,
		TTransferOptions	aTransferOptions
	)	`[pure virtual]`

Import a set of landmarks.

Precondition:: Database is initialized (see IsInitializingNeeded).

To import landmark content, the client must first create a parser object which can parse the landmark content. The client does not have to call CPosLandmarkParser::ParseContentL first. If the content is not already parsed, this will be handled by the import operation.

In this overload of the function, the client can pass an array defining a subset of the landmarks in the parser object. This way the client can select to import only a part of the landmark content.

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that only a subset of the landmarks have been imported.

The client takes ownership of the returned operation object.

After completion ImportedLandmarksIteratorL can be called to retrieve the IDs of the added landmarks.

The NextStep function in the operation object cannot be executed synchronously using User::WaitForRequest. Doing so may cause the operation to hang. NextStep must be run using an active object for this operation.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

`[in]`	aLandmarkParser	An object which can parse landmark content.
`[in]`	aLandmarkSelection	An array defining which of the parsed landmarks to import. The array items refer to the order in which CPosLandmarkParser accesses the landmarks. 0 means the first parsed landmark, 1 means the second, etc. If the parser supports indexing, these numbers correspond to the index values used to access the landmarks in CPosLandmarkParser::LandmarkLC. The index values must be less than the number of landmarks accessed by the parser, otherwise the operation object will panic with error code `EPosInvalidIndex` during execution. `Note:` The indexes can be used regardless of whether the parser supports indexing or not.
	aTransferOptions	A bitmap representing the options for the import operation. The bitmap values are defined by _TTransferOptions.

Returns:: A handle to the operation.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

Panic:: "Landmarks Client"-EPosLmInvalidArgument Client specified invalid transfer option values.

virtual CPosLmOperation* CPosLandmarkDatabase::ImportLandmarksL	(	CPosLandmarkParser &	aLandmarkParser,
		TTransferOptions	aTransferOptions
	)	`[pure virtual]`

Import a set of landmarks.

Precondition:: Database is initialized (see IsInitializingNeeded).

To import landmark content, the client must first create a parser object which can parse the landmark content. The client does not have to call CPosLandmarkParser::ParseContentL first. If the content is not already parsed, this will be handled by the import operation.

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that only a subset of the landmarks have been imported.

The client takes ownership of the returned operation object.

After completion ImportedLandmarksIteratorL can be called to retrieve the IDs of the added landmarks.

The NextStep function in the operation object cannot be executed synchronously using User::WaitForRequest. Doing so may cause the operation to hang. NextStep must be run using an active object for this operation.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

`[in]`	aLandmarkParser	An object which can parse landmark content.
`[in]`	aTransferOptions	A bitmap representing the options for the import operation. The bitmap values are defined by _TTransferOptions.

Returns:: A handle to the operation.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

Panic:: "Landmarks Client"-EPosLmInvalidArgument Client specified invalid transfer option values.

virtual CPosLmOperation* CPosLandmarkDatabase::InitializeL ( ) [pure virtual]

Initializes the database.

This function may have to be called right after the database is opened. IsInitializingNeeded can be called to find out if initialization is needed.

If the database becomes damaged, the client can call InitializeL to try to recover the database.

It is ok to call even if initialization is not needed. In this case, the operation will not do anything.

If the database needs to be initialized, the client must call InitializeL, otherwise the database may not be possible to access. Access functions may leave with KErrPosLmNotInitialized.

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that the database is not yet initialized.

The client takes ownership of the returned operation object.

This function requires ReadUserData capability.

Returns:: A handle to the operation.

virtual TBool CPosLandmarkDatabase::IsInitializingNeeded ( ) const [pure virtual]

Checks if the database is in need of initialization.

If the database needs to be initialized, the client must call InitializeL, otherwise the database may not be possible to access. Access functions may leave with KErrPosLmNotInitialized.

Initialization may be needed also if the database becomes damaged. The client can then try to call InitializeL to try to recover the database.

Returns:: ETrue if the database is in need of initialization, otherwise EFalse.

virtual CPosLmItemIterator* CPosLandmarkDatabase::LandmarkIteratorL ( const TPosLmSortPref & aSortPref ) [pure virtual]

Returns an object for iterating the landmarks in the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

The iterator object is reset, so that the first CPosLmItemIterator::NextL call will return the first landmark ID.

This overload of the iterator function takes a sort preference object as input. The sort preference object specifies how the landmarks should be sorted by the iterator. Only sorting by landmark name is supported.

The client takes ownership of the returned iterator object.

This function requires ReadUserData capability.

Parameters:

[in] aSortPref A sort preference object.

Returns:: The landmark iterator.

Leave:: KErrNotSupported Sorting by another attribute than name is requested.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual CPosLmItemIterator* CPosLandmarkDatabase::LandmarkIteratorL ( ) [pure virtual]

Returns an object for iterating the landmarks in the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

The iterator object is reset, so that the first CPosLmItemIterator::NextL call will return the first landmark ID.

The client takes ownership of the returned iterator object.

This function requires ReadUserData capability.

Returns:: The landmark iterator.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual void CPosLandmarkDatabase::NotifyDatabaseEvent	(	TPosLmEvent &	aEvent,
		TRequestStatus &	aStatus
	)	`[pure virtual]`

Listens for database events.

This function is asynchronous and it will complete the request status when an event occurs. At this time aEvent input parameter is updated and the client can read event information from it.

Event listening can be cancelled by calling CancelNotifyDatabaseEvent.

This function requires ReadUserData capability.

Parameters:

`[out]`	aEvent	Upon completion contains the event information.
`[out]`	aStatus	Upon completion contains status of the request. `KErrNotSupported` if events are not supported. `KErrNone` if an event occured, otherwise an error code if some error was encountered.

Panic:: "Landmarks Client"-EPosEventNotifierAlreadyHasOutstandingRequest Client already has an outstanding NotifyDatabaseEvent request.

static IMPORT_C CPosLandmarkDatabase* CPosLandmarkDatabase::OpenL ( const TDesC & aDatabaseUri ) [static]

Opens a specific landmark database.

The client refers to a database by URI. The URI consists of a protocol specifier and the database location: "protocol://location". If the client does not specify a protocol, "file://" will be assumed.

For local landmark databases, the URI consists of the drive and the database file name, e.g. "c:landmarks.ldb". The path cannot be specified by the client. The extension of the database file name must be "ldb" otherwise the client will get the error KErrArgument.

If the client specifies a local database and does not specify the drive letter, e.g. "landmarks.ldb", default database drive will be assumed.

The client takes ownership of the returned database handle.

The database may have to be initialized before it can be used, see IsInitializingNeeded and InitializeL.

This function requires ReadUserData capability.

Parameters:

[in] aDatabaseUri The URI of the database to open.

Returns:: A handle to the open database.

Leave:: KErrArgument Extension of the local database name is not "ldb".

Leave:: KErrNotSupported The protocol specified in URI is not supported.

static IMPORT_C CPosLandmarkDatabase* CPosLandmarkDatabase::OpenL ( ) [static]

Opens the default landmark database.

The client takes ownership of the returned database handle.

The database may have to be initialized before it can be used, see IsInitializingNeeded and InitializeL.

This function requires ReadUserData capability.

Returns:: A handle to the open database.

virtual CPosLmPartialReadParameters* CPosLandmarkDatabase::PartialReadParametersLC ( ) [pure virtual]

Returns the partial read parameters for this database handle.

Partial read parameters are used to define which landmark data should be returned when ReadPartialLandmarkLC is called.

The client takes ownership of the returned parameter object.

Returns:: The current partial read parameters.

virtual CPosLmOperation* CPosLandmarkDatabase::PreparePartialLandmarksL ( const RArray< TPosLmItemId > & aLandmarkIdArray ) [pure virtual]

Reads partial data from a set of landmarks in the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

Partial settings define which landmark data should be read. Partial read attributes are defined by calling SetPartialReadParametersL. If no partial read parameters have been set, the landmarks will not contain any attributes.

Note that the returned data may be very big if all attributes in each landmark are requested. A typical use for this function is to retrieve the names for a set of landmarks.

When the request is completed, the result can be retrieved by calling TakePreparedPartialLandmarksL.

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

The client takes ownership of the returned operation object.

While preparing landmark information, this operation will acquire a read-lock on the database.

This function requires ReadUserData capability.

Parameters:

[in] aLandmarkIdArray An array with IDs of the landmarks to read.

Returns:: A handle to the operation.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual CPosLandmark* CPosLandmarkDatabase::ReadLandmarkLC ( TPosLmItemId aLandmarkId ) [pure virtual]

Reads a landmark from the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

The client takes ownership of the returned database landmark object.

This function requires ReadUserData capability.

Parameters:

The

ID of the landmark to read.

Returns:: The requested landmark. The landmark object is put on the cleanup stack.

Leave:: KErrNotFound The requested landmark does not exist in the database.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual CPosLandmark* CPosLandmarkDatabase::ReadPartialLandmarkLC ( TPosLmItemId aLandmarkId ) [pure virtual]

Reads partial data from a landmark in the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

Partial settings define which landmark data should be returned in this call. Partial read attributes are defined by calling SetPartialReadParametersL. If no partial read parameters have been set, the landmarks will not contain any attributes.

The client takes ownership of the returned landmark object.

This function requires ReadUserData capability.

Parameters:

The

ID of the landmark to read.

Returns:: The requested landmark. The landmark object will only contain the attributes defined in the partial read attributes. The landmark object is put on the cleanup stack.

Leave:: KErrNotFound The requested landmark does not exist in the database.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual CPosLmOperation* CPosLandmarkDatabase::RemoveAllLandmarksL ( ) [pure virtual]

Removes all landmarks from the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that only a subset of the landmarks have been deleted.

The client takes ownership of the returned operation object.

While removing landmarks, this operation will acquire a write-lock on the database.

This function requires ReadUserData and WriteUserData capabilities.

Returns:: A handle to the operation.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual void CPosLandmarkDatabase::RemoveLandmarkL ( TPosLmItemId aLandmarkId ) [pure virtual]

Removes a landmark from the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

If the landmark does not exist in the database, nothing happens.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

aLandmarkId

The ID of the landmark to remove.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual CPosLmOperation* CPosLandmarkDatabase::RemoveLandmarksL ( const RArray< TPosLmItemId > & aLandmarkIdArray ) [pure virtual]

Removes a set of landmarks from the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

If any of the specified landmarks don't exist in the database, nothing happens for those landmarks.

The function returns an operation object which can be run in incremental mode. If it is run incrementally the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that only a subset of the landmarks have been deleted.

The client takes ownership of the returned operation object.

While removing landmarks, this operation will acquire a write-lock on the database.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

[in] aLandmarkIdArray The IDs of the landmarks to remove.

Returns:: A handle to the operation.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

virtual void CPosLandmarkDatabase::SetPartialReadParametersL ( const CPosLmPartialReadParameters & aPartialSettings ) [pure virtual]

Sets the partial read parameters for this database handle.

Partial read parameters are used to define which landmark data should be returned when ReadPartialLandmarkLC is called.

Parameters:

[in] aPartialSettings The new partial read parameters.

virtual TSize CPosLandmarkDatabase::SizeL ( ) [pure virtual]

Returns size information for the database.

This function requires ReadUserData capability.

Returns:: Size information for the database.

virtual CArrayPtr<CPosLandmark>* CPosLandmarkDatabase::TakePreparedPartialLandmarksL ( CPosLmOperation * aPreparePartialLandmarkOperation ) [pure virtual]

Fetches the result from a call to PreparePartialLandmarksL.

Precondition:: A call to this function must be preceeded by successful call to PreparePartialLandmarksL.

The returned array will have the same length as the ID array passed in the PreparePartialLandmarksL call and it will have the same order.

If reading a landmark failed during preparation, the corresponding pointer value in the returned array will be NULL. For instance, reading can fail if the specified ID does not exist in the database.

The client takes ownership of the returned array object including the contained landmark objects.

Parameters:

[in] aPreparePartialLandmarkOperation The operation object returned by the PreparePartialLandmarksL function.

Returns:: An array containing the prepared partial landmark objects.

Leave:: KErrNotFound PreparePartialLandmarksL hasn't been called yet or it didn't succeed or this function has been called already since then.

virtual void CPosLandmarkDatabase::UpdateLandmarkL ( const CPosLandmark & aLandmark ) [pure virtual]

Updates a landmark in the database.

Precondition:: Database is initialized (see IsInitializingNeeded).

Only landmark objects containing full landmark information can be used to update a landmark. If a partial landmark (see ReadPartialLandmarkLC and CPosLandmark::IsPartial) is passed to this function it will leave with KErrArgument.

Note that any updates in the database made since the landmark object was read from the database will be overwritten by this operation.

A landmark can contain the IDs of the categories it belongs to. If any of these categories does not exist in the database, the update operation will still complete successfully but the category which was not found will be ignored.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

[in] aLandmark The new landmark data.

Leave:: KErrArgument A partial landmark is passed.

Leave:: KErrAccessDenied The database is read-only.

Leave:: KErrPosLmNotInitialized Database is not yet initialized.

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

epos_cposlandmarkdatabase.h

Copyright © Nokia Corporation 2001-2008