1 /*

     2 * Copyright (c) 2004-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:  

    15 *     See class description below

    16 *

    17 */

    18 

    19 

    20 #ifndef __LANDMARKS_CATEGORIES_ENGINE_H__

    21 #define __LANDMARKS_CATEGORIES_ENGINE_H__

    22 

    23 

    24 #include "LandmarksEngineBase.h"

    25 #include "LandmarksOperationObserver.h"

    26 

    27 

    28 class CPosLmCategoryManager;

    29 class CPosLandmarkCategory;

    30 class CPosLandmarkDatabase;

    31 class CPosLmItemIterator;

    32 

    33 

    34 

    35 /**

    36 *  Implements all functions of the engine related to categories. This engine 

    37 *  servs the categories view.

    38 */

    39 class CLandmarksCategoriesEngine : public CLandmarksEngineBase

    40     {

    41     public: // Constructors and destructor

    42 

    43         /**

    44         * Two-phased constructor.

    45         *

    46         * @param aDb an instance of the default landmark database

    47         */

    48         static CLandmarksCategoriesEngine* NewL(CPosLandmarkDatabase& aDb);

    49 

    50         /**

    51         * Destructor.

    52         */

    53         ~CLandmarksCategoriesEngine();

    54 

    55     public: // New functions

    56 

    57         /**

    58         * AddCategoryL adds a category to the database.

    59         *

    60         * @param aCategory the landmark to add

    61         */

    62         void AddCategoryL(CPosLandmarkCategory& aCategory);

    63 

    64         /**

    65         * UpdateCategoryL updates a category in the database.

    66         *

    67         * @param aCategory the landmark to update

    68         */

    69         void UpdateCategoryL(const CPosLandmarkCategory& aCategory);

    70 

    71         /**

    72         * DeleteCategoryL deletes a category.

    73         *

    74         * @param aItemId the itemId identifying the category to be deleted

    75         */

    76         void DeleteCategoryL(TPosLmItemId aItemId);

    77 

    78         /**

    79         * CategoryLC reads a category in the default landmark database.

    80         * Ownership of the returned category is transferred to the caller. 

    81         * 

    82         * @param aItemId the ItemId identifying the category

    83         * @return a category

    84         */

    85         CPosLandmarkCategory* CategoryLC(TPosLmItemId aItemId);

    86 

    87         /**

    88         * StartSearchingCategoriesL starts an asynchronous search operation for

    89         * categories. When the search completes the supplied observer is 

    90         * notified and it is supposed to fetch the matches by calling 

    91         * @ref FetchCategorySearchResult. All categoiries in the database are 

    92         * returned.

    93         * 

    94         * @param aObserver the observer that is notified when the search 

    95         * operation completes

    96         */

    97         void StartSearchingCategoriesL(

    98             MLandmarksOperationObserver* aObserver);

    99 

   100         /**

   101         * StartSearchingCategoriesL starts an asynchronous search operation for

   102         * categories. The names of the categories are used as criterion for a

   103         * match. When the search completes the supplied observer is notified 

   104         * and it is supposed to fetch the matches by calling 

   105         * @ref FetchLandmarkSearchResult.

   106         * 

   107         * @param aSearchPattern search pattern to compare landmarks against

   108         * @param aSearchOnlyInPreviousMatches boolean indicating that only

   109         * previous matches should be searched

   110         * @param aObserver the observer that is notified when the search 

   111         * operation completes

   112         */

   113         void StartSearchingCategoriesL(

   114             const TDesC& aSearchPattern,

   115             TBool aSearchOnlyInPreviousMatches,

   116             MLandmarksOperationObserver* aObserver);

   117 

   118         /**

   119         * FetchSearchResultL should be called after a successful 

   120         * category search operation. It returns the matches from the 

   121         * previous category search operation. Ownership of the returned array 

   122         * is kept by this class.

   123         * 

   124         * @return an array containing matches from a previous categories search

   125         * operation

   126         */

   127         RArray<TPosLmItemId>* FetchSearchResult();

   128 

   129         /**

   130         * StartReadingCategoriesL should be called after a successful 

   131         * category search operation. It continously reads a number of 

   132         * categories until all landmarks found in a previous search operation 

   133         * are read. The method is asynchronous and every time a number of 

   134         * categories are read the supplied observer is notified. 

   135         * @ref FetchLandmarksLC should be called to fetch the read categories.

   136         *

   137         * @param aNrOfItemsToReadPerBundle the number of categories to read 

   138         * before notifying the supplied observer

   139         * @param aObserver the observer that is notified every time a bundle of 

   140         * categories are read

   141         */

   142         void StartReadingCategoriesL(

   143             TInt aNrOfItemsToReadPerBundle,

   144             MLandmarksOperationObserver* aObserver);

   145 

   146         /**

   147         * FetchCategoriesLC should be called after a successful category read

   148         * operation. It returns the categories that were read during a

   149         * preceding landmark read operation. Ownership of the returned array 

   150         * is transferred to the caller.

   151         *

   152         * @return an array containing partially read landmarks from a previous 

   153         * read operation

   154         */

   155         CArrayPtr<CPosLandmarkCategory>* FetchCategoriesLC();

   156 

   157         /**

   158         * CategoriesL reads all categories in the default database 

   159         * synchronously.Ownership of the returned array is transferred 

   160         * to the caller.

   161         *

   162         * @return an array containing all categories in the database.

   163         */

   164         CArrayPtr<CPosLandmarkCategory>* CategoriesL();

   165 

   166     protected: // From CActive

   167 

   168         /**

   169         * Handles an active object’s request completion event.

   170         */

   171         void RunL();

   172 

   173         /**

   174         * Implements cancellation of an outstanding request.

   175         */

   176         void DoCancel();

   177 

   178         /**

   179         * Handles a leave occurring in the request completion event 

   180         * handler RunL().

   181         *

   182         * @return KErrNone

   183         */

   184         TInt RunError(TInt aError);

   185 

   186     private: // New functions

   187 

   188         /**

   189         * C++ constructor.

   190         *

   191         * @param aDb an instance of the default landmark database

   192         */

   193         CLandmarksCategoriesEngine(CPosLandmarkDatabase& aDb);

   194 

   195         /**

   196         * By default Symbian 2nd phase constructor is private.

   197         */

   198         void ConstructL();

   199 

   200         /**

   201         * ReadSomeLandmarksL reads a number of categories. The number of 

   202         * categories is specified when initiating an asynchronous categories 

   203         * read operation.

   204         */

   205         void ReadSomeCategoriesL();

   206 

   207         /**

   208         * NotifyOperationReadyL notifies the observer of an asynchronous 

   209         * operation that the operation has completed.

   210         *

   211         * @param aOperation the kind of operation that is finished

   212         * @param aErrorCode the complete code the operation returned

   213         */

   214         void NotifyOperationReadyL(TOperation aOperation, TInt aErrorCode);

   215 

   216         /**

   217         * Fetches the matches after a search operation and populates the data 

   218         * member @ref iItemIds

   219         */

   220         void PopulateItemIdArrayL();

   221 

   222     private: // Data

   223 

   224         //! provides access to categories in the default database

   225         CPosLmCategoryManager* iCatManager;

   226 

   227         //! an array containing the item Ids of the last search

   228         RArray<TPosLmItemId> iItemIds;

   229 

   230         /** represents a subset of a search result. Used when 

   231             reading categories */

   232         RArray<TPosLmItemId> iSubSetOfIds;

   233 

   234         /** the observer to notify the progress of asynchronous 

   235             operations */

   236         MLandmarksOperationObserver* iObserver;

   237 

   238         //! keeps track of which type of operation is executed

   239         TOperation iActiveOperation;

   240 

   241         //! keeps track of which item to read

   242         TInt iCurrentItemId;

   243 

   244         //! keeps track of how many items to read per bundle

   245         TInt iNrOfItemsToRead;

   246 

   247         /** indicates if there is any previous result to 

   248             search */

   249         TBool iSearchResultExists;

   250 

   251         /** indicates if the current search operation has 

   252             carried out with or without search pattern */

   253         TBool iFilterSearch;

   254 

   255     };

   256 

   257 

   258 #endif // __LANDMARKS_CATEGORIES_ENGINE_H__

   259 

   260