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_ENGINE_H__

    21 #define __LANDMARKS_ENGINE_H__

    22 

    23 

    24 #include "LandmarksEngineBase.h"

    25 #include "LandmarksOperationObserver.h"

    26 #include <EPos_TPosLmSortPref.h>

    27 

    28 

    29 class CPosLandmark;

    30 

    31 

    32 

    33 /**

    34 *  Implements all functions of the engine related to landmarks. This engine

    35 *  servs the landmarks view.

    36 */

    37 class CLandmarksEngine : public CLandmarksEngineBase

    38     {

    39     public: // Constructors and destructor

    40 

    41         /**

    42         * Two-phased constructor.

    43         *

    44         * @param aDb an instance of the defaukt landmark database

    45         */

    46         static CLandmarksEngine* NewL(

    47             CPosLandmarkDatabase& aDb);

    48 

    49         /**

    50         * Destructor.

    51         */

    52         ~CLandmarksEngine();

    53 

    54     public: // New functions

    55 

    56         /**

    57         * StartInitializeDbIfNecessaryL indicates if the default database needs

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

    59         * initialized the initialization is started immediately and the

    60         * supplied observer is notified when initialization is ready.

    61         *

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

    63         * ready

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

    65         */

    66         TBool StartInitializeDbIfNecessaryL(MLandmarksOperationObserver* aObserver);

    67 

    68         /**

    69         * AddLandmarkL adds a landmark to the database.

    70         *

    71         * @param aLandmark the landmark to add

    72         */

    73         void AddLandmarkL(CPosLandmark& aLandmark);

    74 

    75         /**

    76         * CommitLandmarkL commits a modified landmark.

    77         *

    78         * @param aLandmark the landmark to commit

    79         */

    80         void CommitLandmarkL(const CPosLandmark& aLandmark);

    81 

    82         /**

    83         * DeleteLandmarkL deletes a landmark.

    84         *

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

    86         */

    87         void DeleteLandmarkL(TPosLmItemId aItemId);

    88 

    89         /**

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

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

    92         * to the caller.

    93         *

    94         * @param aItemId the ItemId identifying the landmark

    95         * @return a landmark

    96         */

    97         CPosLandmark* LandmarkLC(TPosLmItemId aItemId);

    98 

    99         /**

   100         * StartSearchingLandmarksL starts an asynchronous search operation for

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

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

   103         * @ref FetchLandmarkSearchResult. All landmarks in the database are

   104         * returned.

   105         *

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

   107         * operation completes

   108         */

   109         void StartSearchingLandmarksL(

   110             MLandmarksOperationObserver* aObserver);

   111 

   112         /**

   113         * StartSearchingLandmarksL starts an asynchronous search operation for

   114         * landmarks. The names of the landmarks are uses as criterion for a

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

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

   117         * @ref FetchLandmarkSearchResult.

   118         *

   119         * @param aSearchPattern search pattern to compare landmarks against

   120         * @param aSearchOnlyInPreviousMatches boolean indicating that only

   121         * previous matches should be searched

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

   123         * operation completes

   124         */

   125         void StartSearchingLandmarksL(

   126             const TDesC& aSearchPattern,

   127             TBool aSearchOnlyInPreviousMatches,

   128             MLandmarksOperationObserver* aObserver);

   129 

   130         /**

   131         * FetchSearchResultL should be called after a successful

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

   133         * previous landmark search operation. Ownership of the returned array

   134         * is kept by this class.

   135         *

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

   137         * operation

   138         */

   139         RArray<TPosLmItemId>* FetchSearchResult();

   140 

   141         /**

   142         * StartReadingLandmarksL should be called after a successful

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

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

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

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

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

   148         * be called to fetch the read landmarks.

   149         *

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

   151         * notifying the supplied observer

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

   153         * landmarks are read

   154         */

   155         void StartReadingLandmarksL(

   156             TInt aNrOfItemsToReadPerBundle,

   157             MLandmarksOperationObserver* aObserver);

   158 

   159         /**

   160         * FetchLandmarksLC should be called after a successful landmark read

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

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

   163         * is transferred to the caller.

   164         *

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

   166         * read operation

   167         */

   168         CArrayPtr<CPosLandmark>* FetchLandmarksLC();

   169 

   170 

   171     protected: // From CActive

   172 

   173         /**

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

   175         */

   176         void RunL();

   177 

   178         /**

   179         * Implements cancellation of an outstanding request.

   180         */

   181         void DoCancel();

   182 

   183         /**

   184         * Handles a leave occurring in the request completion event

   185         * handler RunL().

   186         *

   187         * @return KErrNone

   188         */

   189         TInt RunError(TInt aError);

   190 

   191     private: // New functions

   192 

   193         /**

   194         * C++ constructor.

   195         *

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

   197         */

   198         CLandmarksEngine(CPosLandmarkDatabase& aDb);

   199 

   200         /**

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

   202         */

   203         void ConstructL();

   204 

   205         /**

   206         * ReadSomeLandmarksL reads a number of landmarks. The number of

   207         * landmarks is specified when initiating an asynchronous landmark read

   208         * operation.

   209         */

   210         void ReadSomeLandmarksL();

   211 

   212         /**

   213         * NotifyOperationReadyL notifies the observer of an asynchronous

   214         * operation that the operation has completed.

   215         *

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

   217         * @param aErrorCode the complete code the operation returned

   218         */

   219         void NotifyOperationReadyL(TOperation aOperation, TInt aErrorCode);

   220 

   221         /**

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

   223         * member @ref iItemIds

   224         */

   225         void PopulateItemIdArrayL();

   226 

   227     private: // Data

   228 

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

   230         RArray<TPosLmItemId> iItemIds;

   231 

   232         //! the observer to notify the progress asynchronous operations

   233         MLandmarksOperationObserver* iObserver;

   234 

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

   236         TOperation iActiveOperation;

   237 

   238         //! keeps track of which item to read

   239         TInt iCurrentItemId;

   240 

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

   242         TInt iNrOfItemsToRead;

   243 

   244         //! indicates if there is any previous result to search

   245         TBool iSearchResultExists;

   246 

   247         /** indicates if the current search operation has been carried

   248         out with or without search pattern */

   249         TBool iFilterSearch;

   250 

   251         //! defines the sort preferences for this engine

   252         TPosLmSortPref iSortPref;

   253 

   254     };

   255 

   256 #endif // __LANDMARKS_ENGINE_H__

   257