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_APPLICATION_ENGINE_H__

    21 #define __LANDMARKS_APPLICATION_ENGINE_H__

    22 

    23 

    24 #include <e32base.h>

    25 #include <EPos_TPosLmSortPref.h>

    26 

    27 

    28 class CPosLandmark;

    29 class CPosLmOperation;

    30 class CPosLandmarkDatabase;

    31 class CPosLandmarkSearch;

    32 class CLandmarksEngine;

    33 class CLandmarksCategoriesEngine;

    34 class CLandmarksDbEventHandler;

    35 class MLandmarksDbObserver;

    36 class MLandmarksOperationObserver;

    37 class CPosLandmarkCategory;

    38 

    39 

    40 

    41 /**

    42 *  CLandmarksApplicationEngine provides the main interface to the application 

    43 *  engine component.

    44 *  

    45 *  CLandmarksApplicationEngine is the only engine class UI-components need to 

    46 *  interact with. It uses the default landmark database for reading/writing

    47 *  landmarks and categories.

    48 *

    49 */

    50 class CLandmarksApplicationEngine : public CBase

    51     {

    52     public: // Constructors and destructor

    53 

    54         /**

    55         * Two-phased constructor.

    56         *

    57         * @returns A new instance of this class.

    58         */

    59         static CLandmarksApplicationEngine* NewL();

    60 

    61         /**

    62         * Destructor.

    63         */

    64         ~CLandmarksApplicationEngine();

    65 

    66     public: // New functions

    67 

    68         /**

    69         * NotifyViewActivated notifies the engine which view is in focus. Should

    70         * be called by views when they are activated/deactivated. This makes it

    71         * possible for the engine to prioritize its asynchronous operations.

    72         *

    73         * @param aViewId the TUid identifying the view

    74         * @param aIsActive ETrue if view is active, EFalse otherwise

    75         */

    76         void NotifyViewActivated(TUid aViewId, TBool aIsActive);

    77 

    78         /**

    79         * StartInitializeDbIfNecessaryL indicates if the default database needs

    80         * to be initialised before it can be used. If it needs to be 

    81         * initialized the initialization is started immediately and the 

    82         * supplied observer is notified when initialization is ready.

    83         *

    84         * @param aObserver the observer to be notified when initialization is 

    85         * ready

    86         * @return ETrue if initializing is necessary, EFalse otherwise

    87         */

    88         TBool StartInitializeDbIfNecessaryL(

    89             MLandmarksOperationObserver* aObserver);

    90 

    91         /**

    92         * AddDbObserverL registers the supplied observer as observer of 

    93         * database events.

    94         *

    95         * @param aObserver the observer to be notified when a database event 

    96         * occurs

    97         */

    98         void AddDbObserverL(MLandmarksDbObserver* aObserver);

    99 

   100         // Landmark related functions

   101 

   102         /**

   103         * LandmarkLC reads all fields of a landmark in the default 

   104         * landmark database. Ownership of the returned landmark is transferred

   105         * to the caller.

   106         * 

   107         * @param aItemId the ItemId identifying the landmark

   108         * @return a landmark

   109         */

   110         CPosLandmark* LandmarkLC(TPosLmItemId aItemId);

   111 

   112         /**

   113         * CommitLandmarkL commits a modified landmark.

   114         *

   115         * @param aLandmark the landmark to commit

   116         */

   117         void CommitLandmarkL(const CPosLandmark& aLandmark);

   118 

   119         /**

   120         * DeleteLandmarkL deletes a landmark.

   121         *

   122         * @param aItemId the itemId identifying the landmark to be deleted

   123         */

   124         void DeleteLandmarkL(TPosLmItemId aItemId);

   125 

   126         /**

   127         * AddLandmarkL adds a landmark to the database.

   128         *

   129         * @param aLandmark the landmark to add

   130         */

   131         void AddLandmarkL(CPosLandmark& aLandmark);

   132 

   133         /**

   134         * StartSearchingLandmarksL starts an asynchronous search operation for

   135         * landmarks. When the search completes the supplied observer is 

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

   137         * @ref FetchLandmarkSearchResult(). All landmarks in the database are 

   138         * returned.

   139         * 

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

   141         * operation completes

   142         */

   143         void StartSearchingLandmarksL(

   144             MLandmarksOperationObserver* aObserver);

   145 

   146         /**

   147         * StartSearchingLandmarksL starts an asynchronous search operation for

   148         * landmarks. The names of the landmarks are used as criterion for a 

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

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

   151         * @ref FetchLandmarkSearchResult().

   152         * 

   153         * @param aSearchPattern search pattern to compare landmarks against

   154         * @param aSearchOnlyInPreviousMatches boolean indicating that only

   155         * previous matches should be searched

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

   157         * operation completes

   158         */

   159         void StartSearchingLandmarksL(

   160             const TDesC& aSearchPattern, 

   161             TBool aSearchOnlyInPreviousMatches,

   162             MLandmarksOperationObserver* aObserver);

   163 

   164         /**

   165         * FetchLandmarkSearchResult should be called after a successful 

   166         * landmark search operation. It returns the matches from the 

   167         * previous landmark search operation. Ownership of the returened array

   168         * is kept by this class.

   169         * 

   170         * @return an array containing matches from a previous landmark search

   171         * operation

   172         */

   173         RArray<TPosLmItemId>* FetchLandmarkSearchResult();

   174 

   175         /**

   176         * StartReadingLandmarksL should be called after a successful 

   177         * landmark search operation. It continously reads a number of landmarks 

   178         * partially, i.e. only the name and the icon of the landmarks are read,

   179         * until all landmarks found in a previous search operation are read.  

   180         * The method is asynchronous and every time a number of landmarks are  

   181         * read the supplied observer is notified, @ref FetchLandmarksLC should 

   182         * be called to fetch the read landmarks.

   183         *

   184         * @param aNrOfItemsToReadPerBundle the number of items to read before 

   185         * notifying the supplied observer

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

   187         * landmarks are read

   188         */

   189         void StartReadingLandmarksL(

   190             TInt aNrOfItemsToReadPerBundle,

   191             MLandmarksOperationObserver* aObserver);

   192 

   193         /**

   194         * FetchLandmarksLC should be called after a successful landmark read

   195         * operation. It returns the landmarks that were partially read during a

   196         * preceding landmark read operation. Ownership of the returned array is

   197         * transferred to the caller.

   198         *

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

   200         * read operation

   201         */

   202         CArrayPtr<CPosLandmark>* FetchLandmarksLC();

   203 

   204         // Category related functions

   205 

   206         /**

   207         * CategoryLC reads all fields of a category in the default 

   208         * landmark database. Ownership of the returned category is transferred

   209         * to the caller.

   210         * 

   211         * @param aItemId the ItemId identifying the category

   212         * @return a category

   213         */

   214         CPosLandmarkCategory* CategoryLC(TPosLmItemId aItemId);

   215 

   216         /**

   217         * DeleteCategoryL deletes a category.

   218         *

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

   220         */

   221         void DeleteCategoryL(TPosLmItemId aItemId);

   222 

   223         /**

   224         * UpdateCategoryL updates a modified category.

   225         *

   226         * @param aCategory the category to update

   227         */

   228         void UpdateCategoryL(const CPosLandmarkCategory& aCategory);

   229 

   230         /**

   231         * AddCategoryL adds a category to the default database.

   232         *

   233         * @param aCategory the category to add

   234         */

   235         void AddCategoryL(CPosLandmarkCategory& aCategory);

   236 

   237         /**

   238         * StartSearchingCategoriesL starts an asynchronous search operation for

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

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

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

   242         * returned.

   243         * 

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

   245         * operation completes

   246         */

   247         void StartSearchingCategoriesL(

   248             MLandmarksOperationObserver* aObserver);

   249 

   250         /**

   251         * StartSearchingCategoriesL starts an asynchronous search operation for

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

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

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

   255         * @ref FetchLandmarkSearchResult().

   256         * 

   257         * @param aSearchPattern search pattern to compare landmarks against

   258         * @param aSearchOnlyInPreviousMatches boolean indicating that only

   259         * previous matches should be searched

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

   261         * operation completes

   262         */

   263         void StartSearchingCategoriesL(

   264             const TDesC& aSearchPattern, 

   265             TBool aSearchOnlyInPreviousMatches,

   266             MLandmarksOperationObserver* aObserver);

   267 

   268         /**

   269         * FetchCategorySearchResult should be called after a successful 

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

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

   272         * is kept by this class.

   273         * 

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

   275         * operation

   276         */

   277         RArray<TPosLmItemId>* FetchCategorySearchResult();

   278 

   279         /**

   280         * StartReadingCategoriesL should be called after a successful 

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

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

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

   284         * categories are read the supplied observer is notified. 

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

   286         *

   287         * @param aNrOfItemsToReadPerBundle the number of categories to read 

   288         * before notifying the supplied observer

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

   290         * categories are read

   291         */

   292         void StartReadingCategoriesL(

   293             TInt aNrOfItemsToReadPerBundle,

   294             MLandmarksOperationObserver* aObserver);

   295 

   296         /**

   297         * FetchCategoriesLC should be called after a successful category read

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

   299         * preceding landmark read operation. Ownership of teh returned array is

   300         * transferred to the caller.

   301         *

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

   303         * read operation

   304         */

   305         CArrayPtr<CPosLandmarkCategory>* FetchCategoriesLC();

   306 

   307         /**

   308         * CategoriesL reads all categories in the default database 

   309         * synchronously. Ownership of the returned array is transferred to the

   310         * caller.

   311         *

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

   313         */

   314         CArrayPtr<CPosLandmarkCategory>* CategoriesL();

   315         

   316         /** Returns URI of current landmarks database */

   317         HBufC* DatabaseUriLC();

   318 

   319     private:

   320 

   321         /**

   322         * C++ default constructor.

   323         */

   324         CLandmarksApplicationEngine();

   325 

   326         /**

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

   328         */

   329         void ConstructL();

   330 

   331     private: // Data

   332 

   333         //! Default landmark database

   334         CPosLandmarkDatabase* iDb;

   335 

   336         //! Landmarks engine part

   337         CLandmarksEngine* iLandmarksEngine;

   338 

   339         //! Categories engine part

   340         CLandmarksCategoriesEngine* iCategoriesEngine;

   341 

   342         //! Database event handler

   343         CLandmarksDbEventHandler* iDbEventHandler;

   344 

   345     };

   346 

   347 

   348 #endif // __LANDMARKS_APPLICATION_ENGINE_H__

   349