S60 3rd Edition SDK for Symbian OS
Example Applications Guide

CLandmarksCategoriesEngine Class Reference

#include <LandmarksCategoriesEngine.h>

Inheritance diagram for CLandmarksCategoriesEngine:

CLandmarksEngineBase List of all members.

Public Member Functions

 ~CLandmarksCategoriesEngine ()
void AddCategoryL (CPosLandmarkCategory &aCategory)
void UpdateCategoryL (const CPosLandmarkCategory &aCategory)
void DeleteCategoryL (TPosLmItemId aItemId)
CPosLandmarkCategory * CategoryLC (TPosLmItemId aItemId)
void StartSearchingCategoriesL (MLandmarksOperationObserver *aObserver)
void StartSearchingCategoriesL (const TDesC &aSearchPattern, TBool aSearchOnlyInPreviousMatches, MLandmarksOperationObserver *aObserver)
RArray< TPosLmItemId > * FetchSearchResult ()
void StartReadingCategoriesL (TInt aNrOfItemsToReadPerBundle, MLandmarksOperationObserver *aObserver)
CArrayPtr< CPosLandmarkCategory > * FetchCategoriesLC ()
CArrayPtr< CPosLandmarkCategory > * CategoriesL ()

Static Public Member Functions

static CLandmarksCategoriesEngine * NewL (CPosLandmarkDatabase &aDb)

Protected Member Functions

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

Private Member Functions

 CLandmarksCategoriesEngine (CPosLandmarkDatabase &aDb)
void ConstructL ()
void ReadSomeCategoriesL ()
void NotifyOperationReadyL (TOperation aOperation, TInt aErrorCode)
void PopulateItemIdArrayL ()

Private Attributes

CPosLmCategoryManager * iCatManager
 provides access to categories in the default database
RArray< TPosLmItemId > iItemIds
 an array containing the item Ids of the last search
RArray< TPosLmItemId > iSubSetOfIds
MLandmarksOperationObserver * iObserver
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
TBool iFilterSearch

Detailed Description

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

Definition at line 35 of file LandmarksCategoriesEngine.h.

Constructor & Destructor Documentation

CLandmarksCategoriesEngine::~CLandmarksCategoriesEngine (   ) 
 

Destructor.

Definition at line 67 of file LandmarksCategoriesEngine.cpp.

References iCatManager, iItemIds, and iSubSetOfIds.

00068     {
00069     Cancel();
00070     delete iCatManager;
00071     iSubSetOfIds.Close();
00072     iItemIds.Close();
00073     }

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

C++ constructor.

Parameters:
aDb an instance of the default landmark database

Definition at line 33 of file LandmarksCategoriesEngine.cpp.

00035 :   CLandmarksEngineBase(aDb)
00036     {
00037     }

Member Function Documentation

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

Two-phased constructor.

Parameters:
aDb an instance of the default landmark database

Definition at line 55 of file LandmarksCategoriesEngine.cpp.

References CLandmarksCategoriesEngine().

00057     {
00058     CLandmarksCategoriesEngine* self = 
00059         new (ELeave) CLandmarksCategoriesEngine(aDb);
00060     CleanupStack::PushL(self);
00061     self->ConstructL();
00062     CleanupStack::Pop(self);
00063     return self;
00064     }

void CLandmarksCategoriesEngine::AddCategoryL (  CPosLandmarkCategory &  aCategory  ) 
 

AddCategoryL adds a category to the database.

Parameters:
aCategory the landmark to add

Definition at line 81 of file LandmarksCategoriesEngine.cpp.

References iCatManager.

00082     {
00083     iCatManager->AddCategoryL(aCategory);
00084     }

void CLandmarksCategoriesEngine::UpdateCategoryL (  const CPosLandmarkCategory &  aCategory  ) 
 

UpdateCategoryL updates a category in the database.

Parameters:
aCategory the landmark to update

Definition at line 92 of file LandmarksCategoriesEngine.cpp.

References iCatManager.

00093     {
00094     iCatManager->UpdateCategoryL(aCategory);
00095     }

void CLandmarksCategoriesEngine::DeleteCategoryL (  TPosLmItemId  aItemId  ) 
 

DeleteCategoryL deletes a category.

Parameters:
aItemId the itemId identifying the category to be deleted

Definition at line 103 of file LandmarksCategoriesEngine.cpp.

References iCatManager.

00104     {
00105     ExecuteAndDeleteLD(iCatManager->RemoveCategoryL(aItemId));
00106     }

CPosLandmarkCategory * CLandmarksCategoriesEngine::CategoryLC (  TPosLmItemId  aItemId  ) 
 

CategoryLC reads a category in the default landmark database. Ownership of the returned category is transferred to the caller.

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

Definition at line 114 of file LandmarksCategoriesEngine.cpp.

References iCatManager.

00115     {
00116     return iCatManager->ReadCategoryLC(aItemId);
00117     }

void CLandmarksCategoriesEngine::StartSearchingCategoriesL (  MLandmarksOperationObserver *  aObserver  ) 
 

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 FetchCategorySearchResult. All categoiries in the database are returned.

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

Definition at line 125 of file LandmarksCategoriesEngine.cpp.

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

00127     {
00128     // We need to cancel if we are searching/reading categories.
00129     Cancel();
00130 
00131     iObserver = aObserver;
00132     iSearchResultExists = EFalse;
00133     iFilterSearch = EFalse;
00134 
00135     // Complete ourselves and start search for all categories in db in RunL().
00136     iStatus = KRequestPending;
00137     SetPriorityAndSetActive();
00138     iActiveOperation = ECategorySearch;
00139     TRequestStatus* status = &iStatus;
00140     User::RequestComplete(status, KErrNone);
00141     }

void CLandmarksCategoriesEngine::StartSearchingCategoriesL (  const TDesC &  aSearchPattern,
TBool  aSearchOnlyInPreviousMatches,
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 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 149 of file LandmarksCategoriesEngine.cpp.

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

00153     {
00154     // We need to cancel if we are searching/reading categories.
00155     Cancel();
00156 
00157     if (!iSearchResultExists)
00158         {
00159         // There are no previous results or previous search did not complete.
00160         // We cannot use the result from it.
00161         aSearchOnlyInPreviousMatches = EFalse;
00162         }
00163     iSearchResultExists = EFalse;
00164     iFilterSearch = ETrue;
00165 
00166     // Set search criteria
00167     CPosLmCatNameCriteria* criteria = CPosLmCatNameCriteria::NewLC();
00168     criteria->SetSearchPatternL(aSearchPattern);
00169 
00170     // Create search operation
00171     CPosLmOperation* operation = iSearcher->StartCategorySearchL(
00172         *criteria, 
00173         CPosLmCategoryManager::ECategorySortOrderNameAscending, 
00174         aSearchOnlyInPreviousMatches);
00175     CleanupStack::PopAndDestroy(criteria);
00176 
00177     // Start search operation
00178     iObserver = aObserver;
00179     iStatus = KRequestPending;
00180     iLmOpWrapper->StartOperation(operation, iStatus);
00181     SetPriorityAndSetActive();
00182     iActiveOperation = ECategorySearch;
00183     }

RArray< TPosLmItemId > * CLandmarksCategoriesEngine::FetchSearchResult (   ) 
 

FetchSearchResultL 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.

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

Definition at line 191 of file LandmarksCategoriesEngine.cpp.

References iItemIds.

00192     {
00193     return &iItemIds;
00194     }

void CLandmarksCategoriesEngine::StartReadingCategoriesL (  TInt  aNrOfItemsToReadPerBundle,
MLandmarksOperationObserver *  aObserver
) 
 

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

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

Definition at line 202 of file LandmarksCategoriesEngine.cpp.

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

00205     {
00206     // We need to cancel if we are searching/reading landmarks.
00207     Cancel();
00208 
00209     iNrOfItemsToRead = aNrOfItemsToReadPerBundle;
00210     iObserver = aObserver;
00211     iCurrentItemId = 0;
00212 
00213     // Start reading a bundle of categories
00214     ReadSomeCategoriesL();
00215     iActiveOperation = ECategoryRead;
00216     }

CArrayPtr< CPosLandmarkCategory > * CLandmarksCategoriesEngine::FetchCategoriesLC (   ) 
 

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 the returned array is transferred to the caller.

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

Definition at line 224 of file LandmarksCategoriesEngine.cpp.

References iCatManager, and iSubSetOfIds.

00225     {
00226     TInt nrOfItems = iSubSetOfIds.Count();
00227     CArrayPtr<CPosLandmarkCategory>* categories = 
00228         new (ELeave) CArrayPtrFlat<CPosLandmarkCategory>(nrOfItems);
00229     CleanupStack::PushL(categories);
00230 
00231     // Start the actual read of landmarks. This is done synchronously since 
00232     // there is no asynchronous read method as there is for landmarks:
00233     // (Compare TakePreparedPartialLandmarksL()) 
00234     for (TInt i = 0; i < nrOfItems; i++)
00235         {
00236         CPosLandmarkCategory* category = 
00237             iCatManager->ReadCategoryLC(iSubSetOfIds[i]);
00238         categories->AppendL(category);
00239         CleanupStack::Pop(category);
00240         }
00241 
00242     return categories;
00243     }

CArrayPtr< CPosLandmarkCategory > * CLandmarksCategoriesEngine::CategoriesL (   ) 
 

CategoriesL reads all categories in the default database synchronously.Ownership of the returned array is transferred to the caller.

Returns:
an array containing all categories in the database.

Definition at line 251 of file LandmarksCategoriesEngine.cpp.

References iCatManager.

00252     {
00253     const TInt KGranularity = 8;
00254     CArrayPtrFlat<CPosLandmarkCategory>* categories = 
00255         new (ELeave) CArrayPtrFlat<CPosLandmarkCategory>(KGranularity);
00256     CleanupStack::PushL(categories);
00257     
00258     // Get an iterator for all existing categories sorted ascending by name
00259     CPosLmItemIterator* itemIterator = iCatManager->CategoryIteratorL(
00260         CPosLmCategoryManager::ECategorySortOrderNameAscending);
00261     CleanupStack::PushL(itemIterator);
00262 
00263     // Read all categories and add them to an array
00264     TPosLmItemId catId = itemIterator->NextL();
00265     while (catId != KPosLmNullItemId)
00266         {
00267         CPosLandmarkCategory* category = iCatManager->ReadCategoryLC(catId);
00268         categories->AppendL(category);
00269         CleanupStack::Pop(category);
00270 
00271         catId = itemIterator->NextL();
00272         }
00273     CleanupStack::PopAndDestroy(itemIterator);
00274     CleanupStack::Pop(categories);
00275 
00276     return categories;
00277     }

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

Handles an active object’s request completion event.

Implements CLandmarksEngineBase.

Definition at line 285 of file LandmarksCategoriesEngine.cpp.

References iActiveOperation, iCurrentItemId, iItemIds, iObserver, MLandmarksOperationObserver::NotifyOperationProgressL(), NotifyOperationReadyL(), PopulateItemIdArrayL(), and ReadSomeCategoriesL().

00286     {
00287     if (iStatus == KErrNone)
00288         {
00289         if (iActiveOperation == ECategorySearch)
00290             {
00291             // Fetch search result
00292             PopulateItemIdArrayL();
00293             }
00294         else if (iActiveOperation == ECategoryRead)
00295             {
00296             if (iCurrentItemId < iItemIds.Count())
00297                 {
00298                 // There are still found landmarks to read
00299                 iObserver->NotifyOperationProgressL(
00300                     iActiveOperation, KOperationNotReady, KErrNone);
00301                 ReadSomeCategoriesL();
00302                 }
00303             else
00304                 {
00305                 // No more matches to read
00306                 NotifyOperationReadyL(iActiveOperation, KErrNone);
00307                 }
00308             }
00309         }
00310     else
00311         {
00312         // Operation failed. Forward error code
00313         NotifyOperationReadyL(iActiveOperation, iStatus.Int());
00314         }
00315     }

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

Implements cancellation of an outstanding request.

Implements CLandmarksEngineBase.

Definition at line 323 of file LandmarksCategoriesEngine.cpp.

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

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

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

Returns:
KErrNone

Implements CLandmarksEngineBase.

Definition at line 339 of file LandmarksCategoriesEngine.cpp.

References iActiveOperation, and NotifyOperationReadyL().

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

void CLandmarksCategoriesEngine::ConstructL (   )  [private]
 

By default Symbian 2nd phase constructor is private.

Reimplemented from CLandmarksEngineBase.

Definition at line 44 of file LandmarksCategoriesEngine.cpp.

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

00045     {
00046     CLandmarksEngineBase::ConstructL();
00047     iCatManager = CPosLmCategoryManager::NewL(iDb);
00048     }

void CLandmarksCategoriesEngine::ReadSomeCategoriesL (   )  [private]
 

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

Definition at line 354 of file LandmarksCategoriesEngine.cpp.

References iCurrentItemId, iItemIds, iNrOfItemsToRead, iSubSetOfIds, and CLandmarksEngineBase::SetPriorityAndSetActive().

00355     {
00356     // Create a subset of the found matches to read
00357     iSubSetOfIds.Reset();
00358     TInt nrOfMatches = iItemIds.Count();
00359     TInt i = 0;
00360     while (i < iNrOfItemsToRead && iCurrentItemId < nrOfMatches)
00361         {
00362         User::LeaveIfError(
00363             iSubSetOfIds.Append(iItemIds[iCurrentItemId]));
00364         iCurrentItemId++;
00365         i++;
00366         }
00367 
00368     // Simulate start reading found matches. There is no asynchronous search 
00369     // functionality for categories as there is for landmarks, 
00370     // (Compare PreparePartialLandmarksL())
00371     iStatus = KRequestPending;
00372     SetPriorityAndSetActive();
00373     TRequestStatus* status = &iStatus;
00374     User::RequestComplete(status, KErrNone);
00375     }

void CLandmarksCategoriesEngine::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 383 of file LandmarksCategoriesEngine.cpp.

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

00386     {
00387     iActiveOperation = ENoOperation;
00388     iObserver->NotifyOperationProgressL(
00389         aOperation, 
00390         KOperationReady, 
00391         aErrorCode);
00392     }

void CLandmarksCategoriesEngine::PopulateItemIdArrayL (   )  [private]
 

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

Definition at line 400 of file LandmarksCategoriesEngine.cpp.

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

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

Member Data Documentation

RArray<TPosLmItemId> CLandmarksCategoriesEngine::iSubSetOfIds [private]
 

represents a subset of a search result. Used when reading categories

Definition at line 228 of file LandmarksCategoriesEngine.h.

MLandmarksOperationObserver* CLandmarksCategoriesEngine::iObserver [private]
 

the observer to notify the progress of asynchronous operations

Definition at line 232 of file LandmarksCategoriesEngine.h.

TBool CLandmarksCategoriesEngine::iSearchResultExists [private]
 

indicates if there is any previous result to search

Definition at line 245 of file LandmarksCategoriesEngine.h.

TBool CLandmarksCategoriesEngine::iFilterSearch [private]
 

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

Definition at line 249 of file LandmarksCategoriesEngine.h.

© Nokia 2006

Back to top