williamr@2: /* williamr@2: * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members williamr@2: * which accompanies this distribution, and is available williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: CPosLandmarkSearch class williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef CPOSLANDMARKSEARCH_H williamr@2: #define CPOSLANDMARKSEARCH_H williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: class CPosLmSearchCriteria; williamr@2: class CPosLmDisplayData; williamr@2: williamr@2: const TInt KPosLmMaxNumOfMatchesUnlimited = -1; williamr@2: williamr@2: /** williamr@2: * This class is used to perform searches for landmarks or landmark categories williamr@2: * in a landmark database. williamr@2: * williamr@2: * To search a landmark database, an instance of this class is created, williamr@2: * supplying the database to search. The client creates a criterion object to williamr@2: * specify what to search for. There are different criterion classes which all williamr@2: * inherit from @ref CPosLmSearchCriteria. For instance, the client can search williamr@2: * for landmarks which contain a certain text string by passing a williamr@2: * @ref CPosLmTextCriteria. williamr@2: * williamr@2: * Some criterion classes are used for searching for landmarks (e.g. williamr@2: * @ref CPosLmCategoryCriteria is used for searching for landmarks which williamr@2: * contain a certain category) and some are used williamr@2: * to search for landmark categories (e.g. @ref CPosLmCatNameCriteria is used williamr@2: * to search for landmark categories by specifying a category name which may williamr@2: * contain wild-card characters). williamr@2: * williamr@2: * Searches can be run in incremental mode. williamr@2: * @ref StartLandmarkSearchL and @ref StartCategorySearchL both return a williamr@2: * @p CPosLmOperation object which is used to execute the search. If it is williamr@2: * run incrementally the client can supervise the progress of the operation. williamr@2: * If it is sufficient to run the search synchronously, the client only has to williamr@2: * call @p CPosLmOperation::ExecuteL. The client can cancel williamr@2: * the search by deleting the @p CPosLmOperation object. williamr@2: * williamr@2: * By default, these functions start a new search, but the client can specify williamr@2: * that only previous matches should be searched. This can be used to refine williamr@2: * the search when there are many matches. williamr@2: * williamr@2: * During the search execution a read-lock is acquired for each database. williamr@2: * williamr@2: * Only one search can be performed at a time by the single instance of williamr@2: * the class. If a search is already running, the search function leaves williamr@2: * with error code @p KErrInUse. williamr@2: * williamr@2: * After search completion, the client can make a second search and specify williamr@2: * that only the matches from the previous search shall be considered. williamr@2: * williamr@2: * The client can also set a limit on how many search matches should be williamr@2: * returned (see @ref SetMaxNumOfMatches). williamr@2: * williamr@2: * The client retrieves the matches from the search by requesting an iterator williamr@2: * (see @ref MatchIteratorL) or by using display data (see @ref SetDisplayData). williamr@2: * williamr@2: * @p NetworkServices capability is required for remote databases. williamr@2: * williamr@2: * @lib eposlmsearchlib.lib williamr@2: * @since S60 3.0 williamr@2: */ williamr@2: class CPosLandmarkSearch : public CBase williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * williamr@2: * The client takes ownership of the returned search object. williamr@2: * williamr@2: * @param[in] aDatabase The landmark database to search. williamr@2: * @returns A new instance of this class. williamr@2: */ williamr@2: IMPORT_C static CPosLandmarkSearch* NewL( williamr@2: CPosLandmarkDatabase& aDatabase williamr@2: ); williamr@2: williamr@2: /** williamr@2: * Destructor. williamr@2: */ williamr@2: IMPORT_C virtual ~CPosLandmarkSearch(); williamr@2: williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Retrieves the maximum number of search matches limit. williamr@2: * williamr@2: * By default the maximum number of matches is unlimited. williamr@2: * williamr@2: * @return The maximum number of search matches or williamr@2: * @p KPosLmMaxNumOfMatchesUnlimited if unlimited. williamr@2: */ williamr@2: IMPORT_C TInt MaxNumOfMatches() const; williamr@2: williamr@2: /** williamr@2: * Sets the maximum number of search matches limit. williamr@2: * williamr@2: * If the limit is set, the search operation will stop when this limit williamr@2: * is reached. williamr@2: * williamr@2: * By default the maximum number of matches is unlimited. williamr@2: * williamr@2: * If a new value for maximum number of matches is set when a search is williamr@2: * ongoing, it will not affect the current search. The new maximum will williamr@2: * be utilized in the next search. williamr@2: * williamr@2: * @param[in] aMaxNumOfMatches the maximum number of search matches. williamr@2: * KPosLmMaxNumOfMatchesUnlimited means that the number of matches is williamr@2: * unlimited. williamr@2: */ williamr@2: IMPORT_C void SetMaxNumOfMatches( williamr@2: TInt aMaxNumOfMatches = KPosLmMaxNumOfMatchesUnlimited williamr@2: ); williamr@2: williamr@2: /** williamr@2: * Starts a search for landmarks. williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param[in] aCriteria The search criterion. williamr@2: * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a williamr@2: * search within the results of previous search. williamr@2: * @returns A handle to the search operation. williamr@2: * williamr@2: * @leave KErrInUse Search is already running. williamr@2: * @leave KErrNotSupported search criterion is not supported. williamr@2: * @leave KErrArgument Search criterion is not valid for landmark searching. williamr@2: * @leave KErrArgument There are no previous matches and the client specifies that williamr@2: * previous matches should be used. williamr@2: */ williamr@2: virtual CPosLmOperation* StartLandmarkSearchL( williamr@2: const CPosLmSearchCriteria& aCriteria, williamr@2: TBool aSearchOnlyPreviousMatches = EFalse williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Starts a search for landmarks. williamr@2: * williamr@2: * This overload of the @ref StartLandmarkSearchL function lets the williamr@2: * client define the sort order for the search matches. williamr@2: * Only sorting by landmark name is supported. williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param[in] aCriteria The search criterion. williamr@2: * @param[in] aSortPref A sort preference object. williamr@2: * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a williamr@2: * search within the results of previous search. williamr@2: * @returns A handle to the search operation. williamr@2: * williamr@2: * @leave KErrInUse Search is already running. williamr@2: * @leave KErrArgument Search criterion is not valid for landmark searching. williamr@2: * @leave KErrArgument There are no previous matches and the client specifies that williamr@2: * previous matches should be used. williamr@2: * @leave KErrNotSupported Search criterion is not supported. williamr@2: * @leave KErrNotSupported Client tries to sort by other attribute than name. williamr@2: */ williamr@2: virtual CPosLmOperation* StartLandmarkSearchL( williamr@2: const CPosLmSearchCriteria& aCriteria, williamr@2: const TPosLmSortPref& aSortPref, williamr@2: TBool aSearchOnlyPreviousMatches = EFalse williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Starts a search for landmark categories. williamr@2: * williamr@2: * The criterion which defines whether a landmark category is a match or williamr@2: * not is passed as input to this function. williamr@2: * williamr@2: * The client takes ownership of the returned operation object. williamr@2: * williamr@2: * This function requires @p ReadUserData capability. williamr@2: * williamr@2: * @param[in] aCriteria The search criterion. williamr@2: * @param[in] aSortPref Sort preference for the search results. williamr@2: * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a williamr@2: * search within the results of previous search. williamr@2: * @returns A handle to the search operation. williamr@2: * williamr@2: * @leave KErrInUse Search is already running. williamr@2: * @leave KErrArgument Search criterion is not valid for category searching. williamr@2: * @leave KErrNotSupported Search criterion is not supported. williamr@2: */ williamr@2: virtual CPosLmOperation* StartCategorySearchL( williamr@2: const CPosLmSearchCriteria& aCriteria, williamr@2: CPosLmCategoryManager::TCategorySortPref aSortPref, williamr@2: TBool aSearchOnlyPreviousMatches = EFalse williamr@2: ) = 0; williamr@2: williamr@2: /** williamr@2: * Returns the number of matches so far in the search. williamr@2: * williamr@2: * This function can also be called during a search operation. williamr@2: * williamr@2: * @return The number of search matches. williamr@2: */ williamr@2: virtual TUint NumOfMatches() const = 0; williamr@2: williamr@2: /** williamr@2: * Creates an iterator object to iterate the matching landmarks or williamr@2: * landmark categories. williamr@2: * williamr@2: * This function can also be called during a search in order to read the williamr@2: * matches encountered so far. Note that the iterator will not iterate williamr@2: * any new matches. If new matches are found, a new iterator must be williamr@2: * created. williamr@2: * williamr@2: * If a sort preference was specified when the search was started, williamr@2: * the landmarks/categories will be sorted when the search is complete williamr@2: * but the items are not necessarily sorted if this function is called williamr@2: * during a search. williamr@2: * williamr@2: * Note: If the client has set display data and resets the display data williamr@2: * during a search, the sort order in the iterator might be incorrect. williamr@2: * williamr@2: * The client takes ownership of the returned iterator object. williamr@2: * williamr@2: * Note that the iterator iterates matches in @ref CPosLandmarkSearch. williamr@2: * It cannot be used after the search object has been deleted. Make sure williamr@2: * to delete the iterator first. williamr@2: * williamr@2: * @return A search match iterator. williamr@2: */ williamr@2: virtual CPosLmItemIterator* MatchIteratorL() = 0; williamr@2: williamr@2: /** williamr@2: * Display data can be used as an alternative way to get result williamr@2: * from a database search. Landmarks or categories are added to the williamr@2: * display data collection during a search depending on the search type. williamr@2: * williamr@2: * This function may replace the combination of using williamr@2: * @ref MatchIteratorL and reading landmark or category data. williamr@2: * Result data is read already during the search and no duplicate williamr@2: * access to database is needed. williamr@2: * williamr@2: * The display data object will be reset each time a new search is williamr@2: * started. No items during the search are removed from the williamr@2: * collection. New found matches can be added every time next williamr@2: * search step is completed, see @ref CPosLmDisplayData::NewItemIndex. williamr@2: * williamr@2: * Note: The database index of displayable data items in williamr@2: * @ref CPosLmDisplayData will be set to 0 as it has no meaning in a williamr@2: * single database search. williamr@2: * williamr@2: * The client owns the display data object. If the client deletes it williamr@2: * during a search, this may lead to unexpected errors. The client must williamr@2: * call @ref UnsetDisplayData before it deletes the display data object. williamr@2: * williamr@2: * Note: If the client resets the display data during a search, the sort williamr@2: * order in the iterator might become incorrect. williamr@2: * williamr@2: * @param[in,out] aData The displayable data. williamr@2: * williamr@2: * @panic "Landmarks Client"-EPosSearchOperationInUse williamr@2: * The client set display data during an ongoing search. williamr@2: */ williamr@2: virtual void SetDisplayData( CPosLmDisplayData& aData ) = 0; williamr@2: williamr@2: /** williamr@2: * Unsets display data. No further data will be added to the display williamr@2: * data that was set with @ref SetDisplayData. williamr@2: * williamr@2: * @panic "Landmarks Client"-EPosSearchOperationInUse williamr@2: * The client unset display data during an ongoing search. williamr@2: */ williamr@2: virtual void UnsetDisplayData() = 0; williamr@2: williamr@2: protected: williamr@2: williamr@2: // C++ constructor. williamr@2: IMPORT_C CPosLandmarkSearch(); williamr@2: williamr@2: private: williamr@2: williamr@2: // Prohibit copy constructor williamr@2: CPosLandmarkSearch( const CPosLandmarkSearch& ); williamr@2: // Prohibit assigment operator williamr@2: CPosLandmarkSearch& operator= ( const CPosLandmarkSearch& ); williamr@2: williamr@2: private: williamr@2: williamr@2: TUid iDtorIdKey; williamr@2: TInt iMaxNumOfMatches; williamr@2: }; williamr@2: williamr@2: #endif // CPOSLANDMARKSEARCH_H williamr@2: williamr@2: