/*
* Copyright (c) 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:This class is used to start searches for landmarks or landmark categories
* in a local landmark database.
*
*/
#ifndef CPOSLMLOCALSEARCH_H
#define CPOSLMLOCALSEARCH_H
// INCLUDES
#include <e32base.h>
#include <EPos_CPosLandmarkSearch.h>
// FORWARD DECLARATIONS
class CPosLmLocalDatabase;
class CPosLmLocalSearchHandler;
class TPosLmLocalSortPref;
class CPosLmLocalSearchOperation;
// CONSTANT DECLARATIONS
// CLASS DECLARATION
/**
* This class is used to start searches for landmarks or landmark categories
* in a local landmark database.
*
* @version $Revision: 1.8 $, $Date: 2005/02/15 13:36:46 $
*/
class CPosLmLocalSearch : public CPosLandmarkSearch
{
public: // Constructors and destructor
/**
* Two-phased constructor.
*
* @param aDatabase A landmark database.
* @returns A new instance of this class.
*/
static CPosLmLocalSearch* NewL(
/* IN */ TAny* aDatabase
);
/**
* Destructor.
*/
virtual ~CPosLmLocalSearch();
public: // New functions
/**
* This method must be called by the search operation when the operation
* has completed (successfully or due to an error) or if the search
* operation was cancelled.
*
*/
void SearchCompleted();
public: // Functions from base classes
/**
* From CPosLandmarkSearch.
*
* Start a search for landmarks.
*
* The criteria which defines whether a landmark is a match or not is
* passed as input to this function.
*
* The function returns an operation object which can be run in either
* synchronous or asynchronous mode. If it is run in asynchronous mode
* the client can supervise the progress of the operation.
*
* The client can cancel the search by deleting the
* CPosLmOperation object.
*
* By default, this function starts a new search, but the client can
* specify that only previous matches should be searched. This can be
* used to refine the search when there are many matches. If there are
* no previous matches, this function will leave with error code
* @p KErrArgument.
*
* If a search is already running, this function will leave with error
* code @p KErrInUse.
*
* If the search criteria is not supported, this function will leave
* with error code @p KErrNotSupported.
*
* The client is allowed to delete the criteria object after the search
* is started.
*
* The client takes ownership of the returned operation object.
*
* @param aCriteria The search criteria.
* @param aSearchOnlyPreviousMatches This flag may be used to perform a
* search within the results of previous search.
* @returns A handle to the search operation.
*/
CPosLmOperation* StartLandmarkSearchL(
/* IN */ const CPosLmSearchCriteria& aCriteria,
/* IN */ TBool aSearchOnlyPreviousMatches = EFalse
);
/**
* From CPosLandmarkSearch.
*
* Start a search for landmarks.
*
* The criteria which defines whether a landmark is a match or not is
* passed as input to this function.
*
* The function returns an operation object which can be run in either
* synchronous or asynchronous mode. If it is run in asynchronous mode
* the client can supervise the progress of the operation.
*
* The client can cancel the search by deleting the
* CPosLmOperation object.
*
* By default, this function starts a new search, but the client can
* specify that only previous matches should be searched. This can be
* used to refine the search when there are many matches. If there are
* no previous matches, this function will leave with error code
* @p KErrArgument.
*
* If a search is already running, this function will leave with error
* code @p KErrInUse.
*
* If the search criteria is not supported, this function will leave
* with error code @p KErrNotSupported.
*
* The client is allowed to delete the criteria object after the search
* is started.
*
* This overload of the StartLandmarkSearchL function let's the client
* define the sort order for the search matches.
*
* Only sorting by landmark name is supported. If the client tries to
* sort by another attribute, this function will leave with error code
* @p KErrNotSupported.
*
* The client takes ownership of the returned operation object.
*
* @param aCriteria The search criteria.
* @param aSortPref A sort preference object.
* @param aSearchOnlyPreviousMatches This flag may be used to perform a
* search within the results of previous search.
* @returns A handle to the search operation.
*/
CPosLmOperation* StartLandmarkSearchL(
/* IN */ const CPosLmSearchCriteria& aCriteria,
/* IN */ const TPosLmSortPref& aSortPref,
/* IN */ TBool aSearchOnlyPreviousMatches = EFalse
);
/**
* From CPosLandmarkSearch.
*
* Start a search for landmark categories.
*
* The criteria which defines whether a landmark category is a match or
* not is passed as input to this function.
*
* The function returns an operation object which can be run in either
* synchronous or asynchronous mode. If it is run in asynchronous mode
* the client can supervise the progress of the operation.
*
* The client can cancel the search by deleting the
* CPosLmOperation object.
*
* By default, this function starts a new search, but the client can
* specify that only previous matches should be searched. This can be
* used to refine the search when there are many matches. If there are
* no previous matches, this function will leave with error code
* @p KErrArgument.
*
* If a search is already running, this function will leave with error
* code @p KErrInUse.
*
* If the search criteria is not supported, this function will leave
* with error code @p KErrNotSupported.
*
* The client is allowed to delete the criteria object after the search
* is started.
*
* The client passes a sort preference to specify if and how the
* matching categories should be sorted.
*
* The client takes ownership of the returned operation object.
*
* @param aCriteria The search criteria.
* @param aSortPref Sort preference for the search results.
* @param aSearchOnlyPreviousMatches This flag may be used to perform a
* search within the results of previous search.
* @returns A handle to the search operation.
*/
CPosLmOperation* StartCategorySearchL(
/* IN */ const CPosLmSearchCriteria& aCriteria,
/* IN */ CPosLmCategoryManager::TCategorySortPref aSortPref,
/* IN */ TBool aSearchOnlyPreviousMatches = EFalse
);
/**
* From CPosLandmarkSearch.
*
* Returns the number of matches so far in the search.
*
* This function can also be called during a search operation.
*
* @return The number of search matches.
*/
TUint NumOfMatches() const;
/**
* From CPosLandmarkSearch.
*
* Creates an iterator object to iterate the matching landmarks or
* landmark categories.
*
* This function can also be called during a search in order to read the
* matches encountered so far. Note, that the iterator will not iterate
* any new matches. If new matches are found a new iterator must be
* created.
*
* If a sort preference was specified when the search was started,
* the landmarks/categories will be sorted when the search is complete
* but the items will not be sorted if this function is called during
* a search.
*
* The client takes ownership of the returned iterator object.
*
* @return A search match iterator.
*/
CPosLmItemIterator* MatchIteratorL();
/**
* From CPosLandmarkSearch.
*
* @param aData The displayable data.
*/
void SetDisplayData(
/* IN/OUT */ CPosLmDisplayData& aData
);
/**
* From CPosLandmarkSearch.
*/
void UnsetDisplayData();
private:
/**
* C++ default constructor.
*/
CPosLmLocalSearch();
/**
* By default Symbian 2nd phase constructor is private.
*
* @param aDatabase A landmark database.
*/
void ConstructL(
/* IN */ TAny* aDatabase
);
/**
* Creates the proper CPosLmSearchHandler and stores it in
* iSearchHandler. Then creates the CPosLmLocalSearchOperation and
* stores it in iSearchOperation.
*
* If a search is already running, this function will leave with error
* code @p KErrInUse.
*
* If the search criteria is not supported, this function will leave
* with error code @p KErrNotSupported.
*
* If the search criteria is incorrect, this function will leave
* with error code @p KErrArgument.
*
* The client is allowed to delete the criteria object after the search
* is started.
*
* @param aSearchForLandmarks Search for landmarks if this flag is true,
* otherwise search for categories.
* @param aCriteria The search criteria.
* @param aSortPref The sort preference for the search.
* @param aSearchOnlyPreviousMatches This flag may be used to perform a
* search within the results of previous search.
*/
void StartSearchL(
/* IN */ TBool aSearchForLandmarks,
/* IN */ const CPosLmSearchCriteria& aCriteria,
/* IN */ const TPosLmLocalSortPref& aSortPref,
/* IN */ TBool aSearchOnlyPreviousMatches
);
private:
// By default, prohibit copy constructor
CPosLmLocalSearch( const CPosLmLocalSearch& );
// Prohibit assigment operator
CPosLmLocalSearch& operator= ( const CPosLmLocalSearch& );
private: // Data
// The local database. Not owned by this class.
CPosLmLocalDatabase* iDb;
// Pointer to the current search operation. Not owned by this class.
CPosLmLocalSearchOperation* iSearchOperation;
// Pointer to a search handler.
// Owned by this class when iOwnsSearchHandler is true.
CPosLmLocalSearchHandler* iSearchHandler;
// Tells whether this class owns an instance of CPosLmLocalSearchHandler
TBool iOwnsSearchHandler;
// The displayable data. Not owned by this class.
CPosLmDisplayData* iDisplayData;
};
#endif // CPOSLMLOCALSEARCH_H
// End of File