CPosLandmarkSearch Class Reference

class CPosLandmarkSearch : public CBase

This class is used to perform searches for landmarks or landmark categories in a landmark database.

To search a landmark database, an instance of this class is created, supplying the database to search. The client creates a criterion object to specify what to search for. There are different criterion classes which all inherit from CPosLmSearchCriteria . For instance, the client can search for landmarks which contain a certain text string by passing a CPosLmTextCriteria .

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 which may contain wild-card characters).

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 run incrementally the client can supervise the progress of the operation. If it is sufficient to run the search synchronously, the client only has to call CPosLmOperation::ExecuteL . 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.

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

NetworkServices capability is required for remote databases.

eposlmsearchlib.lib
Since
S60 3.0

Inherits from

Constructor & Destructor Documentation

CPosLandmarkSearch()

IMPORT_C CPosLandmarkSearch ( ) [protected]

CPosLandmarkSearch(const CPosLandmarkSearch &)

CPosLandmarkSearch ( const CPosLandmarkSearch & ) [private]

Parameters

const CPosLandmarkSearch &

~CPosLandmarkSearch()

IMPORT_C ~CPosLandmarkSearch ( ) [virtual]

Destructor.

Member Functions Documentation

MatchIteratorL()

CPosLmItemIterator * MatchIteratorL ( ) [pure virtual]

Creates an iterator object to iterate the matching landmarks or landmark categories.

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 must be created.

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

Note: If the client has set display data and resets the display data during a search, the sort order in the iterator might be incorrect.

The client takes ownership of the returned iterator object.

Note that the iterator iterates matches in CPosLandmarkSearch . It cannot be used after the search object has been deleted. Make sure to delete the iterator first.

MaxNumOfMatches()

IMPORT_C TInt MaxNumOfMatches ( ) const

Retrieves the maximum number of search matches limit.

By default the maximum number of matches is unlimited.

NewL(CPosLandmarkDatabase &)

IMPORT_C CPosLandmarkSearch * NewL ( CPosLandmarkDatabase & aDatabase ) [static]

Two-phased constructor.

The client takes ownership of the returned search object.

Parameters

CPosLandmarkDatabase & aDatabase The landmark database to search.

NumOfMatches()

TUint NumOfMatches ( ) const [pure virtual]

Returns the number of matches so far in the search.

This function can also be called during a search operation.

SetDisplayData(CPosLmDisplayData &)

void SetDisplayData ( CPosLmDisplayData & aData ) [pure virtual]

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 .

Note: The database index of displayable data items in CPosLmDisplayData will be set to 0 as it has no meaning in a single database search.

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.

Note: If the client resets the display data during a search, the sort order in the iterator might become incorrect.

panic
"Landmarks Client"-EPosSearchOperationInUse The client set display data during an ongoing search.

Parameters

CPosLmDisplayData & aData The displayable data.

SetMaxNumOfMatches(TInt)

IMPORT_C void SetMaxNumOfMatches ( TInt aMaxNumOfMatches =  KPosLmMaxNumOfMatchesUnlimited )

Sets the maximum number of search matches limit.

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

TInt aMaxNumOfMatches =  KPosLmMaxNumOfMatchesUnlimited the maximum number of search matches. KPosLmMaxNumOfMatchesUnlimited means that the number of matches is unlimited.

StartCategorySearchL(const CPosLmSearchCriteria &, CPosLmCategoryManager::TCategorySortPref, TBool)

CPosLmOperation * StartCategorySearchL ( const CPosLmSearchCriteria & aCriteria,
CPosLmCategoryManager::TCategorySortPref aSortPref,
TBool aSearchOnlyPreviousMatches = EFalse
) [pure virtual]

Starts a search for landmark categories.

The criterion which defines whether a landmark category is a match or not is passed as input to this function.

The client takes ownership of the returned operation object.

This function requires ReadUserData capability.

leave
KErrInUse Search is already running.
leave
KErrArgument Search criterion is not valid for category searching.
leave
KErrNotSupported Search criterion is not supported.

Parameters

const CPosLmSearchCriteria & aCriteria The search criterion.
CPosLmCategoryManager::TCategorySortPref aSortPref Sort preference for the search results.
TBool aSearchOnlyPreviousMatches = EFalse This flag may be used to perform a search within the results of previous search.

StartLandmarkSearchL(const CPosLmSearchCriteria &, TBool)

CPosLmOperation * StartLandmarkSearchL ( const CPosLmSearchCriteria & aCriteria,
TBool aSearchOnlyPreviousMatches = EFalse
) [pure virtual]

Starts a search for landmarks.

The client takes ownership of the returned operation object.

This function requires ReadUserData capability.

leave
KErrInUse Search is already running.
leave
KErrNotSupported search criterion is not supported.
leave
KErrArgument Search criterion is not valid for landmark searching.
leave
KErrArgument There are no previous matches and the client specifies that previous matches should be used.

Parameters

const CPosLmSearchCriteria & aCriteria The search criterion.
TBool aSearchOnlyPreviousMatches = EFalse This flag may be used to perform a search within the results of previous search.

StartLandmarkSearchL(const CPosLmSearchCriteria &, const TPosLmSortPref &, TBool)

CPosLmOperation * StartLandmarkSearchL ( const CPosLmSearchCriteria & aCriteria,
const TPosLmSortPref & aSortPref,
TBool aSearchOnlyPreviousMatches = EFalse
) [pure virtual]

Starts a search for landmarks.

This overload of the StartLandmarkSearchL function lets the client define the sort order for the search matches. Only sorting by landmark name is supported.

The client takes ownership of the returned operation object.

This function requires ReadUserData capability.

leave
KErrInUse Search is already running.
leave
KErrArgument Search criterion is not valid for landmark searching.
leave
KErrArgument There are no previous matches and the client specifies that previous matches should be used.
leave
KErrNotSupported Search criterion is not supported.
leave
KErrNotSupported Client tries to sort by other attribute than name.

Parameters

const CPosLmSearchCriteria & aCriteria The search criterion.
const TPosLmSortPref & aSortPref A sort preference object.
TBool aSearchOnlyPreviousMatches = EFalse This flag may be used to perform a search within the results of previous search.

UnsetDisplayData()

void UnsetDisplayData ( ) [pure virtual]

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

panic
"Landmarks Client"-EPosSearchOperationInUse The client unset display data during an ongoing search.

operator=(const CPosLandmarkSearch &)

CPosLandmarkSearch & operator= ( const CPosLandmarkSearch & ) [private]

Parameters

const CPosLandmarkSearch &

Member Data Documentation

TUid iDtorIdKey

TUid iDtorIdKey [private]

TInt iMaxNumOfMatches

TInt iMaxNumOfMatches [private]