diff -r 000000000000 -r 667063e416a2 landmarks/locationlandmarks/localsearchprov/inc/EPos_CPosLmLocalSearch.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/landmarks/locationlandmarks/localsearchprov/inc/EPos_CPosLmLocalSearch.h Tue Feb 02 01:06:48 2010 +0200 @@ -0,0 +1,337 @@ +/* +* 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 +#include + +// 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