/*

* Copyright (c) 2002-2005 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: Base class for criteria based searches.

*

*/

#ifndef CPOSLMLOCALSEARCHHANDLER_H

#define CPOSLMLOCALSEARCHHANDLER_H

#include <d32dbms.h>

#include <EPos_CPosLmSearchCriteria.h>

#include <epos_rposlmlocalnameindex.h>

#include "EPos_TPosLmLocalSortPref.h"

#include "EPos_TPosLmProgressHelper.h"

const TReal32 KProgressCompleted = 1.0;

const TReal32 KPosUndefinedDistance = -1;

class CPosLmDisplayItem;

class CPosLmDisplayData;

class CPosLmLocalDbAccess;

class CPosLmNameIndexIterator;

class CPosLmLocalDatabase;

/**

*  Base class for criteria based searches.

*/

class CPosLmLocalSearchHandler : public CBase

    {

    public:  // Constructors and destructor

        /**

        * Destructor.

        */

        virtual ~CPosLmLocalSearchHandler();

    public: // New functions

        /**

        * Factory method for creating an instance of the

        * CPosLmLocalSearchHandler subclass that corresponds to the search

        * criteria.

        *

        * The caller takes ownership of the returned object.

        *

        * @param[in] aDbAccess Access handle to the database to search in.

        * @param[in] aCriteria The search criteria.

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

        * @param[in] aDisplayData The displayable data. NOTE: Ownership is

        *   not transferred.

        * @param aMaxNumOfMatches The max number of items that will be

        *   searched for.

        * @return An instance of a CPosLmLocalSearchHandler subclass.

        */

        static CPosLmLocalSearchHandler* CreateHandlerL(

            CPosLmLocalDatabase& aDatabase,

            const CPosLmSearchCriteria& aCriteria,

            const TPosLmLocalSortPref& aSortPref,

            CPosLmDisplayData* aDisplayData,

            TInt aMaxNumOfMatches );

        /**

        * Restricts the next search to only include matches that also are

        * included in this array.

        *

        * @param[in] aPreviousMatches An array of item ids.

        */

        void SetPreviousMatchesToSearchL(

                const RArray<TPosLmItemId>& aPreviousMatches );

        /**

        * Checks if this search handler is valid for landmark searching.

        *

        * @return EFalse unless overriden in derived class.

        */

        virtual TBool IsValidForLandmarkSearch() const;

        /**

        * Checks if this search handler is valid for category searching.

        *

        * @return EFalse unless overriden in derived class.

        */

        virtual TBool IsValidForCategorySearch() const;

        /**

        * Synchronous incremental execution of the search. Performs a single

        * step of the search synchronously.

        *

        * Leaves with an error code if something goes wrong.

        *

        * @param[out] aProgress Will be set to the progress of the search when

        * the step has finished.

        * @return @p KPosLmOperationNotComplete if the step has completed but

        *   more steps are needed before the search has finished,

        *   @p KErrNone if the search has finished successfully.

        */

        virtual TInt NextStepL( TReal32& aProgress ) = 0;

        /**

        * This function must be called if any further searching is cancelled.

        * (I.e. NextStepL has either leaved or if the search operation is

        * deleted before NextStepL has returned @p KErrNone.)

        */

        virtual void CancelSearch();

        /**

        * Get matches from a search. If the search is not completed the

        * matches encountered so far will be returned.

        *

        * @param[out] aMatches Array containing the landmark item IDs found

        *   in the search. The caller is responsible to close the array.

        */

        virtual void GetMatchesL( RArray<TPosLmItemId>& aMatches ) const;

        /**

        * Get matches from a search. If the search is not completed the

        * matches encountered so far will be returned.

        *

        * @return Array containing the landmark item IDs found

        *   in the search. Do NOT call Close() or Reset().

        */

        virtual const RArray<TPosLmItemId>& Matches() const;

    protected:

        /**

        * C++ default constructor.

        *

        * @param[in] aDbAccess Access handle to the database to search in.

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

        * @param[in] aMaxNumOfMatches The max number of items that will be

        *   searched for.

        * @param[in] aIsLast Should be set to @p ETrue if this search handler

        *   is the last search handler as a part of a composite search or

        *   if it is not part of a composite search at all, otherwise @p EFalse.

        */

        CPosLmLocalSearchHandler(

            CPosLmLocalDatabase& aDatabase,

            CPosLmSearchCriteria::TCriteriaType aCriteriaType,

            const TPosLmLocalSortPref& aSortPref,

            TInt aMaxNumOfMatches );

        /**

        * Set display data.

        * Only allowed to call this function once, typically in ConstructL.

        *

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

        */

        void SetDisplayDataL( CPosLmDisplayData* aData );

        /**

        * Tells if display data has been set.

        * @return @p ETrue if display data has been set otherwise @p EFalse.

        */

        TBool HasDisplayData() const;

        /**

        * @return Reference to display data object.

        */

        CPosLmDisplayData& DisplayData();

        const CPosLmDisplayData& DisplayData() const;

        /**

        * Get current matches from a search. If the search is not completed the

        * matches encountered so far will be returned.

        *

        * @return Array containing the landmark item IDs found

        *   in the search. Do NOT call Close() or Reset().

        */

        RArray<TPosLmItemId>& CurrentMatches();

        /**

        * Retrieves the maximum number of search matches.

        *

        * @return The maximum number of search matches or

        *   @p KPosLmMaxNumOfMatchesUnlimited if unlimited.

        */

        TInt MaxNumOfMatches() const;

        /**

        * Checks whether maximum number of matches have been found.

        */

        TBool IsMaxMatchesFound() const;

        /**

        * Returns the sort preference.

        * @return The sort preference.

        */

        const TPosLmLocalSortPref& SortPref() const;

        /**

        * Returns previous matches if set.

        *

        * @return Array containing the landmark item IDs set as previous

        *   matches.

        */

        const RArray<TUint>& PreviousMatches() const;

        /**

        * Checks if a landmark id matches the previous matches array if set.

        *

        * If SetPreviousMatchesToSearchL has NOT been called, this method will

        * always return @p ETrue.

        *

        * If SetPreviousMatchesToSearchL has been called, this method will

        * return @p ETrue only if included in the previous matches, otherwise

        * @p EFalse.

        *

        * @param aCurrentMatch Landmark item id for the current match.

        * @return See above.

        */

        TBool MatchesPreviousMatches( TPosLmItemId aCurrentMatch ) const;

        /**

        * Adds new match from an ongoing search.

        *

        * If SetPreviousMatchesToSearchL has been called, this match will be

        * added only if included in the previous matches.

        *

        * @param aCurrentMatch Landmark item id for the current match.

        * @param aDataRow Pointer to a row, which contains landmark or category

        * 	data. Forwarded o display data.

        */

        void AddMatchL( TPosLmItemId aMatchId, RDbRowSet* aDataRow = NULL );

        /**

        * Appends sort order to a db query.

        * @param[in,out] The db query.

        */

        void AppendSortToQueryL( HBufC* aDbQuery );

        /**

        * Prepares a view for a search.

        *

        * @param[in,out] aView The view to prepare.

        * @param[in] aDbQuery The database query.

        * @param[in] aTextComparison The type of text comparison.

        */

        void PrepareViewL(

            RDbView& aView,

            const TDesC& aDbQuery,

            TDbTextComparison aTextComparison = EDbCompareCollated );

        /**

        * Evaluates a single step of given view if needed.

        * Increments the evaluation counter (needed for progress calculation).

        */

        void EvaluateViewL( RDbView& aView );

        /**

        * Reads the next row in a view.

        * @param[in,out] aView The view to read.

        * @return ETrue if there are more rows in the view. EFalse otherwise.

        */

        TBool MoreInView( RDbView& aView ) const;

        /**

        * Gets the current row data of given view for access.

        * Increments the row counter (needed for progress calculation).

        * @param[in] aView A view.

        */

        void GetRowL( RDbRowSet& aView );

        /**

        * Performs a stepwise synchronous search.

        *

        * It is assumed that the caller of this method does not call

        * this method again when max number of items have been reached

        * (i.e. @p ETrue was returned from the previous call).

        *

        * @param aMatchView A view, which holds match IDs

        * @param aMatchIdColumn Index of the ID column in aMatchView

        * @param aUseMatchViewForDisplayData If ETrue, then aMatchView can be

        *   used to retrieve display data.

        * 

        * @return @p ETrue if maxNumOfMatches has been reached after

        *   this search, otherwise @p EFalse.

        */

        TBool SearchViewL(

            RDbView& aMatchView,

            TInt aMatchIdColumn,

            TBool aUseMatchViewForDisplayData = ETrue );

        /**

        * Calculates progress and search status.

        * Should be called last in NextStepL.

        *

        * @param[in] aSearchFinished Should be set to @p EFalse if more steps are

        *   needed before the search has finished, otherwise @p ETrue.

        * @param[out aProgress Will be set to the progress of the search when

        * the step has finished.

        * @return @p KPosLmOperationNotComplete if the step has completed but

        *   more steps are needed before the search has finished,

        *   @p KErrNone if the search has finished successfully.

        */

        TInt SearchStepCompletedL( TBool aSearchFinished, TReal32& aProgress );

        /**

        * Gets the row count of aTable.

        * @param[in] aTable The table.

        * @return The number of rows.

        */

        TInt GetRowCountL( const TDesC& aTable );

        /**

        * Prepares for calculation of search progress.

        *

        * @param aNoOfRowsToEvaluate The number rows in the table(s) to search.

        * @param aSqlQueryIncludesSearchCondition @p ETrue if the db query

        *   will include a condition of which rows in a table that matches,

        *   @p EFalse if the db query will get all rows in a table.

        */

        void PrepareCalculateProgress(

            TInt aNoOfRowsToEvaluate,

            TBool aSqlQueryIncludesSearchCondition = ETrue );

        /**

        * Calculates the progress of a search.

        * @return The progress of the search.

        */

        TReal32 CalculateProgressL();

        /**

        * Adds a display item to the display data using the prefered sort order.

        *

        * @param aCurrentMatch The item id of the item add to the display data.

        * @param aDistance The distance to be used if the displayable item

        *   should be inserted in distance order.

        *

        * @return The position of the added match.

        */

        TInt AddMatchToDisplayDataL(

            TPosLmItemId aCurrentMatch,

            RDbRowSet* aView = NULL,

            TBool aSuppressSorting = EFalse,

            TReal32 aDistance = KPosUndefinedDistance );

        /** Opend LM table and landmarks index */

        void PrepareLandmarkIndexL();

        /* Loads more landmarks from index if needed */

        void EvaluateLandmarkIndexL();

        /** Loads all items of landmark name index. 

         *  The index should be in EModeFull mode to keep the loaded items. */

        void LoadFullLandmarkIndexL();

        /** Checks whether landmark index has more items */

    	TBool MoreInLandmarkIndex() const; 

        /** Finds row in Lm table, by given ID */

        TBool GetLandmarkRowL( TPosLmItemId aLmid );

        /**

        * Creates a new display item to be added to the display data.

        *

        * @param aMatchId The item id of the item to create.

        * @param aRow A row, which contains item data 

        * @return A displayable item.

        */

        CPosLmDisplayItem* CreateItemLC( 

        	TPosLmItemId aMatchId,

        	RDbRowSet* aRow = NULL );

        /** Returns ETrue if current amount of items in 

         *  display data is equal or greater than given

         *  initial amount. Used to break search loops in more steps,

         *  than Evaluate does,

         *  because reading display data is a long operation.

         *  Always returns EFalse if display data is not use */

        TBool BreakOnDisplayData( TInt aInitialDdMatches ) const;

        /** Returns count of display data items, or 0 if no display data used */

        TInt DisplayDataCount() const;

        /** Closes view, table and index iterator */

        void CleanupSources();

    private:

        /** Loads more landmarks from index */

        void GetMoreSortedLandmarksL();

        // By default, prohibit copy constructor

        CPosLmLocalSearchHandler( const CPosLmLocalSearchHandler& );

        // Prohibit assigment operator

        CPosLmLocalSearchHandler& operator= ( const CPosLmLocalSearchHandler& );

    protected:  // Data

        // The view used during the search

        RDbView iView;

        // A table used during the search

        RDbTable iTable;

        // If ETrue, new display data items are appended,

        // regardless of current sorting preference.

        // Used when data come pre-sorted from source view or table

        TBool iSuppressDisplayDataSorting;

        // Landmark Name index iterator

        CPosLmNameIndexIterator* iLandmarkIndex;

        // Array containing results from current search

        RArray<TPosLmItemId> iCurrentMatches;

    private:  // Data

        CPosLmLocalDatabase& iDatabase;

        // The database to search

        CPosLmLocalDbAccess* iDbAccess;

        // The local sort preference

        TPosLmLocalSortPref iLocalSortPref;

        // The max number of matches to search for.

        TInt iMaxNumOfMatches;

        // Tells whether previous result should be used or not

        TBool iSearchOnlyPreviousMatches;

        // Array containing results from a previous search

        RArray<TUint> iPreviousMatches;

        TPosLmProgressHelper iProgressHelper;

        // Stores next sort index for separate sorting search

        TInt iNextSortIndex;

        // Stores the criteria type

        CPosLmSearchCriteria::TCriteriaType iCriteriaType;

        // Stores the partial read parameters

        CPosLmPartialReadParameters* iPartialReadParameters;

        // The display data. Not owned by this class

        CPosLmDisplayData* iDisplayData;

        };

#endif      // CPOSLMLOCALSEARCHHANDLER_H