/*
* 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__