S60 3rd Edition SDK for Symbian OS
Example Applications Guide

CLandmarksEngine Class Reference

#include <LandmarksEngine.h>

Inheritance diagram for CLandmarksEngine:

CLandmarksEngineBase List of all members.

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 ()

Static Public Member Functions

static CLandmarksEngine * NewL (CPosLandmarkDatabase &aDb)

Protected Member Functions

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

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

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.

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.

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().

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().

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.

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.

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.

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().

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.

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().

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().

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().

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().

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().

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     }

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.

© Nokia 2006

Back to top