/*

 * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). 

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: CPosLmMultiDbSearch class used to perform searches for landmarks or

 *				       landmark categories in multiple databases.

 *

 *

 */

 #ifndef CPOSLMMULTIDBSEARCH_H

 #define CPOSLMMULTIDBSEARCH_H

 #include <e32base.h>

 #include <badesca.h>

 #include <EPos_CPosLandmarkSearch.h>

 #include <EPos_CPosLmCategoryManager.h>

 class CPosLmSearchCriteria;

 class CPosLmDisplayData;

 class CPosLmMultiDbSearchOperation;

 class CPosLmMultiDbSortPref;

 class CPosLmMultiDbSearchItem;

 /**

 *  @ref 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.

 *  @ref CPosLmCategoryCriteria is used for searching for landmarks which

 *  contain a certain category) and some are used

 *  to search for landmark categories (e.g. @ref CPosLmCatNameCriteria is used

 *  to search for landmark categories by specifying a category name).

 *

 *  Searches can be run in incremental mode.

 *  @ref StartLandmarkSearchL and @ref StartCategorySearchL both return a

 *  @p CPosLmOperation object which is used to execute the search. If it is

 *  sufficient to run the search synchronously, the client only has to

 *  call @p CPosLmOperation::ExecuteL. If it is run incrementally the client can

 *  supervise the progress of the operation. The @p CPosLmOperation::NextStep

 *  function in the search operations cannot be executed synchronously using

 *  @p User::WaitForRequest. Doing so may cause the operation to hang.

 *  @p CPosLmOperation::NextStep must be run using an active object. The client

 *  can cancel the search by deleting the @p 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

 *  @ref 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 @ref CPosLmIdListCriteria

 *  since an item ID is only valid in one landmark database. In both cases

 *  the search functions leave with error code @p 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 @p 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 @ref SetMaxNumOfMatches).

 *

 *  The client retrieves the matches from the search by requesting an iterator

 *  (see @ref MatchIteratorL) or by using display data (see

 *  @ref SetDisplayData).

 *

 *  If @ref CPosLmMultiDbSearch is used, the client must call the global

 *  function @ref ReleaseLandmarkResources before terminating in order to

 *  release all used landmark resources, otherwise the client may receive

 *  an ALLOC panic.

 *

 *  @p NetworkServices capability is required for remote databases.

 *

 *  @lib eposlmmultidbsearch.lib

 *  @since S60 3.0

 *  @version $Revision: 1.17 $, $Date: 2005/07/07 13:40:10 $

 */

 class CPosLmMultiDbSearch : public CBase

     {

     public:  // Data types

         /**

         *  Struct containing a search error.

         */

         struct TSearchError

             {

             TUint iDatabaseIndex; /**<

                 The index of the database where the search has failed. The

                 database URI can be retrieved by calling @ref DatabaseUriPtr.*/

             TInt iErrorCode; /**<

                 The search error code for the database. */

             };

     public:  // Constructors and destructor

         /**

         * Two-phased constructor.

         *

         * Leaves with @p KErrArgument if the database list is empty.

         *

         * @param[in] aDatabaseList An array containing the URIs of the landmark

         *   databases to be used in the search.

         * @return A new instance of this class.

         */

         IMPORT_C static CPosLmMultiDbSearch* NewL( const CDesCArray&  aDatabaseList );

         /**

         * Destructor.

         */

         IMPORT_C virtual ~CPosLmMultiDbSearch();

     public: // New functions

         /**

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

         *

         * If this function is called and then @ref StartLandmarkSearchL or

         * @ref 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,

         * @ref GetSearchError will report error code @p KErrNotFound for those

         * databases after the search is started.

         *

         * This function will leave with @p 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 @p KErrArgument if the database list is empty.

         *

         * @since S60 3.0

         * @param[in] aDatabaseList An array containing the URIs of the landmark

         *   databases to be used in the search.

         */

         IMPORT_C void SetDatabasesToSearchL( const CDesCArray&  aDatabaseList );

         /**

         * Returns the list of databases to search. Ownership is transferred

         * to the caller.

         *

         * @return The list of databases to search.

         */

         IMPORT_C CDesCArray* DatabasesToSearchL();

         /**

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

         *

         * @since S60 3.0

         * @param[in] aMaxNumOfMatches The maximum number of search matches for

         *   each landmark database involved in the search.

         */

         IMPORT_C void SetMaxNumOfMatches( TInt  aMaxNumOfMatches = KPosLmMaxNumOfMatchesUnlimited );

         /**

         * 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 @p KErrArgument.

         *

         * If a search is already running, this function leaves with error

         * code @p KErrInUse.

         *

         * If the search criterion is not valid for landmark searching, this

         * function leaves with error code @p KErrArgument.

         *

         * If the search criterion is not supported, this function leaves

         * with error code @p KErrNotSupported.

         *

         * If @ref CPosLmIdListCriteria is used or @ref CPosLmCategoryCriteria

         * with item ID set, this function leaves with error code

         * @p KErrArgument.

         *

         * The client takes ownership of the returned operation object.

         *

         * This function requires @p ReadUserData capability.

         *

         * @since S60 3.0

         * @param[in] aCriteria The search criterion.

         * @param[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* StartLandmarkSearchL(

             const CPosLmSearchCriteria&  aCriteria,

             TBool  aSearchOnlyPreviousMatches = EFalse );

         /**

         * Starts a landmark search.

         *

         * This overload of the @ref 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

         * @p KErrNotSupported.

         *

         * If there are no previous matches and the client specifies that

         * previous matches should be used, this function leaves with error

         * code @p KErrArgument.

         *

         * If a search is already running, this function will leave with error

         * code @p KErrInUse.

         *

         * If the search criterion is not valid for landmark searching, this

         * function leaves with error code @p KErrArgument.

         *

         * If the search criterion is not supported, this function will leave

         * with error code @p KErrNotSupported.

         *

         * If @ref CPosLmIdListCriteria is used or @ref CPosLmCategoryCriteria

         * with item ID set, this function leaves with error code

         * @p KErrArgument.

         *

         * The client takes ownership of the returned operation object.

         *

         * This function requires @p ReadUserData capability.

         *

         * @since S60 3.0

         * @param[in] aCriteria The search criterion.

         * @param[in] aSortPref A sort preference object.

         * @param[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* StartLandmarkSearchL(

             const CPosLmSearchCriteria&  aCriteria,

             const TPosLmSortPref&  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 @p 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 @p KErrInUse.

         *

         * If the search criterion is not valid for landmark category searching,

         * this function leaves with error code @p KErrArgument.

         *

         * If the search criterion is not supported, this function leaves

         * with error code @p KErrNotSupported.

         *

         * The client takes ownership of the returned operation object.

         *

         * This function requires @p ReadUserData capability.

         *

         * @param[in] aCriteria The search criteria.

         * @param[in] aSortPref Sort preference for the search results.

         * @param[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* StartCategorySearchL(

             const CPosLmSearchCriteria&  aCriteria,

             CPosLmCategoryManager::TCategorySortPref  aSortPref,

             TBool  aSearchOnlyPreviousMatches = EFalse );

         /**

         * Returns the number of errors encountered during the search. This is

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

         *

         * @since S60 3.0

         * @return The number of errors encountered during the search.

         */

         IMPORT_C TUint NumOfSearchErrors() const;

         /**

         * Returns errors encountered in the search.

         *

         * The client specifies an index of the error to retrieve. The index must

         * be strictly less than @ref NumOfSearchErrors, otherwise this function

         * panics with code @p EPosInvalidIndex. Whenever a new search is started

         * this function must be called again to retrieve error codes, if any.

         *

         * @since S60 3.0

         * @param[in] aErrorIndex The index of the error to retrieve.

         * @param[out] aSearchError On return, contains the search error.

         */

         IMPORT_C void GetSearchError(

             TUint  aErrorIndex,

             TSearchError&  aSearchError ) const;

         /**

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

         *

         * This function can also be called during a search operation.

         *

         * @since S60 3.0

         * @return The number of search matches.

         */

         IMPORT_C TUint TotalNumOfMatches() const;

         /**

         * Returns the number of matches so far in the search for a

         * database specified by index.

         *

         * The index must be strictly less than @ref NumOfDatabasesToSearch,

         * otherwise this function will panic with code @p EPosInvalidIndex.

         * The URI of the database can be retrieved by calling

         * @ref DatabaseUriPtr.

         *

         * This function can also be called during a search operation.

         *

         * @param[in] aDatabaseIndex The index of the database to get number

         *   of search matches for.

         * @return The number of matches per database.

         */

         IMPORT_C TUint NumOfMatches( TUint aDatabaseIndex ) const;

         /**

         * Returns the number of databases involved in the search.

         *

         * @since S60 3.0

         * @return The number of databases involved in the search.

         */

         IMPORT_C TUint NumOfDatabasesToSearch() 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 @ref NumOfDatabasesToSearch,

         * otherwise this function will panic with code @p EPosInvalidIndex.

         *

         * @since S60 3.0

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

         * @return A pointer to the database URI descriptor. This pointer is

         *   only valid until @ref SetDatabasesToSearch is called, or the

         *   @ref CPosLmMultiDbSearch object is destroyed, whichever happens

         *   first.

         */

         IMPORT_C TPtrC DatabaseUriPtr( TUint aDatabaseIndex ) const;

         /**

         * 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 @ref NumOfDatabasesToSearch,

         * otherwise this function will panic with code @p EPosInvalidIndex.

         * The URI of the database can be retrieved by calling

         * @ref 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 @ref CPosLmMultiDbSearch.

         * It cannot be used after the search object has been deleted.

         *

         * @since S60 3.0

         * @param aDatabaseIndex The index of the database to get search matches

         *   for.

         * @return A search results iterator.

         */

         IMPORT_C CPosLmItemIterator* MatchIteratorL( TUint aDatabaseIndex );

         /**

         * 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

         * @ref 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 @ref CPosLmDisplayData::NewItemIndex.

         *

         * If the client sets display data during an ongoing search, this

         * function panics with code @p 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 @ref UnsetDisplayData before it deletes the display data object.

         *

         * Search results from all databases are collected in the same

         * displayable data collection. The @ref CPosLmDisplayItem::DatabaseIndex

         * may be used to know which database every displayable item belongs to.

         * The database index matches databases specified in this object,

         * see @ref DatabaseUriPtr.

         *

         * @param[in,out] aData The displayable data.

         */

         IMPORT_C void SetDisplayData( CPosLmDisplayData& aData );

         /**

         * Unsets display data. No further data will be added to the display

         * data set with @ref SetDisplayData.

         *

         * If the client unsets display data during an ongoing search, this

         * function panics with code @p EPosSearchOperationInUse.

         */

         IMPORT_C void UnsetDisplayData();

         /**

         * Retrieves the maximum number of search matches limit for each

         * database.

         *

         * By default the maximum number of matches is unlimited.

         *

         * @return The maximum number of search matches for each landmark

         *   database involved in the search or

         *   @p KPosLmMaxNumOfMatchesUnlimited if unlimited.

         */

         IMPORT_C TInt MaxNumOfMatches() const;

         /*

         * Tells if the database with the specified database index is to be

         * searched or not.

         *

         * @param aDatabaseIndex The index of the database.

         * @return ETrue if the database is to be searched, otherwise EFalse.

         */

         TBool ToBeSearched( TUint aDatabaseIndex ) const;

         /*

         * Gets a pointer to the database with the specified database index.

         *

         * @param aDatabaseIndex The index of the database.

         * @return A pointer to the landmark database.

         */

         CPosLandmarkDatabase* DatabaseL( TUint aDatabaseIndex );

         /*

         * Gets a pointer to the single search class for the database with the

         * specified database index.

         *

         * @param aDatabaseIndex The index of the database.

         * @return A pointer to the single search class.

         */

         CPosLandmarkSearch* SearcherL( TUint aDatabaseIndex );

         /*

         * This method must be called to notify this class when a search has

         * been started in the single search class corresponding to the

         * specified database index.

         *

         * @param aDatabaseIndex The index of the database.

         */

         void SearchStarted( TUint aDatabaseIndex );

         /*

         * This method must be called to notify this class when a search has

         * been executed (partly or completely) in the single search class

         * corresponding to the specified database index.

         *

         * @param[in] aDatabaseIndex The index of the database.

         * @param[in] aSortPref The sort pref for the search.

         */

         void SearchExecutedL(

             TUint aDatabaseIndex,

             const CPosLmMultiDbSortPref& aSortPref );

         /*

         * Adds a search error for the specified database index.

         *

         * @param aDatabaseIndex The index of the database.

         * @param aErrorCode The error code.

         */

         void AddSearchError( TUint aDatabaseIndex, TInt aErrorCode );

         /*

         * This function must be called by the CPosLmMultiDbSearchOperation

         * when the search operation has completed or has been cancelled.

         */

         void HandleSearchOperationCompleted();

     private:

         /**

         * C++ default constructor.

         */

         CPosLmMultiDbSearch();

         /**

         * By default Symbian 2nd phase constructor is private.

         */

         void ConstructL(const CDesCArray& aDatabaseList);

         void CloseDbsNotToSearch(const CDesCArray& aDatabaseList);

         CPosLmOperation* StartSearchL(

             const CPosLmSearchCriteria& aCriteria,

             CPosLmMultiDbSortPref* aSortPref,

             TBool aSearchOnlyPreviousMatches );

     private:    // Data

         TInt                    iMaxNumOfMatches;

         TInt                    iNewMaxNumOfMatches;

         CPosLmMultiDbSearchOperation* iMultiSearchOperation; // No ownership

         RPointerArray<CPosLmMultiDbSearchItem> iSearchItems;

         RArray<TSearchError>    iSearchErrors; // Can contain dummy errors.

         TUint                   iNoOfSearchErrors; // Number of valid errors.

         CPosLmDisplayData*      iClientDisplayData; // No ownership

     };

 #endif      // CPOSLMMULTIDBSEARCH_H