--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/locationlandmarksrefappfors60/Inc/LandmarksApplicationEngine.h Wed Sep 01 12:31:27 2010 +0100
@@ -0,0 +1,349 @@
+/*
+* Copyright (c) 2004-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:
+* See class description below
+*
+*/
+
+
+#ifndef __LANDMARKS_APPLICATION_ENGINE_H__
+#define __LANDMARKS_APPLICATION_ENGINE_H__
+
+
+#include <e32base.h>
+#include <EPos_TPosLmSortPref.h>
+
+
+class CPosLandmark;
+class CPosLmOperation;
+class CPosLandmarkDatabase;
+class CPosLandmarkSearch;
+class CLandmarksEngine;
+class CLandmarksCategoriesEngine;
+class CLandmarksDbEventHandler;
+class MLandmarksDbObserver;
+class MLandmarksOperationObserver;
+class CPosLandmarkCategory;
+
+
+
+/**
+* CLandmarksApplicationEngine provides the main interface to the application
+* engine component.
+*
+* CLandmarksApplicationEngine is the only engine class UI-components need to
+* interact with. It uses the default landmark database for reading/writing
+* landmarks and categories.
+*
+*/
+class CLandmarksApplicationEngine : public CBase
+ {
+ public: // Constructors and destructor
+
+ /**
+ * Two-phased constructor.
+ *
+ * @returns A new instance of this class.
+ */
+ static CLandmarksApplicationEngine* NewL();
+
+ /**
+ * Destructor.
+ */
+ ~CLandmarksApplicationEngine();
+
+ public: // New functions
+
+ /**
+ * NotifyViewActivated notifies the engine which view is in focus. Should
+ * be called by views when they are activated/deactivated. This makes it
+ * possible for the engine to prioritize its asynchronous operations.
+ *
+ * @param aViewId the TUid identifying the view
+ * @param aIsActive ETrue if view is active, EFalse otherwise
+ */
+ void NotifyViewActivated(TUid aViewId, TBool aIsActive);
+
+ /**
+ * StartInitializeDbIfNecessaryL indicates if the default database needs
+ * to be initialised before it can be used. If it needs to be
+ * initialized the initialization is started immediately and the
+ * supplied observer is notified when initialization is ready.
+ *
+ * @param aObserver the observer to be notified when initialization is
+ * ready
+ * @return ETrue if initializing is necessary, EFalse otherwise
+ */
+ TBool StartInitializeDbIfNecessaryL(
+ MLandmarksOperationObserver* aObserver);
+
+ /**
+ * AddDbObserverL registers the supplied observer as observer of
+ * database events.
+ *
+ * @param aObserver the observer to be notified when a database event
+ * occurs
+ */
+ void AddDbObserverL(MLandmarksDbObserver* aObserver);
+
+ // Landmark related functions
+
+ /**
+ * LandmarkLC reads all fields of a landmark in the default
+ * landmark database. Ownership of the returned landmark is transferred
+ * to the caller.
+ *
+ * @param aItemId the ItemId identifying the landmark
+ * @return a landmark
+ */
+ CPosLandmark* LandmarkLC(TPosLmItemId aItemId);
+
+ /**
+ * CommitLandmarkL commits a modified landmark.
+ *
+ * @param aLandmark the landmark to commit
+ */
+ void CommitLandmarkL(const CPosLandmark& aLandmark);
+
+ /**
+ * DeleteLandmarkL deletes a landmark.
+ *
+ * @param aItemId the itemId identifying the landmark to be deleted
+ */
+ void DeleteLandmarkL(TPosLmItemId aItemId);
+
+ /**
+ * AddLandmarkL adds a landmark to the database.
+ *
+ * @param aLandmark the landmark to add
+ */
+ void AddLandmarkL(CPosLandmark& aLandmark);
+
+ /**
+ * StartSearchingLandmarksL starts an asynchronous search operation for
+ * landmarks. When the search completes the supplied observer is
+ * notified and it is supposed to fetch the matches by calling
+ * @ref FetchLandmarkSearchResult(). All landmarks in the database are
+ * returned.
+ *
+ * @param aObserver the observer that is notified when the search
+ * operation completes
+ */
+ void StartSearchingLandmarksL(
+ MLandmarksOperationObserver* aObserver);
+
+ /**
+ * StartSearchingLandmarksL starts an asynchronous search operation for
+ * landmarks. The names of the landmarks are used as criterion for a
+ * match. When the search completes the supplied observer is notified
+ * and it is supposed to fetch the matches by calling
+ * @ref FetchLandmarkSearchResult().
+ *
+ * @param aSearchPattern search pattern to compare landmarks against
+ * @param aSearchOnlyInPreviousMatches boolean indicating that only
+ * previous matches should be searched
+ * @param aObserver the observer that is notified when the search
+ * operation completes
+ */
+ void StartSearchingLandmarksL(
+ const TDesC& aSearchPattern,
+ TBool aSearchOnlyInPreviousMatches,
+ MLandmarksOperationObserver* aObserver);
+
+ /**
+ * FetchLandmarkSearchResult should be called after a successful
+ * landmark search operation. It returns the matches from the
+ * previous landmark search operation. Ownership of the returened array
+ * is kept by this class.
+ *
+ * @return an array containing matches from a previous landmark search
+ * operation
+ */
+ RArray<TPosLmItemId>* FetchLandmarkSearchResult();
+
+ /**
+ * StartReadingLandmarksL should be called after a successful
+ * landmark search operation. It continously reads a number of landmarks
+ * partially, i.e. only the name and the icon of the landmarks are read,
+ * until all landmarks found in a previous search operation are read.
+ * The method is asynchronous and every time a number of landmarks are
+ * read the supplied observer is notified, @ref FetchLandmarksLC should
+ * be called to fetch the read landmarks.
+ *
+ * @param aNrOfItemsToReadPerBundle the number of items to read before
+ * notifying the supplied observer
+ * @param aObserver the observer that is notified every time a bundle of
+ * landmarks are read
+ */
+ void StartReadingLandmarksL(
+ TInt aNrOfItemsToReadPerBundle,
+ MLandmarksOperationObserver* aObserver);
+
+ /**
+ * FetchLandmarksLC should be called after a successful landmark read
+ * operation. It returns the landmarks that were partially read during a
+ * preceding landmark read operation. Ownership of the returned array is
+ * transferred to the caller.
+ *
+ * @return an array containing partially read landmarks from a previous
+ * read operation
+ */
+ CArrayPtr<CPosLandmark>* FetchLandmarksLC();
+
+ // Category related functions
+
+ /**
+ * CategoryLC reads all fields of a category in the default
+ * landmark database. Ownership of the returned category is transferred
+ * to the caller.
+ *
+ * @param aItemId the ItemId identifying the category
+ * @return a category
+ */
+ CPosLandmarkCategory* CategoryLC(TPosLmItemId aItemId);
+
+ /**
+ * DeleteCategoryL deletes a category.
+ *
+ * @param aItemId the itemId identifying the category to be deleted
+ */
+ void DeleteCategoryL(TPosLmItemId aItemId);
+
+ /**
+ * UpdateCategoryL updates a modified category.
+ *
+ * @param aCategory the category to update
+ */
+ void UpdateCategoryL(const CPosLandmarkCategory& aCategory);
+
+ /**
+ * AddCategoryL adds a category to the default database.
+ *
+ * @param aCategory the category to add
+ */
+ void AddCategoryL(CPosLandmarkCategory& aCategory);
+
+ /**
+ * StartSearchingCategoriesL starts an asynchronous search operation for
+ * categories. When the search completes the supplied observer is
+ * notified and it is supposed to fetch the matches by calling
+ * @ref FetchCategorySearchResult. All categoiries in the database are
+ * returned.
+ *
+ * @param aObserver the observer that is notified when the search
+ * operation completes
+ */
+ void StartSearchingCategoriesL(
+ MLandmarksOperationObserver* aObserver);
+
+ /**
+ * StartSearchingCategoriesL starts an asynchronous search operation for
+ * categories. The names of the categories are used as criterion for a
+ * match. When the search completes the supplied observer is notified
+ * and it is supposed to fetch the matches by calling
+ * @ref FetchLandmarkSearchResult().
+ *
+ * @param aSearchPattern search pattern to compare landmarks against
+ * @param aSearchOnlyInPreviousMatches boolean indicating that only
+ * previous matches should be searched
+ * @param aObserver the observer that is notified when the search
+ * operation completes
+ */
+ void StartSearchingCategoriesL(
+ const TDesC& aSearchPattern,
+ TBool aSearchOnlyInPreviousMatches,
+ MLandmarksOperationObserver* aObserver);
+
+ /**
+ * FetchCategorySearchResult should be called after a successful
+ * category search operation. It returns the matches from the
+ * previous category search operation. Ownership of the returned array
+ * is kept by this class.
+ *
+ * @return an array containing matches from a previous categories search
+ * operation
+ */
+ RArray<TPosLmItemId>* FetchCategorySearchResult();
+
+ /**
+ * StartReadingCategoriesL should be called after a successful
+ * category search operation. It continously reads a number of
+ * categories until all landmarks found in a previous search operation
+ * are read. The method is asynchronous and every time a number of
+ * categories are read the supplied observer is notified.
+ * @ref FetchLandmarksLC should be called to fetch the read categories.
+ *
+ * @param aNrOfItemsToReadPerBundle the number of categories to read
+ * before notifying the supplied observer
+ * @param aObserver the observer that is notified every time a bundle of
+ * categories are read
+ */
+ void StartReadingCategoriesL(
+ TInt aNrOfItemsToReadPerBundle,
+ MLandmarksOperationObserver* aObserver);
+
+ /**
+ * FetchCategoriesLC should be called after a successful category read
+ * operation. It returns the categories that were read during a
+ * preceding landmark read operation. Ownership of teh returned array is
+ * transferred to the caller.
+ *
+ * @return an array containing partially read landmarks from a previous
+ * read operation
+ */
+ CArrayPtr<CPosLandmarkCategory>* FetchCategoriesLC();
+
+ /**
+ * CategoriesL reads all categories in the default database
+ * synchronously. Ownership of the returned array is transferred to the
+ * caller.
+ *
+ * @return an array containing all categories in the database.
+ */
+ CArrayPtr<CPosLandmarkCategory>* CategoriesL();
+
+ /** Returns URI of current landmarks database */
+ HBufC* DatabaseUriLC();
+
+ private:
+
+ /**
+ * C++ default constructor.
+ */
+ CLandmarksApplicationEngine();
+
+ /**
+ * By default Symbian 2nd phase constructor is private.
+ */
+ void ConstructL();
+
+ private: // Data
+
+ //! Default landmark database
+ CPosLandmarkDatabase* iDb;
+
+ //! Landmarks engine part
+ CLandmarksEngine* iLandmarksEngine;
+
+ //! Categories engine part
+ CLandmarksCategoriesEngine* iCategoriesEngine;
+
+ //! Database event handler
+ CLandmarksDbEventHandler* iDbEventHandler;
+
+ };
+
+
+#endif // __LANDMARKS_APPLICATION_ENGINE_H__
+