1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Base class for criteria based searches.

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLMLOCALSEARCHHANDLER_H

    20 #define CPOSLMLOCALSEARCHHANDLER_H

    21 

    22 #include <d32dbms.h>

    23 #include <EPos_CPosLmSearchCriteria.h>

    24 #include <epos_rposlmlocalnameindex.h>

    25 #include "EPos_TPosLmLocalSortPref.h"

    26 #include "EPos_TPosLmProgressHelper.h"

    27 

    28 const TReal32 KProgressCompleted = 1.0;

    29 const TReal32 KPosUndefinedDistance = -1;

    30 

    31 class CPosLmDisplayItem;

    32 class CPosLmDisplayData;

    33 class CPosLmLocalDbAccess;

    34 class CPosLmNameIndexIterator;

    35 class CPosLmLocalDatabase;

    36 

    37 /**

    38 *  Base class for criteria based searches.

    39 */

    40 class CPosLmLocalSearchHandler : public CBase

    41     {

    42     public:  // Constructors and destructor

    43 

    44         /**

    45         * Destructor.

    46         */

    47         virtual ~CPosLmLocalSearchHandler();

    48 

    49     public: // New functions

    50 

    51         /**

    52         * Factory method for creating an instance of the

    53         * CPosLmLocalSearchHandler subclass that corresponds to the search

    54         * criteria.

    55         *

    56         * The caller takes ownership of the returned object.

    57         *

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

    59         * @param[in] aCriteria The search criteria.

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

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

    62         *   not transferred.

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

    64         *   searched for.

    65         * @return An instance of a CPosLmLocalSearchHandler subclass.

    66         */

    67         static CPosLmLocalSearchHandler* CreateHandlerL(

    68             CPosLmLocalDatabase& aDatabase,

    69             const CPosLmSearchCriteria& aCriteria,

    70             const TPosLmLocalSortPref& aSortPref,

    71             CPosLmDisplayData* aDisplayData,

    72             TInt aMaxNumOfMatches );

    73 

    74         /**

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

    76         * included in this array.

    77         *

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

    79         */

    80         void SetPreviousMatchesToSearchL(

    81                 const RArray<TPosLmItemId>& aPreviousMatches );

    82 

    83         /**

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

    85         *

    86         * @return EFalse unless overriden in derived class.

    87         */

    88         virtual TBool IsValidForLandmarkSearch() const;

    89 

    90         /**

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

    92         *

    93         * @return EFalse unless overriden in derived class.

    94         */

    95         virtual TBool IsValidForCategorySearch() const;

    96 

    97         /**

    98         * Synchronous incremental execution of the search. Performs a single

    99         * step of the search synchronously.

   100         *

   101         * Leaves with an error code if something goes wrong.

   102         *

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

   104         * the step has finished.

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

   106         *   more steps are needed before the search has finished,

   107         *   @p KErrNone if the search has finished successfully.

   108         */

   109         virtual TInt NextStepL( TReal32& aProgress ) = 0;

   110 

   111         /**

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

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

   114         * deleted before NextStepL has returned @p KErrNone.)

   115         */

   116         virtual void CancelSearch();

   117 

   118         /**

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

   120         * matches encountered so far will be returned.

   121         *

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

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

   124         */

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

   126 

   127         /**

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

   129         * matches encountered so far will be returned.

   130         *

   131         * @return Array containing the landmark item IDs found

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

   133         */

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

   135 

   136     protected:

   137 

   138         /**

   139         * C++ default constructor.

   140         *

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

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

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

   144         *   searched for.

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

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

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

   148         */

   149         CPosLmLocalSearchHandler(

   150             CPosLmLocalDatabase& aDatabase,

   151             CPosLmSearchCriteria::TCriteriaType aCriteriaType,

   152             const TPosLmLocalSortPref& aSortPref,

   153             TInt aMaxNumOfMatches );

   154 

   155         /**

   156         * Set display data.

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

   158         *

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

   160         */

   161         void SetDisplayDataL( CPosLmDisplayData* aData );

   162 

   163         /**

   164         * Tells if display data has been set.

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

   166         */

   167         TBool HasDisplayData() const;

   168 

   169         /**

   170         * @return Reference to display data object.

   171         */

   172         CPosLmDisplayData& DisplayData();

   173         const CPosLmDisplayData& DisplayData() const;

   174 

   175         /**

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

   177         * matches encountered so far will be returned.

   178         *

   179         * @return Array containing the landmark item IDs found

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

   181         */

   182         RArray<TPosLmItemId>& CurrentMatches();

   183 

   184         /**

   185         * Retrieves the maximum number of search matches.

   186         *

   187         * @return The maximum number of search matches or

   188         *   @p KPosLmMaxNumOfMatchesUnlimited if unlimited.

   189         */

   190         TInt MaxNumOfMatches() const;

   191         

   192         /**

   193         * Checks whether maximum number of matches have been found.

   194         */

   195         TBool IsMaxMatchesFound() const;

   196 

   197         /**

   198         * Returns the sort preference.

   199         * @return The sort preference.

   200         */

   201         const TPosLmLocalSortPref& SortPref() const;

   202 

   203         /**

   204         * Returns previous matches if set.

   205         *

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

   207         *   matches.

   208         */

   209         const RArray<TUint>& PreviousMatches() const;

   210 

   211         /**

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

   213         *

   214         * If SetPreviousMatchesToSearchL has NOT been called, this method will

   215         * always return @p ETrue.

   216         *

   217         * If SetPreviousMatchesToSearchL has been called, this method will

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

   219         * @p EFalse.

   220         *

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

   222         * @return See above.

   223         */

   224         TBool MatchesPreviousMatches( TPosLmItemId aCurrentMatch ) const;

   225 

   226         /**

   227         * Adds new match from an ongoing search.

   228         *

   229         * If SetPreviousMatchesToSearchL has been called, this match will be

   230         * added only if included in the previous matches.

   231         *

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

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

   234         * 	data. Forwarded o display data.

   235         */

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

   237 

   238         /**

   239         * Appends sort order to a db query.

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

   241         */

   242         void AppendSortToQueryL( HBufC* aDbQuery );

   243 

   244         /**

   245         * Prepares a view for a search.

   246         *

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

   248         * @param[in] aDbQuery The database query.

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

   250         */

   251         void PrepareViewL(

   252             RDbView& aView,

   253             const TDesC& aDbQuery,

   254             TDbTextComparison aTextComparison = EDbCompareCollated );

   255 

   256         /**

   257         * Evaluates a single step of given view if needed.

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

   259         */

   260         void EvaluateViewL( RDbView& aView );

   261 

   262         /**

   263         * Reads the next row in a view.

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

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

   266         */

   267         TBool MoreInView( RDbView& aView ) const;

   268 

   269         /**

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

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

   272         * @param[in] aView A view.

   273         */

   274         void GetRowL( RDbRowSet& aView );

   275 

   276         /**

   277         * Performs a stepwise synchronous search.

   278         *

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

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

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

   282         *

   283         * @param aMatchView A view, which holds match IDs

   284         * @param aMatchIdColumn Index of the ID column in aMatchView

   285         * @param aUseMatchViewForDisplayData If ETrue, then aMatchView can be

   286         *   used to retrieve display data.

   287         * 

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

   289         *   this search, otherwise @p EFalse.

   290         */

   291         TBool SearchViewL(

   292             RDbView& aMatchView,

   293             TInt aMatchIdColumn,

   294             TBool aUseMatchViewForDisplayData = ETrue );

   295 

   296         /**

   297         * Calculates progress and search status.

   298         * Should be called last in NextStepL.

   299         *

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

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

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

   303         * the step has finished.

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

   305         *   more steps are needed before the search has finished,

   306         *   @p KErrNone if the search has finished successfully.

   307         */

   308         TInt SearchStepCompletedL( TBool aSearchFinished, TReal32& aProgress );

   309 

   310         /**

   311         * Gets the row count of aTable.

   312         * @param[in] aTable The table.

   313         * @return The number of rows.

   314         */

   315         TInt GetRowCountL( const TDesC& aTable );

   316 

   317         /**

   318         * Prepares for calculation of search progress.

   319         *

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

   321         * @param aSqlQueryIncludesSearchCondition @p ETrue if the db query

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

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

   324         */

   325         void PrepareCalculateProgress(

   326             TInt aNoOfRowsToEvaluate,

   327             TBool aSqlQueryIncludesSearchCondition = ETrue );

   328 

   329         /**

   330         * Calculates the progress of a search.

   331         * @return The progress of the search.

   332         */

   333         TReal32 CalculateProgressL();

   334 

   335         /**

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

   337         *

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

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

   340         *   should be inserted in distance order.

   341         *

   342         * @return The position of the added match.

   343         */

   344         TInt AddMatchToDisplayDataL(

   345             TPosLmItemId aCurrentMatch,

   346             RDbRowSet* aView = NULL,

   347             TBool aSuppressSorting = EFalse,

   348             TReal32 aDistance = KPosUndefinedDistance );

   349         

   350         /** Opend LM table and landmarks index */

   351         void PrepareLandmarkIndexL();

   352         

   353         /* Loads more landmarks from index if needed */

   354         void EvaluateLandmarkIndexL();

   355         

   356         /** Loads all items of landmark name index. 

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

   358         void LoadFullLandmarkIndexL();

   359 

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

   361     	TBool MoreInLandmarkIndex() const; 

   362                

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

   364         TBool GetLandmarkRowL( TPosLmItemId aLmid );

   365         

   366         /**

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

   368         *

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

   370         * @param aRow A row, which contains item data 

   371         * @return A displayable item.

   372         */

   373         CPosLmDisplayItem* CreateItemLC( 

   374         	TPosLmItemId aMatchId,

   375         	RDbRowSet* aRow = NULL );

   376         

   377         /** Returns ETrue if current amount of items in 

   378          *  display data is equal or greater than given

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

   380          *  than Evaluate does,

   381          *  because reading display data is a long operation.

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

   383         TBool BreakOnDisplayData( TInt aInitialDdMatches ) const;

   384         

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

   386         TInt DisplayDataCount() const;

   387         

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

   389         void CleanupSources();

   390 

   391     private:

   392 

   393         /** Loads more landmarks from index */

   394         void GetMoreSortedLandmarksL();

   395 

   396         // By default, prohibit copy constructor

   397         CPosLmLocalSearchHandler( const CPosLmLocalSearchHandler& );

   398         // Prohibit assigment operator

   399         CPosLmLocalSearchHandler& operator= ( const CPosLmLocalSearchHandler& );

   400 

   401     protected:  // Data

   402 

   403         // The view used during the search

   404         RDbView iView;

   405 

   406         // A table used during the search

   407         RDbTable iTable;

   408         

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

   410         // regardless of current sorting preference.

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

   412         TBool iSuppressDisplayDataSorting;

   413 

   414         // Landmark Name index iterator

   415         CPosLmNameIndexIterator* iLandmarkIndex;

   416         

   417         // Array containing results from current search

   418         RArray<TPosLmItemId> iCurrentMatches;

   419 

   420     private:  // Data

   421 

   422         CPosLmLocalDatabase& iDatabase;

   423     

   424         // The database to search

   425         CPosLmLocalDbAccess* iDbAccess;

   426 

   427         // The local sort preference

   428         TPosLmLocalSortPref iLocalSortPref;

   429 

   430         // The max number of matches to search for.

   431         TInt iMaxNumOfMatches;

   432 

   433         // Tells whether previous result should be used or not

   434         TBool iSearchOnlyPreviousMatches;

   435 

   436         // Array containing results from a previous search

   437         RArray<TUint> iPreviousMatches;

   438 

   439         TPosLmProgressHelper iProgressHelper;

   440 

   441         // Stores next sort index for separate sorting search

   442         TInt iNextSortIndex;

   443 

   444         // Stores the criteria type

   445         CPosLmSearchCriteria::TCriteriaType iCriteriaType;

   446 

   447         // Stores the partial read parameters

   448         CPosLmPartialReadParameters* iPartialReadParameters;

   449 

   450         // The display data. Not owned by this class

   451         CPosLmDisplayData* iDisplayData;

   452         };

   453 

   454 #endif      // CPOSLMLOCALSEARCHHANDLER_H

   455