CPosLandmarkParser 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_cposlandmarkparser.h>

Detailed Description

Class used for parsing landmark content.

When creating an instance of this class, the type (e.g. the mime type) of the landmark content must be specified. The client will then receive a parser implementation which understands the requested landmark content.

The client specifies landmark content either in a buffer or in a file. The buffer/file is needed until the client no longer uses the parser object for accessing the parsed data. If the buffer/file is deleted or modified, it may not be possible to access the parsed landmark data.

ParseContentL returns a CPosLmOperation which means parsing can be run incrementally. Each call to CPosLmOperation::NextStep parses one landmark. The landmark can be retrieved by calling LandmarkLC.

Optionally, the client can specify that the parser should build an index. An index enables direct access to all landmarks when the content has been fully parsed. The content is fully parsed when CPosLmOperation::NextStep or CPosLmOperation::ExecuteL complete with KErrNone. The LandmarkLC method then can be called with landmark index to directly access any of parsed landmarks.

If CPosLandmarkParser 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.


Public Member Functions
virtual IMPORT_C	~CPosLandmarkParser ()
	Destructor.
virtual void	SetInputBuffer (const TDesC8 &aBuffer)=0
	Sets the buffer to be parsed.
virtual void	SetInputFileL (const TDesC &aFile)=0
	Opens the file with the landmark content to be parsed.
virtual void	SetInputFileHandleL (RFile &aFileHandle)=0
	Sets a handle to the file which should be parsed.
virtual CPosLmOperation *	ParseContentL (TBool aBuildIndex=EFalse)=0
	Parse landmark content.
virtual TUint32	NumOfParsedLandmarks () const =0
	Retrieve the total number of parsed landmarks.
virtual TPosLmCollectionDataId	FirstCollectionDataId () const =0
	Retrieve the first landmark collection data identifier.
virtual TPosLmCollectionDataId	NextCollectionDataId (TPosLmCollectionDataId aCollectionData) const =0
	Retrieve the next landmark collection data identifier.
virtual TPtrC	CollectionData (TPosLmCollectionDataId aDataId) const =0
	Retrieve a specific collection data.
virtual CPosLandmark *	LandmarkLC (TUint aLandmarkIndex=KPosLastParsedLandmark) const =0
	Retrieve a parsed landmark.
virtual CPosLandmarkCategory *	LandmarkCategoryLC (TPosLmItemId aCategoryId) const =0
	Retrieve a landmark category found in a parsed landmark.
Static Public Member Functions
static IMPORT_C CPosLandmarkParser *	NewL (const TDesC8 &aContentMimeType)
	Two-phased constructor.
Protected Member Functions
IMPORT_C	CPosLandmarkParser ()

Constructor & Destructor Documentation

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

Destructor.

IMPORT_C CPosLandmarkParser::CPosLandmarkParser ( ) [protected]

Member Function Documentation

virtual TPtrC CPosLandmarkParser::CollectionData ( TPosLmCollectionDataId aDataId ) const [pure virtual]

Retrieve a specific collection data.

If the requested collection data is not found, this function will return an empty descriptor.

The returned descriptor pointer can be used as long as the parser object exists and is not reset by calling SetInputBuffer, SetInputFileL or SetInputFileHandleL.

Parameters:

[in] aDataId The collection data to retrieve.

Returns:: The requested collection data.

virtual TPosLmCollectionDataId CPosLandmarkParser::FirstCollectionDataId ( ) const [pure virtual]

Retrieve the first landmark collection data identifier.

Landmark collection data is generic information about the landmark collection.

To retrieve the next collection data, call NextCollectionDataId. To retrieve the content of the collection data, call CollectionData.

Returns:: The first landmark collection data ID or EPosLmCollDataNone if there is no landmark collection data detected.

virtual CPosLandmarkCategory* CPosLandmarkParser::LandmarkCategoryLC ( TPosLmItemId aCategoryId ) const [pure virtual]

Retrieve a landmark category found in a parsed landmark.

A landmark may include the IDs of some landmark categories. These categories are retrieved by calling this function.

Note that a category ID in this case is not the ID of a category stored in a database, but the category ID specified in the parsed landmark.

Note that even if the returned category object is modified, the changes will not be included when importing using CPosLandmarkDatabase::ImportLandmarksL.

The client takes ownership of the returned category object.

Parameters:

aCategoryId

The ID of the landmark category.

Returns:: The requested landmark category.

Leave:: KErrNotFound Passed category ID is not part of the parsed landmark content.

virtual CPosLandmark* CPosLandmarkParser::LandmarkLC ( TUint aLandmarkIndex = KPosLastParsedLandmark ) const [pure virtual]

Retrieve a parsed landmark.

The client can supply an index of the landmark to retrieve. Index must be a positive number and less than the number of parsed landmarks, otherwise this function will panic with error code EPosInvalidIndex. If no index has been built, this function will leave with error code KErrNotFound. A landmark index is built by supplying a parameter in ParseContentL.

If aLandmarkIndex parameter is omitted, or KPosLastParsedLandmark is supplied, then this function will retrieve the last parsed landmark. This does not require that an index has been built. Each CPosLmOperation::NextStep call will parse a new landmark.

The client may retrieve the categories of the landmark by calling LandmarkCategoryLC and supplying the category ID which can be obtained from the landmark object.

Note that even if the returned landmark object is modified, the changes will not be included when importing using CPosLandmarkDatabase::ImportLandmarksL.

The client takes ownership of the returned landmark object.

Parameters:

aLandmarkIndex

The index of the landmark to retrieve.

Returns:: The requested landmark.

Leave:: KErrNotFound No index has been built and given index value is not equal to KPosLastParsedLandmark.

Panic:: "Landmarks Client"-EPosInvalidIndex When landmark index is used and given index value is negative and not equal to KPosLastParsedLandmark or greater or equal to the number of parsed landmarks.

static IMPORT_C CPosLandmarkParser* CPosLandmarkParser::NewL ( const TDesC8 & aContentMimeType ) [static]

Two-phased constructor.

The client must specify the type (e.g. the mime type) of the landmark content which should be parsed.

Parameters:

[in] The mime-type of the content to parse.

Returns:: A new instance of this class.

Leave:: KErrNotSupported Content format is not supported.

virtual TPosLmCollectionDataId CPosLandmarkParser::NextCollectionDataId ( TPosLmCollectionDataId aCollectionData ) const [pure virtual]

Retrieve the next landmark collection data identifier.

Landmark collection data is generic information about the landmark collection.

To retrieve the first collection data, call FirstCollectionDataId. To retrieve the content of the collection data, call CollectionData.

Parameters:

[in] aCollectionData Previous landmark collection data ID.

Returns:: The next landmark collection data ID or EPosLmCollDataNone if there is no more landmark collection data detected.

virtual TUint32 CPosLandmarkParser::NumOfParsedLandmarks ( ) const [pure virtual]

Retrieve the total number of parsed landmarks.

This function can also be called while ParseContentL is incrementally executed.

Returns:: The total number of parsed landmarks.

virtual CPosLmOperation* CPosLandmarkParser::ParseContentL ( TBool aBuildIndex = EFalse ) [pure virtual]

Parse landmark content.

Precondition:: Input buffer or file or file handle has been specified.

The landmark content to be parsed is specified in SetInputBuffer, SetInputFileL or SetInputFileHandleL.

Any previously parsed data is discarded.

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.

If the CPosLmOperation object is deleted before the operation is complete, it will not be possible to retrieve any parsed data.

If the content is in unrecognized format, or if the content is invalid, the returned operation will fail with error code KErrPosLmUnknownFormat.

If another content source is set by SetInputBuffer, SetInputFileL or SetInputFileHandleL, then this method needs to be called again to get a new operation object. If the previous operation object is still executed, it will panic with error code EPosLmProtocolBreak.

The client can specify that the parser should build an index while parsing. Building an index uses more memory but it allows unlimited direct access to all parsed data. If the parser does not support indexing, this call will fail with error code KErrNotSupported.

Parameters:

[in] aBuildIndex Specifies if the parser should build an index.

Returns:: A handle to the operation.

Leave:: KErrNotSupported aBuildIndex is ETrue, but parser does not support indexing.

Panic:: "Landmarks Client"-EPosLmProtocolBreak Input buffer or file or file handle not yet specified.

virtual void CPosLandmarkParser::SetInputBuffer ( const TDesC8 & aBuffer ) [pure virtual]

Sets the buffer to be parsed.

The parser does not copy the data which means the buffer must not be deleted or modified until the client no longer uses the parser to access the content.

This call discards any previous parsing result.

Parameters:

[in] aBuffer The buffer containing the landmark content.

virtual void CPosLandmarkParser::SetInputFileHandleL ( RFile & aFileHandle ) [pure virtual]

Sets a handle to the file which should be parsed.

The file needs to be open until the client no longer uses the parser to access the content.

This call discards any previous parsing result.

Parameters:

[in] aFileHandle The handle to the file which should be parsed.

virtual void CPosLandmarkParser::SetInputFileL ( const TDesC & aFile ) [pure virtual]

Opens the file with the landmark content to be parsed.

The file is opened in read-only sharing mode which means the file cannot be deleted or modified until the file is released. The file is released either by deleting the parser object or if SetInputBuffer, SetInputFileL or SetInputFileHandleL is called for some new landmark content data.

This call discards any previous parsing result.

Parameters:

[in] aFile The file containing the landmark content.

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

epos_cposlandmarkparser.h

Copyright © Nokia Corporation 2001-2008