williamr@2: /* williamr@2: * Copyright (c) 2002-2007 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: CPosLmMultiDbSearch class used to perform searches for landmarks or williamr@2: * landmark categories in multiple databases. williamr@2: * williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef CPOSLMMULTIDBSEARCH_H williamr@2: #define CPOSLMMULTIDBSEARCH_H williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: class CPosLmSearchCriteria; williamr@2: class CPosLmDisplayData; williamr@2: class CPosLmMultiDbSearchOperation; williamr@2: class CPosLmMultiDbSortPref; williamr@2: class CPosLmMultiDbSearchItem; williamr@2: williamr@2: /** williamr@2: * @ref CPosLmMultiDbSearch is used to perform searches for landmarks or williamr@2: * landmark categories in multiple databases. williamr@2: * williamr@2: * The client can specify which databases to search. 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). 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: * sufficient to run the search synchronously, the client only has to williamr@2: * call @p CPosLmOperation::ExecuteL. If it is run incrementally the client can williamr@2: * supervise the progress of the operation. The @p CPosLmOperation::NextStep williamr@2: * function in the search operations cannot be executed synchronously using williamr@2: * @p User::WaitForRequest. Doing so may cause the operation to hang. williamr@2: * @p CPosLmOperation::NextStep must be run using an active object. The client williamr@2: * can cancel 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: * It is not allowed to search by category item ID in williamr@2: * @ref CPosLmCategoryCriteria since an item ID is only valid in one landmark williamr@2: * database. williamr@2: * williamr@2: * It is only allowed to specify a named category, a global category, williamr@2: * or no category. It is not allowed to search with @ref CPosLmIdListCriteria williamr@2: * since an item ID is only valid in one landmark database. In both cases williamr@2: * the search functions leave with error code @p KErrArgument. williamr@2: * williamr@2: * During the search execution, a read-lock is acquired for each database. 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 williamr@2: * @ref SetDisplayData). williamr@2: * williamr@2: * If @ref CPosLmMultiDbSearch is used, the client must call the global williamr@2: * function @ref ReleaseLandmarkResources before terminating in order to williamr@2: * release all used landmark resources, otherwise the client may receive williamr@2: * an ALLOC panic. williamr@2: * williamr@2: * @p NetworkServices capability is required for remote databases. williamr@2: * williamr@2: * @lib eposlmmultidbsearch.lib williamr@2: * @since S60 3.0 williamr@2: * @version $Revision: 1.17 $, $Date: 2005/07/07 13:40:10 $ williamr@2: */ williamr@2: class CPosLmMultiDbSearch : public CBase williamr@2: { williamr@2: public: // Data types williamr@2: williamr@2: /** williamr@2: * Struct containing a search error. williamr@2: */ williamr@2: struct TSearchError williamr@2: { williamr@2: TUint iDatabaseIndex; /**< williamr@2: The index of the database where the search has failed. The williamr@2: database URI can be retrieved by calling @ref DatabaseUriPtr.*/ williamr@2: TInt iErrorCode; /**< williamr@2: The search error code for the database. */ williamr@2: }; williamr@2: williamr@2: public: // Constructors and destructor williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * williamr@2: * Leaves with @p KErrArgument if the database list is empty. williamr@2: * williamr@2: * @param[in] aDatabaseList An array containing the URIs of the landmark williamr@2: * databases to be used in the search. williamr@2: * @return A new instance of this class. williamr@2: */ williamr@2: IMPORT_C static CPosLmMultiDbSearch* NewL( const CDesCArray& aDatabaseList ); williamr@2: williamr@2: /** williamr@2: * Destructor. williamr@2: */ williamr@2: IMPORT_C virtual ~CPosLmMultiDbSearch(); williamr@2: williamr@2: public: // New functions williamr@2: williamr@2: /** williamr@2: * Specifies the list of databases that should be used in the search. williamr@2: * williamr@2: * If this function is called and then @ref StartLandmarkSearchL or williamr@2: * @ref StartCategorySearchL is called with the flag williamr@2: * aSearchOnlyPreviousMatches set, new databases that were not a part williamr@2: * of the previous search will generate no matches. williamr@2: * williamr@2: * If the client specifies database(s) that do not exist, williamr@2: * @ref GetSearchError will report error code @p KErrNotFound for those williamr@2: * databases after the search is started. williamr@2: * williamr@2: * This function will leave with @p KErrInUse if called during a williamr@2: * search. williamr@2: * williamr@2: * If this function is called after a search has completed, williamr@2: * database indexes in the results may become invalid. williamr@2: * williamr@2: * If a database is removed from a previously set list, the search williamr@2: * result of that database is unavailable after this function williamr@2: * is called. Search errors are reset after this function is called. williamr@2: * williamr@2: * Leaves with @p KErrArgument if the database list is empty. williamr@2: * williamr@2: * @since S60 3.0 williamr@2: * @param[in] aDatabaseList An array containing the URIs of the landmark williamr@2: * databases to be used in the search. williamr@2: */ williamr@2: IMPORT_C void SetDatabasesToSearchL( const CDesCArray& aDatabaseList ); williamr@2: williamr@2: /** williamr@2: * Returns the list of databases to search. Ownership is transferred williamr@2: * to the caller. williamr@2: * williamr@2: * @return The list of databases to search. williamr@2: */ williamr@2: IMPORT_C CDesCArray* DatabasesToSearchL(); williamr@2: williamr@2: /** williamr@2: * Sets the maximum number of search matches limit for each database. williamr@2: * williamr@2: * This function is used to limit the number of matches retrieved from williamr@2: * each database in the search operation. If the limit is set, the williamr@2: * search operation will stop when this limit is reached. By default williamr@2: * 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: * @since S60 3.0 williamr@2: * @param[in] aMaxNumOfMatches The maximum number of search matches for williamr@2: * each landmark database involved in the search. williamr@2: */ williamr@2: IMPORT_C void SetMaxNumOfMatches( TInt aMaxNumOfMatches = KPosLmMaxNumOfMatchesUnlimited ); williamr@2: williamr@2: /** williamr@2: * Starts a landmark search. williamr@2: * williamr@2: * If there are no previous matches and the client specifies that williamr@2: * previous matches should be used, this function leaves with error williamr@2: * code @p KErrArgument. williamr@2: * williamr@2: * If a search is already running, this function leaves with error williamr@2: * code @p KErrInUse. williamr@2: * williamr@2: * If the search criterion is not valid for landmark searching, this williamr@2: * function leaves with error code @p KErrArgument. williamr@2: * williamr@2: * If the search criterion is not supported, this function leaves williamr@2: * with error code @p KErrNotSupported. williamr@2: * williamr@2: * If @ref CPosLmIdListCriteria is used or @ref CPosLmCategoryCriteria williamr@2: * with item ID set, this function leaves with error code williamr@2: * @p KErrArgument. 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: * @since S60 3.0 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: IMPORT_C CPosLmOperation* StartLandmarkSearchL( williamr@2: const CPosLmSearchCriteria& aCriteria, williamr@2: TBool aSearchOnlyPreviousMatches = EFalse ); williamr@2: williamr@2: /** williamr@2: * Starts a landmark search. 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: * williamr@2: * Only sorting by landmark name is supported. If the client tries to williamr@2: * sort by another attribute, this function leaves with error code williamr@2: * @p KErrNotSupported. williamr@2: * williamr@2: * If there are no previous matches and the client specifies that williamr@2: * previous matches should be used, this function leaves with error williamr@2: * code @p KErrArgument. williamr@2: * williamr@2: * If a search is already running, this function will leave with error williamr@2: * code @p KErrInUse. williamr@2: * williamr@2: * If the search criterion is not valid for landmark searching, this williamr@2: * function leaves with error code @p KErrArgument. williamr@2: * williamr@2: * If the search criterion is not supported, this function will leave williamr@2: * with error code @p KErrNotSupported. williamr@2: * williamr@2: * If @ref CPosLmIdListCriteria is used or @ref CPosLmCategoryCriteria williamr@2: * with item ID set, this function leaves with error code williamr@2: * @p KErrArgument. 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: * @since S60 3.0 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: IMPORT_C CPosLmOperation* StartLandmarkSearchL( williamr@2: const CPosLmSearchCriteria& aCriteria, williamr@2: const TPosLmSortPref& aSortPref, williamr@2: TBool aSearchOnlyPreviousMatches = EFalse ); williamr@2: williamr@2: /** williamr@2: * Starts a search for landmark categories. williamr@2: * williamr@2: * If there are no previous matches and the client specifies that williamr@2: * previous matches should be used, this function leaves with error williamr@2: * code @p KErrArgument... williamr@2: * williamr@2: * The criterion, which defines if a landmark category is a match, williamr@2: * is passed as input to this function. williamr@2: * williamr@2: * If a search is already running, this function leaves with error williamr@2: * code @p KErrInUse. williamr@2: * williamr@2: * If the search criterion is not valid for landmark category searching, williamr@2: * this function leaves with error code @p KErrArgument. williamr@2: * williamr@2: * If the search criterion is not supported, this function leaves williamr@2: * with error code @p KErrNotSupported. 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 criteria. 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: IMPORT_C CPosLmOperation* StartCategorySearchL( williamr@2: const CPosLmSearchCriteria& aCriteria, williamr@2: CPosLmCategoryManager::TCategorySortPref aSortPref, williamr@2: TBool aSearchOnlyPreviousMatches = EFalse ); williamr@2: williamr@2: /** williamr@2: * Returns the number of errors encountered during the search. This is williamr@2: * the same as number of databases in which the search has failed. williamr@2: * williamr@2: * @since S60 3.0 williamr@2: * @return The number of errors encountered during the search. williamr@2: */ williamr@2: IMPORT_C TUint NumOfSearchErrors() const; williamr@2: williamr@2: /** williamr@2: * Returns errors encountered in the search. williamr@2: * williamr@2: * The client specifies an index of the error to retrieve. The index must williamr@2: * be strictly less than @ref NumOfSearchErrors, otherwise this function williamr@2: * panics with code @p EPosInvalidIndex. Whenever a new search is started williamr@2: * this function must be called again to retrieve error codes, if any. williamr@2: * williamr@2: * @since S60 3.0 williamr@2: * @param[in] aErrorIndex The index of the error to retrieve. williamr@2: * @param[out] aSearchError On return, contains the search error. williamr@2: */ williamr@2: IMPORT_C void GetSearchError( williamr@2: TUint aErrorIndex, williamr@2: TSearchError& aSearchError ) const; williamr@2: williamr@2: /** williamr@2: * Returns the total 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: * @since S60 3.0 williamr@2: * @return The number of search matches. williamr@2: */ williamr@2: IMPORT_C TUint TotalNumOfMatches() const; williamr@2: williamr@2: /** williamr@2: * Returns the number of matches so far in the search for a williamr@2: * database specified by index. williamr@2: * williamr@2: * The index must be strictly less than @ref NumOfDatabasesToSearch, williamr@2: * otherwise this function will panic with code @p EPosInvalidIndex. williamr@2: * The URI of the database can be retrieved by calling williamr@2: * @ref DatabaseUriPtr. williamr@2: * williamr@2: * This function can also be called during a search operation. williamr@2: * williamr@2: * @param[in] aDatabaseIndex The index of the database to get number williamr@2: * of search matches for. williamr@2: * @return The number of matches per database. williamr@2: */ williamr@2: IMPORT_C TUint NumOfMatches( TUint aDatabaseIndex ) const; williamr@2: williamr@2: /** williamr@2: * Returns the number of databases involved in the search. williamr@2: * williamr@2: * @since S60 3.0 williamr@2: * @return The number of databases involved in the search. williamr@2: */ williamr@2: IMPORT_C TUint NumOfDatabasesToSearch() const; williamr@2: williamr@2: /** williamr@2: * Returns the URI of a database involved in the search. williamr@2: * williamr@2: * The client specifies an index of the database URI to retrieve. The williamr@2: * index must be strictly less than @ref NumOfDatabasesToSearch, williamr@2: * otherwise this function will panic with code @p EPosInvalidIndex. williamr@2: * williamr@2: * @since S60 3.0 williamr@2: * @param[in] aDatabaseIndex The index of the database URI to retrieve. williamr@2: * @return A pointer to the database URI descriptor. This pointer is williamr@2: * only valid until @ref SetDatabasesToSearch is called, or the williamr@2: * @ref CPosLmMultiDbSearch object is destroyed, whichever happens williamr@2: * first. williamr@2: */ williamr@2: IMPORT_C TPtrC DatabaseUriPtr( TUint aDatabaseIndex ) const; williamr@2: williamr@2: /** williamr@2: * Creates an iterator object to iterate the matching landmarks or williamr@2: * categories from one of the databases involved in the search. williamr@2: * williamr@2: * The database to get search matches for is specified by index. The williamr@2: * index must be strictly less than @ref NumOfDatabasesToSearch, williamr@2: * otherwise this function will panic with code @p EPosInvalidIndex. williamr@2: * The URI of the database can be retrieved by calling williamr@2: * @ref DatabaseUriPtr. 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 needs to be williamr@2: * created to retrieve them. The previous matches will also be included. williamr@2: * williamr@2: * If the client has started a search, but no matches have been found williamr@2: * yet in the database, an empty iterator is returned. williamr@2: * williamr@2: * If a sort preference was specified when the search was started, the williamr@2: * landmarks or categories will be sorted when the search is complete williamr@2: * but the items are not necessarily sorted if this function is williamr@2: * called during a search. williamr@2: * williamr@2: * The client takes ownership of the returned iterator object. williamr@2: * williamr@2: * Note: The iterator iterates matches in @ref CPosLmMultiDbSearch. williamr@2: * It cannot be used after the search object has been deleted. williamr@2: * williamr@2: * @since S60 3.0 williamr@2: * @param aDatabaseIndex The index of the database to get search matches williamr@2: * for. williamr@2: * @return A search results iterator. williamr@2: */ williamr@2: IMPORT_C CPosLmItemIterator* MatchIteratorL( TUint aDatabaseIndex ); 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: * If the client sets display data during an ongoing search, this williamr@2: * function panics with code @p EPosSearchOperationInUse. 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: * Search results from all databases are collected in the same williamr@2: * displayable data collection. The @ref CPosLmDisplayItem::DatabaseIndex williamr@2: * may be used to know which database every displayable item belongs to. williamr@2: * The database index matches databases specified in this object, williamr@2: * see @ref DatabaseUriPtr. williamr@2: * williamr@2: * @param[in,out] aData The displayable data. williamr@2: */ williamr@2: IMPORT_C void SetDisplayData( CPosLmDisplayData& aData ); williamr@2: williamr@2: /** williamr@2: * Unsets display data. No further data will be added to the display williamr@2: * data set with @ref SetDisplayData. williamr@2: * williamr@2: * If the client unsets display data during an ongoing search, this williamr@2: * function panics with code @p EPosSearchOperationInUse. williamr@2: */ williamr@2: IMPORT_C void UnsetDisplayData(); williamr@2: williamr@2: /** williamr@2: * Retrieves the maximum number of search matches limit for each williamr@2: * database. williamr@2: * williamr@2: * By default the maximum number of matches is unlimited. williamr@2: * williamr@2: * @return The maximum number of search matches for each landmark williamr@2: * database involved in the search or williamr@2: * @p KPosLmMaxNumOfMatchesUnlimited if unlimited. williamr@2: */ williamr@2: IMPORT_C TInt MaxNumOfMatches() const; williamr@2: williamr@2: /* williamr@2: * Tells if the database with the specified database index is to be williamr@2: * searched or not. williamr@2: * williamr@2: * @param aDatabaseIndex The index of the database. williamr@2: * @return ETrue if the database is to be searched, otherwise EFalse. williamr@2: */ williamr@2: TBool ToBeSearched( TUint aDatabaseIndex ) const; williamr@2: williamr@2: /* williamr@2: * Gets a pointer to the database with the specified database index. williamr@2: * williamr@2: * @param aDatabaseIndex The index of the database. williamr@2: * @return A pointer to the landmark database. williamr@2: */ williamr@2: CPosLandmarkDatabase* DatabaseL( TUint aDatabaseIndex ); williamr@2: williamr@2: /* williamr@2: * Gets a pointer to the single search class for the database with the williamr@2: * specified database index. williamr@2: * williamr@2: * @param aDatabaseIndex The index of the database. williamr@2: * @return A pointer to the single search class. williamr@2: */ williamr@2: CPosLandmarkSearch* SearcherL( TUint aDatabaseIndex ); williamr@2: williamr@2: /* williamr@2: * This method must be called to notify this class when a search has williamr@2: * been started in the single search class corresponding to the williamr@2: * specified database index. williamr@2: * williamr@2: * @param aDatabaseIndex The index of the database. williamr@2: */ williamr@2: void SearchStarted( TUint aDatabaseIndex ); williamr@2: williamr@2: /* williamr@2: * This method must be called to notify this class when a search has williamr@2: * been executed (partly or completely) in the single search class williamr@2: * corresponding to the specified database index. williamr@2: * williamr@2: * @param[in] aDatabaseIndex The index of the database. williamr@2: * @param[in] aSortPref The sort pref for the search. williamr@2: */ williamr@2: void SearchExecutedL( williamr@2: TUint aDatabaseIndex, williamr@2: const CPosLmMultiDbSortPref& aSortPref ); williamr@2: williamr@2: /* williamr@2: * Adds a search error for the specified database index. williamr@2: * williamr@2: * @param aDatabaseIndex The index of the database. williamr@2: * @param aErrorCode The error code. williamr@2: */ williamr@2: void AddSearchError( TUint aDatabaseIndex, TInt aErrorCode ); williamr@2: williamr@2: /* williamr@2: * This function must be called by the CPosLmMultiDbSearchOperation williamr@2: * when the search operation has completed or has been cancelled. williamr@2: */ williamr@2: void HandleSearchOperationCompleted(); williamr@2: williamr@2: private: williamr@2: williamr@2: /** williamr@2: * C++ default constructor. williamr@2: */ williamr@2: CPosLmMultiDbSearch(); williamr@2: williamr@2: /** williamr@2: * By default Symbian 2nd phase constructor is private. williamr@2: */ williamr@2: void ConstructL(const CDesCArray& aDatabaseList); williamr@2: williamr@2: void CloseDbsNotToSearch(const CDesCArray& aDatabaseList); williamr@2: williamr@2: CPosLmOperation* StartSearchL( williamr@2: const CPosLmSearchCriteria& aCriteria, williamr@2: CPosLmMultiDbSortPref* aSortPref, williamr@2: TBool aSearchOnlyPreviousMatches ); williamr@2: williamr@2: private: // Data williamr@2: williamr@2: TInt iMaxNumOfMatches; williamr@2: TInt iNewMaxNumOfMatches; williamr@2: williamr@2: CPosLmMultiDbSearchOperation* iMultiSearchOperation; // No ownership williamr@2: williamr@2: RPointerArray iSearchItems; williamr@2: williamr@2: RArray iSearchErrors; // Can contain dummy errors. williamr@2: TUint iNoOfSearchErrors; // Number of valid errors. williamr@2: williamr@2: CPosLmDisplayData* iClientDisplayData; // No ownership williamr@2: williamr@2: }; williamr@2: williamr@2: #endif // CPOSLMMULTIDBSEARCH_H williamr@2: