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