--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/locationlandmarksrefappfors60/Inc/LandmarksEngine.h Wed Sep 01 12:31:27 2010 +0100
@@ -0,0 +1,257 @@
+/*
+* 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_ENGINE_H__
+#define __LANDMARKS_ENGINE_H__
+
+
+#include "LandmarksEngineBase.h"
+#include "LandmarksOperationObserver.h"
+#include <EPos_TPosLmSortPref.h>
+
+
+class CPosLandmark;
+
+
+
+/**
+* Implements all functions of the engine related to landmarks. This engine
+* servs the landmarks view.
+*/
+class CLandmarksEngine : public CLandmarksEngineBase
+ {
+ public: // Constructors and destructor
+
+ /**
+ * Two-phased constructor.
+ *
+ * @param aDb an instance of the defaukt landmark database
+ */
+ static CLandmarksEngine* NewL(
+ CPosLandmarkDatabase& aDb);
+
+ /**
+ * Destructor.
+ */
+ ~CLandmarksEngine();
+
+ public: // New functions
+
+ /**
+ * 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);
+
+ /**
+ * AddLandmarkL adds a landmark to the database.
+ *
+ * @param aLandmark the landmark to add
+ */
+ void AddLandmarkL(CPosLandmark& aLandmark);
+
+ /**
+ * 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);
+
+ /**
+ * 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);
+
+ /**
+ * 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 uses 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);
+
+ /**
+ * FetchSearchResultL should be called after a successful
+ * landmark search operation. It returns the matches from the
+ * previous landmark search operation. Ownership of the returned array
+ * is kept by this class.
+ *
+ * @return an array containing matches from a previous landmark search
+ * operation
+ */
+ RArray<TPosLmItemId>* FetchSearchResult();
+
+ /**
+ * 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();
+
+
+ protected: // From CActive
+
+ /**
+ * Handles an active object’s request completion event.
+ */
+ void RunL();
+
+ /**
+ * Implements cancellation of an outstanding request.
+ */
+ void DoCancel();
+
+ /**
+ * Handles a leave occurring in the request completion event
+ * handler RunL().
+ *
+ * @return KErrNone
+ */
+ TInt RunError(TInt aError);
+
+ private: // New functions
+
+ /**
+ * C++ constructor.
+ *
+ * @param aDb an instance of the default landmark database
+ */
+ CLandmarksEngine(CPosLandmarkDatabase& aDb);
+
+ /**
+ * By default Symbian 2nd phase constructor is private.
+ */
+ void ConstructL();
+
+ /**
+ * ReadSomeLandmarksL reads a number of landmarks. The number of
+ * landmarks is specified when initiating an asynchronous landmark read
+ * operation.
+ */
+ void ReadSomeLandmarksL();
+
+ /**
+ * NotifyOperationReadyL notifies the observer of an asynchronous
+ * operation that the operation has completed.
+ *
+ * @param aOperation the kind of operation that is finished
+ * @param aErrorCode the complete code the operation returned
+ */
+ void NotifyOperationReadyL(TOperation aOperation, TInt aErrorCode);
+
+ /**
+ * Fetches the matches after a search operation and populates the data
+ * member @ref iItemIds
+ */
+ void PopulateItemIdArrayL();
+
+ private: // Data
+
+ //! an array containing the item Ids of the last search
+ RArray<TPosLmItemId> iItemIds;
+
+ //! the observer to notify the progress asynchronous operations
+ MLandmarksOperationObserver* iObserver;
+
+ //! keeps track of which type of operation is executed
+ TOperation iActiveOperation;
+
+ //! keeps track of which item to read
+ TInt iCurrentItemId;
+
+ //! keeps track of how many items to read per bundle
+ TInt iNrOfItemsToRead;
+
+ //! indicates if there is any previous result to search
+ TBool iSearchResultExists;
+
+ /** indicates if the current search operation has been carried
+ out with or without search pattern */
+ TBool iFilterSearch;
+
+ //! defines the sort preferences for this engine
+ TPosLmSortPref iSortPref;
+
+ };
+
+#endif // __LANDMARKS_ENGINE_H__
+