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