CPosLmMultiDbSearch Class Reference

API published in: S60 3rd Ed

Link against: eposlmsearchlib.lib eposlmmultidbsearch.lib

Capability Information

Required Capabilities

None

Exceptions

The capability ReadUserData is required in:

CPosLandmarkSearch::StartLandmarkSearchL( const CPosLmSearchCriteria & aCriteria, TBool aSearchOnlyPreviousMatches = EFalse );

CPosLandmarkSearch::StartLandmarkSearchL( const CPosLmSearchCriteria & aCriteria, const TPosLmSortPref & aSortPref, TBool aSearchOnlyPreviousMatches = EFalse );

CPosLandmarkSearch::StartCategorySearchL( const CPosLmSearchCriteria & aCriteria, CPosLmCategoryManager::TCategorySortPref aSortPref, TBool aSearchOnlyPreviousMatches = EFalse );

CPosLmMultiDbSearch::StartLandmarkSearchL( const CPosLmSearchCriteria & aCriteria, TBool aSearchOnlyPreviousMatches = EFalse );

CPosLmMultiDbSearch::StartLandmarkSearchL( const CPosLmSearchCriteria & aCriteria, const TPosLmSortPref & aSortPref, TBool aSearchOnlyPreviousMatches = EFalse );

CPosLmMultiDbSearch::StartCategorySearchL( const CPosLmSearchCriteria & aCriteria, CPosLmCategoryManager::TCategorySortPref aSortPref, TBool aSearchOnlyPreviousMatches = EFalse );

Other Information

The capability NetworkServices is required to work with remote databases.

#include <epos_cposlmmultidbsearch.h>

Detailed Description

CPosLmMultiDbSearch is used to perform searches for landmarks or landmark categories in multiple databases.

The client can specify which databases to search.

Some criterion classes are used for searching for landmarks (e.g. CPosLmCategoryCriteria is used for searching for landmarks which contain a certain category) and some are used to search for landmark categories (e.g. CPosLmCatNameCriteria is used to search for landmark categories by specifying a category name).

Searches can be run in incremental mode. StartLandmarkSearchL and StartCategorySearchL both return a CPosLmOperation object which is used to execute the search. If it is sufficient to run the search synchronously, the client only has to call CPosLmOperation::ExecuteL. If it is run incrementally the client can supervise the progress of the operation. The CPosLmOperation::NextStep function in the search operations cannot be executed synchronously using User::WaitForRequest. Doing so may cause the operation to hang. CPosLmOperation::NextStep must be run using an active object. The client can cancel the search by deleting the CPosLmOperation object.

By default, these functions start a new search, but the client can specify that only previous matches should be searched. This can be used to refine the search when there are many matches.

It is not allowed to search by category item ID in CPosLmCategoryCriteria since an item ID is only valid in one landmark database.

It is only allowed to specify a named category, a global category, or no category. It is not allowed to search with CPosLmIdListCriteria since an item ID is only valid in one landmark database. In both cases the search functions leave with error code KErrArgument.

During the search execution, a read-lock is acquired for each database. Only one search can be performed at a time by the single instance of the class. If a search is already running, the search function leaves with error code KErrInUse.

After search completion, the client can make a second search and specify that only the matches from the previous search shall be considered.

The client can also set a limit on how many search matches should be returned (see SetMaxNumOfMatches).

The client retrieves the matches from the search by requesting an iterator (see MatchIteratorL) or by using display data (see SetDisplayData).

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

Version:

Revision: 1.17

Date: 2005/07/07 13:40:10


Public Member Functions
virtual IMPORT_C	~CPosLmMultiDbSearch ()
	Destructor.
IMPORT_C void	SetDatabasesToSearchL (const CDesCArray &aDatabaseList)
	Specifies the list of databases that should be used in the search.
IMPORT_C CDesCArray *	DatabasesToSearchL ()
	Returns the list of databases to search.
IMPORT_C void	SetMaxNumOfMatches (TInt aMaxNumOfMatches=KPosLmMaxNumOfMatchesUnlimited)
	Sets the maximum number of search matches limit for each database.
IMPORT_C CPosLmOperation *	StartLandmarkSearchL (const CPosLmSearchCriteria &aCriteria, TBool aSearchOnlyPreviousMatches=EFalse)
	Starts a landmark search.
IMPORT_C CPosLmOperation *	StartLandmarkSearchL (const CPosLmSearchCriteria &aCriteria, const TPosLmSortPref &aSortPref, TBool aSearchOnlyPreviousMatches=EFalse)
	Starts a landmark search.
IMPORT_C CPosLmOperation *	StartCategorySearchL (const CPosLmSearchCriteria &aCriteria, CPosLmCategoryManager::TCategorySortPref aSortPref, TBool aSearchOnlyPreviousMatches=EFalse)
	Starts a search for landmark categories.
IMPORT_C TUint	NumOfSearchErrors () const
	Returns the number of errors encountered during the search.
IMPORT_C void	GetSearchError (TUint aErrorIndex, TSearchError &aSearchError) const
	Returns errors encountered in the search.
IMPORT_C TUint	TotalNumOfMatches () const
	Returns the total number of matches so far in the search.
IMPORT_C TUint	NumOfMatches (TUint aDatabaseIndex) const
	Returns the number of matches so far in the search for a database specified by index.
IMPORT_C TUint	NumOfDatabasesToSearch () const
	Returns the number of databases involved in the search.
IMPORT_C TPtrC	DatabaseUriPtr (TUint aDatabaseIndex) const
	Returns the URI of a database involved in the search.
IMPORT_C CPosLmItemIterator *	MatchIteratorL (TUint aDatabaseIndex)
	Creates an iterator object to iterate the matching landmarks or categories from one of the databases involved in the search.
IMPORT_C void	SetDisplayData (CPosLmDisplayData &aData)
	Display data can be used as an alternative way to get result from a database search.
IMPORT_C void	UnsetDisplayData ()
	Unsets display data.
IMPORT_C TInt	MaxNumOfMatches () const
	Retrieves the maximum number of search matches limit for each database.
TBool	ToBeSearched (TUint aDatabaseIndex) const
CPosLandmarkDatabase *	DatabaseL (TUint aDatabaseIndex)
CPosLandmarkSearch *	SearcherL (TUint aDatabaseIndex)
void	SearchStarted (TUint aDatabaseIndex)
void	SearchExecutedL (TUint aDatabaseIndex, const CPosLmMultiDbSortPref &aSortPref)
void	AddSearchError (TUint aDatabaseIndex, TInt aErrorCode)
void	HandleSearchOperationCompleted ()
Static Public Member Functions
static IMPORT_C CPosLmMultiDbSearch *	NewL (const CDesCArray &aDatabaseList)
	Two-phased constructor.
Data Structures
struct	TSearchError
	Struct containing a search error. More...

Constructor & Destructor Documentation

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

Destructor.

Member Function Documentation

void CPosLmMultiDbSearch::AddSearchError	(	TUint	aDatabaseIndex,
		TInt	aErrorCode
	)

CPosLandmarkDatabase* CPosLmMultiDbSearch::DatabaseL

(

TUint

aDatabaseIndex

)

IMPORT_C CDesCArray* CPosLmMultiDbSearch::DatabasesToSearchL

(

)

Returns the list of databases to search.

Ownership is transferred to the caller.

Returns:: The list of databases to search.

IMPORT_C TPtrC CPosLmMultiDbSearch::DatabaseUriPtr

(

TUint

aDatabaseIndex

)

const

Returns the URI of a database involved in the search.

The client specifies an index of the database URI to retrieve. The index must be strictly less than NumOfDatabasesToSearch, otherwise this function will panic with code EPosInvalidIndex.

Parameters:

[in] aDatabaseIndex The index of the database URI to retrieve.

Returns:: A pointer to the database URI descriptor. This pointer is only valid until SetDatabasesToSearch is called, or the CPosLmMultiDbSearch object is destroyed, whichever happens first.

IMPORT_C void CPosLmMultiDbSearch::GetSearchError	(	TUint	aErrorIndex,
		TSearchError &	aSearchError
	)	const

Returns errors encountered in the search.

The client specifies an index of the error to retrieve. The index must be strictly less than NumOfSearchErrors, otherwise this function panics with code EPosInvalidIndex. Whenever a new search is started this function must be called again to retrieve error codes, if any.

Parameters:

`[in]`	aErrorIndex	The index of the error to retrieve.
`[out]`	aSearchError	On return, contains the search error.

void CPosLmMultiDbSearch::HandleSearchOperationCompleted

(

)

IMPORT_C CPosLmItemIterator* CPosLmMultiDbSearch::MatchIteratorL

(

TUint

aDatabaseIndex

)

Creates an iterator object to iterate the matching landmarks or categories from one of the databases involved in the search.

The database to get search matches for is specified by index. The index must be strictly less than NumOfDatabasesToSearch, otherwise this function will panic with code EPosInvalidIndex. The URI of the database can be retrieved by calling DatabaseUriPtr.

This function can also be called during a search in order to read the matches encountered so far. Note that the iterator will not iterate any new matches. If new matches are found, a new iterator needs to be created to retrieve them. The previous matches will also be included.

If the client has started a search, but no matches have been found yet in the database, an empty iterator is returned.

If a sort preference was specified when the search was started, the landmarks or categories will be sorted when the search is complete but the items are not necessarily sorted if this function is called during a search.

The client takes ownership of the returned iterator object.

Note: The iterator iterates matches in CPosLmMultiDbSearch. It cannot be used after the search object has been deleted.

Parameters:

aDatabaseIndex

The index of the database to get search matches for.

Returns:: A search results iterator.

IMPORT_C TInt CPosLmMultiDbSearch::MaxNumOfMatches

(

)

const

Retrieves the maximum number of search matches limit for each database.

By default the maximum number of matches is unlimited.

Returns:: The maximum number of search matches for each landmark database involved in the search or KPosLmMaxNumOfMatchesUnlimited if unlimited.

static IMPORT_C CPosLmMultiDbSearch* CPosLmMultiDbSearch::NewL ( const CDesCArray & aDatabaseList ) [static]

Two-phased constructor.

Leaves with KErrArgument if the database list is empty.

Parameters:

[in] aDatabaseList An array containing the URIs of the landmark databases to be used in the search.

Returns:: A new instance of this class.

IMPORT_C TUint CPosLmMultiDbSearch::NumOfDatabasesToSearch

(

)

const

Returns the number of databases involved in the search.

Returns:: The number of databases involved in the search.

IMPORT_C TUint CPosLmMultiDbSearch::NumOfMatches

(

TUint

aDatabaseIndex

)

const

Returns the number of matches so far in the search for a database specified by index.

The index must be strictly less than NumOfDatabasesToSearch, otherwise this function will panic with code EPosInvalidIndex. The URI of the database can be retrieved by calling DatabaseUriPtr.

This function can also be called during a search operation.

Parameters:

[in] aDatabaseIndex The index of the database to get number of search matches for.

Returns:: The number of matches per database.

IMPORT_C TUint CPosLmMultiDbSearch::NumOfSearchErrors

(

)

const

Returns the number of errors encountered during the search.

This is the same as number of databases in which the search has failed.

Returns:: The number of errors encountered during the search.

CPosLandmarkSearch* CPosLmMultiDbSearch::SearcherL

(

TUint

aDatabaseIndex

)

void CPosLmMultiDbSearch::SearchExecutedL	(	TUint	aDatabaseIndex,
		const CPosLmMultiDbSortPref &	aSortPref
	)

void CPosLmMultiDbSearch::SearchStarted

(

TUint

aDatabaseIndex

)

IMPORT_C void CPosLmMultiDbSearch::SetDatabasesToSearchL

(

const CDesCArray &

aDatabaseList

)

Specifies the list of databases that should be used in the search.

If this function is called and then StartLandmarkSearchL or StartCategorySearchL is called with the flag aSearchOnlyPreviousMatches set, new databases that were not a part of the previous search will generate no matches.

If the client specifies database(s) that do not exist, GetSearchError will report error code KErrNotFound for those databases after the search is started.

This function will leave with KErrInUse if called during a search.

If this function is called after a search has completed, database indexes in the results may become invalid.

If a database is removed from a previously set list, the search result of that database is unavailable after this function is called. Search errors are reset after this function is called.

Leaves with KErrArgument if the database list is empty.

Parameters:

[in] aDatabaseList An array containing the URIs of the landmark databases to be used in the search.

IMPORT_C void CPosLmMultiDbSearch::SetDisplayData

(

CPosLmDisplayData &

aData

)

Display data can be used as an alternative way to get result from a database search.

Landmarks or categories are added to the display data collection during a search depending on the search type.

This function may replace the combination of using MatchIteratorL and reading landmark or category data. Result data is read already during the search and no duplicate access to database is needed.

The display data object will be reset each time a new search is started. No items during the search are removed from the collection. New found matches can be added every time next search step is completed, see CPosLmDisplayData::NewItemIndex.

If the client sets display data during an ongoing search, this function panics with code EPosSearchOperationInUse.

The client owns the display data object. If the client deletes it during a search, this may lead to unexpected errors. The client must call UnsetDisplayData before it deletes the display data object.

Search results from all databases are collected in the same displayable data collection. The CPosLmDisplayItem::DatabaseIndex may be used to know which database every displayable item belongs to. The database index matches databases specified in this object, see DatabaseUriPtr.

Parameters:

[in,out] aData The displayable data.

IMPORT_C void CPosLmMultiDbSearch::SetMaxNumOfMatches ( TInt aMaxNumOfMatches = KPosLmMaxNumOfMatchesUnlimited )

Sets the maximum number of search matches limit for each database.

This function is used to limit the number of matches retrieved from each database in the search operation. If the limit is set, the search operation will stop when this limit is reached. By default the maximum number of matches is unlimited.

If a new value for maximum number of matches is set when a search is ongoing, it will not affect the current search. The new maximum will be utilized in the next search.

Parameters:

[in] aMaxNumOfMatches The maximum number of search matches for each landmark database involved in the search.

IMPORT_C CPosLmOperation* CPosLmMultiDbSearch::StartCategorySearchL	(	const CPosLmSearchCriteria &	aCriteria,
		CPosLmCategoryManager::TCategorySortPref	aSortPref,
		TBool	aSearchOnlyPreviousMatches = `EFalse`
	)

Starts a search for landmark categories.

If there are no previous matches and the client specifies that previous matches should be used, this function leaves with error code KErrArgument...

The criterion, which defines if a landmark category is a match, is passed as input to this function.

If a search is already running, this function leaves with error code KErrInUse.

If the search criterion is not valid for landmark category searching, this function leaves with error code KErrArgument.

If the search criterion is not supported, this function leaves with error code KErrNotSupported.

The client takes ownership of the returned operation object.

This function requires ReadUserData capability.

Parameters:

`[in]`	aCriteria	The search criteria.
`[in]`	aSortPref	Sort preference for the search results.
`[in]`	aSearchOnlyPreviousMatches	This flag may be used to perform a search within the results of previous search.

Returns:: A handle to the search operation.

IMPORT_C CPosLmOperation* CPosLmMultiDbSearch::StartLandmarkSearchL	(	const CPosLmSearchCriteria &	aCriteria,
		const TPosLmSortPref &	aSortPref,
		TBool	aSearchOnlyPreviousMatches = `EFalse`
	)

Starts a landmark search.

This overload of the StartLandmarkSearchL function lets the client define the sort order for the search matches.

Only sorting by landmark name is supported. If the client tries to sort by another attribute, this function leaves with error code KErrNotSupported.

If there are no previous matches and the client specifies that previous matches should be used, this function leaves with error code KErrArgument.

If a search is already running, this function will leave with error code KErrInUse.

If the search criterion is not valid for landmark searching, this function leaves with error code KErrArgument.

If the search criterion is not supported, this function will leave with error code KErrNotSupported.

If CPosLmIdListCriteria is used or CPosLmCategoryCriteria with item ID set, this function leaves with error code KErrArgument.

The client takes ownership of the returned operation object.

This function requires ReadUserData capability.

Parameters:

`[in]`	aCriteria	The search criterion.
`[in]`	aSortPref	A sort preference object.
`[in]`	aSearchOnlyPreviousMatches	This flag may be used to perform a search within the results of previous search.

Returns:: A handle to the search operation.

IMPORT_C CPosLmOperation* CPosLmMultiDbSearch::StartLandmarkSearchL	(	const CPosLmSearchCriteria &	aCriteria,
		TBool	aSearchOnlyPreviousMatches = `EFalse`
	)

Starts a landmark search.

If there are no previous matches and the client specifies that previous matches should be used, this function leaves with error code KErrArgument.

If a search is already running, this function leaves with error code KErrInUse.

If the search criterion is not valid for landmark searching, this function leaves with error code KErrArgument.

If the search criterion is not supported, this function leaves with error code KErrNotSupported.

If CPosLmIdListCriteria is used or CPosLmCategoryCriteria with item ID set, this function leaves with error code KErrArgument.

The client takes ownership of the returned operation object.

This function requires ReadUserData capability.

Parameters:

`[in]`	aCriteria	The search criterion.
`[in]`	aSearchOnlyPreviousMatches	This flag may be used to perform a search within the results of previous search.

Returns:: A handle to the search operation.

TBool CPosLmMultiDbSearch::ToBeSearched

(

TUint

aDatabaseIndex

)

const

IMPORT_C TUint CPosLmMultiDbSearch::TotalNumOfMatches

(

)

const

Returns the total number of matches so far in the search.

This function can also be called during a search operation.

Returns:: The number of search matches.

IMPORT_C void CPosLmMultiDbSearch::UnsetDisplayData

(

)

Unsets display data.

No further data will be added to the display data set with SetDisplayData.

If the client unsets display data during an ongoing search, this function panics with code EPosSearchOperationInUse.

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

epos_cposlmmultidbsearch.h

CPosLmMultiDbSearch Class Reference

Capability Information

Detailed Description

Public Member Functions

Static Public Member Functions

Data Structures

Constructor & Destructor Documentation

Member Function Documentation