Nokia N97 SDK
Example Applications Guide

CLandmarksEngine Class Reference

#include <LandmarksEngine.h>

Inheritance diagram for CLandmarksEngine:

CLandmarksEngineBase List of all members.

Detailed Description

Implements all functions of the engine related to landmarks. This engine servs the landmarks view.

Definition at line 33 of file LandmarksEngine.h.


Public Member Functions

  ~CLandmarksEngine ()
TBool  StartInitializeDbIfNecessaryL (MLandmarksOperationObserver *aObserver)
void  AddLandmarkL (CPosLandmark &aLandmark)
void  CommitLandmarkL (const CPosLandmark &aLandmark)
void  DeleteLandmarkL (TPosLmItemId aItemId)
CPosLandmark *  LandmarkLC (TPosLmItemId aItemId)
void  StartSearchingLandmarksL (MLandmarksOperationObserver *aObserver)
void  StartSearchingLandmarksL (const TDesC &aSearchPattern, TBool aSearchOnlyInPreviousMatches, MLandmarksOperationObserver *aObserver)
RArray< TPosLmItemId > *  FetchSearchResult ()
void  StartReadingLandmarksL (TInt aNrOfItemsToReadPerBundle, MLandmarksOperationObserver *aObserver)
CArrayPtr< CPosLandmark > *  FetchLandmarksLC ()
void  SetPrio (CActive::TPriority aPriority)

Static Public Member Functions

static CLandmarksEngine *  NewL (CPosLandmarkDatabase &aDb)

Protected Member Functions

void  RunL ()
void  DoCancel ()
TInt  RunError (TInt aError)
void  SetPriorityAndSetActive ()

Protected Attributes

CPosLandmarkDatabase &  iDb
  The default landmark database.
CPosLandmarkSearch *  iSearcher
  Used for searching the database.
CLandmarksLmOpWrapper *  iLmOpWrapper
  An active object wrapping a CPosLmOperation object.

Private Member Functions

  CLandmarksEngine (CPosLandmarkDatabase &aDb)
void  ConstructL ()
void  ReadSomeLandmarksL ()
void  NotifyOperationReadyL (TOperation aOperation, TInt aErrorCode)
void  PopulateItemIdArrayL ()

Private Attributes

RArray< TPosLmItemId >  iItemIds
  an array containing the item Ids of the last search
MLandmarksOperationObserver *  iObserver
  the observer to notify the progress asynchronous operations
TOperation  iActiveOperation
  keeps track of which type of operation is executed
TInt  iCurrentItemId
  keeps track of which item to read
TInt  iNrOfItemsToRead
  keeps track of how many items to read per bundle
TBool  iSearchResultExists
  indicates if there is any previous result to search
TBool  iFilterSearch
TPosLmSortPref  iSortPref
  defines the sort preferences for this engine


Constructor & Destructor Documentation

CLandmarksEngine::~CLandmarksEngine (   ) 
 

Destructor.

Definition at line 75 of file LandmarksEngine.cpp.

References iItemIds.

00076     {
00077     Cancel();
00078     iItemIds.Close();
00079     }

CLandmarksEngine::CLandmarksEngine (  CPosLandmarkDatabase &  aDb  )  [private]
 

C++ constructor.

Parameters:
aDb  an instance of the default landmark database

Definition at line 34 of file LandmarksEngine.cpp.

Referenced by NewL().

00036 :   CLandmarksEngineBase(aDb),
00037     iSortPref(CPosLandmark::ELandmarkName, TPosLmSortPref::EAscending)
00038     {
00039     }


Member Function Documentation

CLandmarksEngine * CLandmarksEngine::NewL (  CPosLandmarkDatabase &  aDb  )  [static]
 

Two-phased constructor.

Parameters:
aDb  an instance of the defaukt landmark database

Definition at line 64 of file LandmarksEngine.cpp.

References CLandmarksEngine().

Referenced by CLandmarksApplicationEngine::ConstructL().

00066     {
00067     CLandmarksEngine* self = new (ELeave) CLandmarksEngine(aDb);
00068     CleanupStack::PushL(self);
00069     self->ConstructL();
00070     CleanupStack::Pop(self);
00071     return self;
00072     }

TBool CLandmarksEngine::StartInitializeDbIfNecessaryL (  MLandmarksOperationObserver *  aObserver  ) 
 

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.

Parameters:
aObserver  the observer to be notified when initialization is ready
Returns:
ETrue if initializing is necessary, EFalse otherwise

Definition at line 87 of file LandmarksEngine.cpp.

References iActiveOperation, CLandmarksEngineBase::iDb, CLandmarksEngineBase::iLmOpWrapper, iObserver, CLandmarksEngineBase::SetPriorityAndSetActive(), and CLandmarksLmOpWrapper::StartOperation().

Referenced by CLandmarksApplicationEngine::StartInitializeDbIfNecessaryL().

00089     {
00090     if (iDb.IsInitializingNeeded())
00091         {
00092         // Create initialize operation
00093         CPosLmOperation* operation = iDb.InitializeL();
00094 
00095         iObserver = aObserver;
00096         iActiveOperation = EInitializeDb;
00097         iStatus = KRequestPending;
00098         SetPriorityAndSetActive();
00099 
00100         // Start asynchronous initialization
00101         TBool reportProgress = ETrue;
00102         iLmOpWrapper->StartOperation(operation, iStatus, reportProgress);
00103 
00104         return ETrue;
00105         }
00106     else
00107         {
00108         return EFalse;
00109         }
00110     }

void CLandmarksEngine::AddLandmarkL (  CPosLandmark &  aLandmark  ) 
 

AddLandmarkL adds a landmark to the database.

Parameters:
aLandmark  the landmark to add

Definition at line 118 of file LandmarksEngine.cpp.

References CLandmarksEngineBase::iDb.

Referenced by CLandmarksApplicationEngine::AddLandmarkL().

00119     {
00120     iDb.AddLandmarkL(aLandmark);
00121     }

void CLandmarksEngine::CommitLandmarkL (  const CPosLandmark &  aLandmark  ) 
 

CommitLandmarkL commits a modified landmark.

Parameters:
aLandmark  the landmark to commit

Definition at line 129 of file LandmarksEngine.cpp.

References CLandmarksEngineBase::iDb.

Referenced by CLandmarksApplicationEngine::CommitLandmarkL().

00130     {
00131     iDb.UpdateLandmarkL(aLandmark);
00132     }

void CLandmarksEngine::DeleteLandmarkL (  TPosLmItemId  aItemId  ) 
 

DeleteLandmarkL deletes a landmark.

Parameters:
aItemId  the itemId identifying the landmark to be deleted

Definition at line 140 of file LandmarksEngine.cpp.

References CLandmarksEngineBase::iDb.

Referenced by CLandmarksApplicationEngine::DeleteLandmarkL().

00141     {
00142     iDb.RemoveLandmarkL(aItemId);
00143     }

CPosLandmark * CLandmarksEngine::LandmarkLC (  TPosLmItemId  aItemId  ) 
 

LandmarkLC reads all fields of a landmark in the default landmark database. Ownership of the returned landmark is transferred to the caller.

Parameters:
aItemId  the ItemId identifying the landmark
Returns:
a landmark

Definition at line 151 of file LandmarksEngine.cpp.

References CLandmarksEngineBase::iDb.

00152     {
00153     return iDb.ReadLandmarkLC(aItemId);
00154     }

void CLandmarksEngine::StartSearchingLandmarksL (  MLandmarksOperationObserver *  aObserver  ) 
 

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 FetchLandmarkSearchResult. All landmarks in the database are returned.

Parameters:
aObserver  the observer that is notified when the search operation completes

Definition at line 162 of file LandmarksEngine.cpp.

References iActiveOperation, iFilterSearch, iObserver, iSearchResultExists, and CLandmarksEngineBase::SetPriorityAndSetActive().

Referenced by CLandmarksApplicationEngine::StartSearchingLandmarksL().

00164     {
00165     // We need to cancel if we are searching/reading landmarks.
00166     Cancel(); 
00167 
00168     iObserver = aObserver;
00169     iSearchResultExists = EFalse;
00170     iFilterSearch = EFalse;
00171     
00172     // Complete ourselves and start search for all landmarks in db in RunL().
00173     iStatus = KRequestPending;
00174     SetPriorityAndSetActive();
00175     iActiveOperation = ELandmarkSearch;
00176     TRequestStatus* status = &iStatus;
00177     User::RequestComplete(status, KErrNone);
00178     }

void CLandmarksEngine::StartSearchingLandmarksL (  const TDesC &  aSearchPattern,
TBool  aSearchOnlyInPreviousMatches,
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 FetchLandmarkSearchResult.

Parameters:
aSearchPattern  search pattern to compare landmarks against
aSearchOnlyInPreviousMatches  boolean indicating that only previous matches should be searched
aObserver  the observer that is notified when the search operation completes

Definition at line 186 of file LandmarksEngine.cpp.

References iActiveOperation, iFilterSearch, CLandmarksEngineBase::iLmOpWrapper, iObserver, CLandmarksEngineBase::iSearcher, iSearchResultExists, iSortPref, CLandmarksEngineBase::SetPriorityAndSetActive(), and CLandmarksLmOpWrapper::StartOperation().

00190     {
00191     // We need to cancel if we are searching/reading landmarks.
00192     Cancel();
00193 
00194     if (!iSearchResultExists)
00195         {
00196         // There are no previous results or previous search did not complete.
00197         // We cannot use the result from it.
00198         aSearchOnlyInPreviousMatches = EFalse;
00199         }
00200     iSearchResultExists = EFalse;
00201     iFilterSearch = ETrue;
00202 
00203     // Set search criteria
00204     CPosLmTextCriteria* criteria = CPosLmTextCriteria::NewLC();
00205     criteria->SetTextL(aSearchPattern);
00206     criteria->SetAttributesToSearch(CPosLandmark::ELandmarkName);
00207 
00208     // Create search operation
00209     CPosLmOperation* operation = iSearcher->StartLandmarkSearchL(
00210         *criteria, iSortPref, aSearchOnlyInPreviousMatches);
00211     CleanupStack::PopAndDestroy(criteria);
00212 
00213     // Start search operation
00214     iObserver = aObserver;
00215     iStatus = KRequestPending;
00216     iLmOpWrapper->StartOperation(operation, iStatus);
00217     SetPriorityAndSetActive();
00218     iActiveOperation = ELandmarkSearch;
00219     }

RArray< TPosLmItemId > * CLandmarksEngine::FetchSearchResult (   ) 
 

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.

Returns:
an array containing matches from a previous landmark search operation

Definition at line 227 of file LandmarksEngine.cpp.

References iItemIds.

Referenced by CLandmarksApplicationEngine::FetchLandmarkSearchResult().

00228     {
00229     return &iItemIds;
00230     }

void CLandmarksEngine::StartReadingLandmarksL (  TInt  aNrOfItemsToReadPerBundle,
MLandmarksOperationObserver *  aObserver
) 
 

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, FetchLandmarksLC should be called to fetch the read landmarks.

Parameters:
aNrOfItemsToReadPerBundle  the number of items to read before notifying the supplied observer
aObserver  the observer that is notified every time a bundle of landmarks are read

Definition at line 238 of file LandmarksEngine.cpp.

References iActiveOperation, iCurrentItemId, iNrOfItemsToRead, iObserver, and ReadSomeLandmarksL().

Referenced by CLandmarksApplicationEngine::StartReadingLandmarksL().

00241     {
00242     // We need to cancel if we are searching/reading landmarks.
00243     Cancel();
00244 
00245     iNrOfItemsToRead = aNrOfItemsToReadPerBundle;
00246     iObserver = aObserver;
00247     iCurrentItemId = 0;
00248 
00249     // Start reading a bundle of landmarks
00250     ReadSomeLandmarksL();
00251     iActiveOperation = ELandmarkRead;
00252     }

CArrayPtr< CPosLandmark > * CLandmarksEngine::FetchLandmarksLC (   ) 
 

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.

Returns:
an array containing partially read landmarks from a previous read operation

Definition at line 260 of file LandmarksEngine.cpp.

References CLandmarksEngineBase::iDb, CLandmarksEngineBase::iLmOpWrapper, and CLandmarksLmOpWrapper::LmOperationPtr().

Referenced by CLandmarksApplicationEngine::FetchLandmarksLC().

00261     {
00262     // Fetch the partially read landmarks.
00263     CArrayPtr<CPosLandmark>* result = 
00264         iDb.TakePreparedPartialLandmarksL(iLmOpWrapper->LmOperationPtr());
00265     CleanupStack::PushL(result);
00266 
00267     return result;
00268     }

void CLandmarksEngine::RunL (   )  [protected, virtual]
 

Handles an active object’s request completion event.

Implements CLandmarksEngineBase.

Definition at line 276 of file LandmarksEngine.cpp.

References CLandmarksLmOpWrapper::ExecuteNextStep(), iActiveOperation, iCurrentItemId, iItemIds, CLandmarksEngineBase::iLmOpWrapper, iObserver, MLandmarksOperationObserver::NotifyOperationProgressL(), NotifyOperationReadyL(), PopulateItemIdArrayL(), CLandmarksLmOpWrapper::Progress(), ReadSomeLandmarksL(), and CLandmarksEngineBase::SetPriorityAndSetActive().

00277     {
00278     if (iActiveOperation == EInitializeDb)
00279         {
00280         // Report progress
00281         iObserver->NotifyOperationProgressL(
00282             iActiveOperation, iLmOpWrapper->Progress(), iStatus.Int());
00283 
00284         if (iStatus == KPosLmOperationNotComplete)
00285             {
00286             // Continue initializing database until finished
00287             iStatus = KRequestPending;
00288             SetPriorityAndSetActive();
00289             iLmOpWrapper->ExecuteNextStep(iStatus);
00290             }
00291         }
00292     else if (iStatus != KErrNone)
00293         {
00294         // Operation failed. Report error code
00295         NotifyOperationReadyL(iActiveOperation, iStatus.Int());
00296         }
00297     else if (iActiveOperation == ELandmarkSearch)
00298         {
00299         // Fetch search result
00300         PopulateItemIdArrayL();
00301         }
00302     else if (iActiveOperation == ELandmarkRead)
00303         {
00304         if (iCurrentItemId < iItemIds.Count())
00305             {
00306             // There are still found landmarks to read
00307             iObserver->NotifyOperationProgressL(iActiveOperation, KOperationNotReady, KErrNone);
00308             ReadSomeLandmarksL();
00309             }
00310         else
00311             {
00312             // No more matches to read
00313             NotifyOperationReadyL(iActiveOperation, KErrNone);
00314             }
00315         }
00316     }

void CLandmarksEngine::DoCancel (   )  [protected, virtual]
 

Implements cancellation of an outstanding request.

Implements CLandmarksEngineBase.

Definition at line 324 of file LandmarksEngine.cpp.

References iActiveOperation, CLandmarksEngineBase::iLmOpWrapper, and iSearchResultExists.

00325     {
00326     iLmOpWrapper->Cancel();
00327 
00328     if (iActiveOperation == ELandmarkSearch)
00329         {
00330         iSearchResultExists = EFalse;
00331         }
00332     iActiveOperation = ENoOperation;
00333     }

TInt CLandmarksEngine::RunError (  TInt  aError  )  [protected, virtual]
 

Handles a leave occurring in the request completion event handler RunL().

Returns:
KErrNone

Implements CLandmarksEngineBase.

Definition at line 341 of file LandmarksEngine.cpp.

References iActiveOperation, and NotifyOperationReadyL().

00342     {
00343     // Notify user and ignore error code
00344     TInt err;
00345     TRAP(err, NotifyOperationReadyL(iActiveOperation, aError));
00346 
00347     return KErrNone;
00348     }

void CLandmarksEngine::ConstructL (   )  [private]
 

By default Symbian 2nd phase constructor is private.

Reimplemented from CLandmarksEngineBase.

Definition at line 46 of file LandmarksEngine.cpp.

References CLandmarksEngineBase::ConstructL(), and CLandmarksEngineBase::iDb.

00047     {
00048     CLandmarksEngineBase::ConstructL();
00049 
00050     // Set partial read parameters
00051     CPosLmPartialReadParameters* partialReadParams = 
00052         CPosLmPartialReadParameters::NewLC();
00053     partialReadParams->SetRequestedAttributes(
00054         CPosLandmark::ELandmarkName | CPosLandmark::EIcon);
00055     iDb.SetPartialReadParametersL(*partialReadParams);
00056     CleanupStack::PopAndDestroy(partialReadParams);
00057     }

void CLandmarksEngine::ReadSomeLandmarksL (   )  [private]
 

ReadSomeLandmarksL reads a number of landmarks. The number of landmarks is specified when initiating an asynchronous landmark read operation.

Definition at line 356 of file LandmarksEngine.cpp.

References iCurrentItemId, CLandmarksEngineBase::iDb, iItemIds, CLandmarksEngineBase::iLmOpWrapper, iNrOfItemsToRead, CLandmarksEngineBase::SetPriorityAndSetActive(), and CLandmarksLmOpWrapper::StartOperation().

Referenced by RunL(), and StartReadingLandmarksL().

00357     {
00358     RArray<TPosLmItemId> subSetOfIds;
00359     CleanupClosePushL(subSetOfIds);
00360 
00361     // Create a subset of the found matches to read
00362     TInt nrOfMatches = iItemIds.Count();
00363     TInt i = 0;
00364     while (i < iNrOfItemsToRead && iCurrentItemId < nrOfMatches)
00365         {
00366         User::LeaveIfError(subSetOfIds.Append(iItemIds[iCurrentItemId]));
00367         iCurrentItemId++;
00368         i++;
00369         }
00370 
00371     // Start reading subset of found matches
00372     iStatus = KRequestPending;
00373     CPosLmOperation* operation = iDb.PreparePartialLandmarksL(subSetOfIds);
00374     iLmOpWrapper->StartOperation(operation, iStatus);
00375     SetPriorityAndSetActive();
00376 
00377     CleanupStack::PopAndDestroy(&subSetOfIds);
00378     }

void CLandmarksEngine::NotifyOperationReadyL (  TOperation  aOperation,
TInt  aErrorCode
)  [private]
 

NotifyOperationReadyL notifies the observer of an asynchronous operation that the operation has completed.

Parameters:
aOperation  the kind of operation that is finished
aErrorCode  the complete code the operation returned

Definition at line 386 of file LandmarksEngine.cpp.

References iActiveOperation, iObserver, and MLandmarksOperationObserver::NotifyOperationProgressL().

Referenced by PopulateItemIdArrayL(), RunError(), and RunL().

00389     {
00390     iActiveOperation = ENoOperation;
00391     iObserver->NotifyOperationProgressL(
00392         aOperation, 
00393         KOperationReady, 
00394         aErrorCode);
00395     }

void CLandmarksEngine::PopulateItemIdArrayL (   )  [private]
 

Fetches the matches after a search operation and populates the data member iItemIds

Definition at line 403 of file LandmarksEngine.cpp.

References iActiveOperation, CLandmarksEngineBase::iDb, iFilterSearch, iItemIds, CLandmarksEngineBase::iSearcher, iSearchResultExists, iSortPref, and NotifyOperationReadyL().

Referenced by RunL().

00404     {
00405     // Fetch itemIterator
00406     CPosLmItemIterator* itemIterator = NULL;
00407     if (iFilterSearch)
00408         {
00409         itemIterator = iSearcher->MatchIteratorL();
00410         iSearchResultExists = ETrue;
00411         }
00412     else
00413         {
00414         itemIterator = iDb.LandmarkIteratorL(iSortPref);
00415         }
00416     CleanupStack::PushL(itemIterator);
00417     itemIterator->Reset();
00418 
00419     // Fetch iItemIds
00420     TUint nrOfItems = itemIterator->NumOfItemsL();
00421     if (nrOfItems > 0)
00422         {
00423         TInt startIndex = 0;
00424         iItemIds.Reset();
00425         itemIterator->GetItemIdsL(iItemIds, startIndex, nrOfItems);
00426         NotifyOperationReadyL(iActiveOperation, KErrNone);
00427         }
00428     else
00429         {
00430         // No matches found
00431         NotifyOperationReadyL(iActiveOperation, KErrNotFound);
00432         }
00433     CleanupStack::PopAndDestroy(itemIterator);
00434     }

void CLandmarksEngineBase::SetPrio (  CActive::TPriority  aPriority  )  [inherited]
 

SetPrio updates the iPriority data member.

Parameters:
aPriority  the priority to set

Definition at line 63 of file LandmarksEngineBase.cpp.

References CLandmarksEngineBase::iPriority.

Referenced by CLandmarksApplicationEngine::NotifyViewActivated().

00064     {
00065     iPriority = aPriority;
00066     }

void CLandmarksEngineBase::SetPriorityAndSetActive (   )  [protected, inherited]
 

SetPriorityAndSetActive updates the priority of this active object if necessary and sets it to active. This method should be used by sub classes rather than CActive::SetActive()

Definition at line 74 of file LandmarksEngineBase.cpp.

References CLandmarksEngineBase::iPriority.

Referenced by CLandmarksCategoriesEngine::ReadSomeCategoriesL(), ReadSomeLandmarksL(), RunL(), StartInitializeDbIfNecessaryL(), CLandmarksCategoriesEngine::StartSearchingCategoriesL(), and StartSearchingLandmarksL().

00075     {
00076     if (iPriority != Priority())
00077         {
00078         CActive::SetPriority(iPriority);
00079         }
00080     SetActive();
00081     }


Member Data Documentation

TBool CLandmarksEngine::iFilterSearch [private]
 

indicates if the current search operation has been carried out with or without search pattern

Definition at line 245 of file LandmarksEngine.h.

Referenced by PopulateItemIdArrayL(), and StartSearchingLandmarksL().


The documentation for this class was generated from the following files:

© Nokia 2009

Back to top