1 /*

     2 * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:This class is used to start searches for landmarks or landmark categories

    15 *  in a local landmark database.

    16 *

    17 */

    18 

    19 

    20 #ifndef CPOSLMLOCALSEARCH_H

    21 #define CPOSLMLOCALSEARCH_H

    22 

    23 //  INCLUDES

    24 #include <e32base.h>

    25 #include <EPos_CPosLandmarkSearch.h>

    26 

    27 // FORWARD DECLARATIONS

    28 class CPosLmLocalDatabase;

    29 class CPosLmLocalSearchHandler;

    30 class TPosLmLocalSortPref;

    31 class CPosLmLocalSearchOperation;

    32 

    33 // CONSTANT DECLARATIONS

    34 

    35 // CLASS DECLARATION

    36 

    37 /**

    38 *  This class is used to start searches for landmarks or landmark categories

    39 *  in a local landmark database.

    40 *

    41 *  @version $Revision: 1.8 $, $Date: 2005/02/15 13:36:46 $

    42 */

    43 class CPosLmLocalSearch : public CPosLandmarkSearch

    44     {

    45 

    46     public:  // Constructors and destructor

    47 

    48         /**

    49         * Two-phased constructor.

    50         *

    51         * @param aDatabase A landmark database.

    52         * @returns A new instance of this class.

    53         */

    54         static CPosLmLocalSearch* NewL(

    55         /* IN  */       TAny* aDatabase

    56         );

    57 

    58         /**

    59         * Destructor.

    60         */

    61         virtual ~CPosLmLocalSearch();

    62 

    63     public: // New functions

    64 

    65         /**

    66         * This method must be called by the search operation when the operation

    67         * has completed (successfully or due to an error) or if the search

    68         * operation was cancelled.

    69         *

    70         */

    71         void SearchCompleted();

    72 

    73     public: // Functions from base classes

    74 

    75         /**

    76         * From CPosLandmarkSearch.

    77         *

    78         * Start a search for landmarks.

    79         *

    80         * The criteria which defines whether a landmark is a match or not is

    81         * passed as input to this function.

    82         *

    83         * The function returns an operation object which can be run in either

    84         * synchronous or asynchronous mode. If it is run in asynchronous mode

    85         * the client can supervise the progress of the operation.

    86         *

    87         * The client can cancel the search by deleting the

    88         * CPosLmOperation object.

    89         *

    90         * By default, this function starts a new search, but the client can

    91         * specify that only previous matches should be searched. This can be

    92         * used to refine the search when there are many matches. If there are

    93         * no previous matches, this function will leave with error code

    94         * @p KErrArgument.

    95         *

    96         * If a search is already running, this function will leave with error

    97         * code @p KErrInUse.

    98         *

    99         * If the search criteria is not supported, this function will leave

   100         * with error code @p KErrNotSupported.

   101         *

   102         * The client is allowed to delete the criteria object after the search

   103         * is started.

   104         *

   105         * The client takes ownership of the returned operation object.

   106         *

   107         * @param aCriteria The search criteria.

   108         * @param aSearchOnlyPreviousMatches This flag may be used to perform a

   109         *   search within the results of previous search.

   110         * @returns A handle to the search operation.

   111         */

   112         CPosLmOperation* StartLandmarkSearchL(

   113         /* IN  */       const CPosLmSearchCriteria&  aCriteria,

   114         /* IN  */       TBool  aSearchOnlyPreviousMatches = EFalse

   115         );

   116 

   117         /**

   118         * From CPosLandmarkSearch.

   119         *

   120         * Start a search for landmarks.

   121         *

   122         * The criteria which defines whether a landmark is a match or not is

   123         * passed as input to this function.

   124         *

   125         * The function returns an operation object which can be run in either

   126         * synchronous or asynchronous mode. If it is run in asynchronous mode

   127         * the client can supervise the progress of the operation.

   128         *

   129         * The client can cancel the search by deleting the

   130         * CPosLmOperation object.

   131         *

   132         * By default, this function starts a new search, but the client can

   133         * specify that only previous matches should be searched. This can be

   134         * used to refine the search when there are many matches. If there are

   135         * no previous matches, this function will leave with error code

   136         * @p KErrArgument.

   137         *

   138         * If a search is already running, this function will leave with error

   139         * code @p KErrInUse.

   140         *

   141         * If the search criteria is not supported, this function will leave

   142         * with error code @p KErrNotSupported.

   143         *

   144         * The client is allowed to delete the criteria object after the search

   145         * is started.

   146         *

   147         * This overload of the StartLandmarkSearchL function let's the client

   148         * define the sort order for the search matches.

   149         *

   150         * Only sorting by landmark name is supported. If the client tries to

   151         * sort by another attribute, this function will leave with error code

   152         * @p KErrNotSupported.

   153         *

   154         * The client takes ownership of the returned operation object.

   155         *

   156         * @param aCriteria The search criteria.

   157         * @param aSortPref A sort preference object.

   158         * @param aSearchOnlyPreviousMatches This flag may be used to perform a

   159         *   search within the results of previous search.

   160         * @returns A handle to the search operation.

   161         */

   162         CPosLmOperation* StartLandmarkSearchL(

   163         /* IN  */       const CPosLmSearchCriteria&  aCriteria,

   164         /* IN  */       const TPosLmSortPref&  aSortPref,

   165         /* IN  */       TBool  aSearchOnlyPreviousMatches = EFalse

   166         );

   167 

   168         /**

   169         * From CPosLandmarkSearch.

   170         *

   171         * Start a search for landmark categories.

   172         *

   173         * The criteria which defines whether a landmark category is a match or

   174         * not is passed as input to this function.

   175         *

   176         * The function returns an operation object which can be run in either

   177         * synchronous or asynchronous mode. If it is run in asynchronous mode

   178         * the client can supervise the progress of the operation.

   179         *

   180         * The client can cancel the search by deleting the

   181         * CPosLmOperation object.

   182         *

   183         * By default, this function starts a new search, but the client can

   184         * specify that only previous matches should be searched. This can be

   185         * used to refine the search when there are many matches. If there are

   186         * no previous matches, this function will leave with error code

   187         * @p KErrArgument.

   188         *

   189         * If a search is already running, this function will leave with error

   190         * code @p KErrInUse.

   191         *

   192         * If the search criteria is not supported, this function will leave

   193         * with error code @p KErrNotSupported.

   194         *

   195         * The client is allowed to delete the criteria object after the search

   196         * is started.

   197         *

   198         * The client passes a sort preference to specify if and how the

   199         * matching categories should be sorted.

   200         *

   201         * The client takes ownership of the returned operation object.

   202         *

   203         * @param aCriteria The search criteria.

   204         * @param aSortPref Sort preference for the search results.

   205         * @param aSearchOnlyPreviousMatches This flag may be used to perform a

   206         *   search within the results of previous search.

   207         * @returns A handle to the search operation.

   208         */

   209         CPosLmOperation* StartCategorySearchL(

   210         /* IN  */       const CPosLmSearchCriteria&  aCriteria,

   211         /* IN  */       CPosLmCategoryManager::TCategorySortPref  aSortPref,

   212         /* IN  */       TBool  aSearchOnlyPreviousMatches = EFalse

   213         );

   214 

   215         /**

   216         * From CPosLandmarkSearch.

   217         *

   218         * Returns the number of matches so far in the search.

   219         *

   220         * This function can also be called during a search operation.

   221         *

   222         * @return The number of search matches.

   223         */

   224         TUint NumOfMatches() const;

   225 

   226         /**

   227         * From CPosLandmarkSearch.

   228         *

   229         * Creates an iterator object to iterate the matching landmarks or

   230         * landmark categories.

   231         *

   232         * This function can also be called during a search in order to read the

   233         * matches encountered so far. Note, that the iterator will not iterate

   234         * any new matches. If new matches are found a new iterator must be

   235         * created.

   236         *

   237         * If a sort preference was specified when the search was started,

   238         * the landmarks/categories will be sorted when the search is complete

   239         * but the items will not be sorted if this function is called during

   240         * a search.

   241         *

   242         * The client takes ownership of the returned iterator object.

   243         *

   244         * @return A search match iterator.

   245         */

   246         CPosLmItemIterator* MatchIteratorL();

   247 

   248         /**

   249         * From CPosLandmarkSearch.

   250         *

   251         * @param aData The displayable data.

   252         */

   253         void SetDisplayData(

   254         /* IN/OUT */        CPosLmDisplayData& aData

   255         );

   256 

   257         /**

   258         * From CPosLandmarkSearch.

   259         */

   260         void UnsetDisplayData();

   261 

   262     private:

   263 

   264         /**

   265         * C++ default constructor.

   266         */

   267         CPosLmLocalSearch();

   268 

   269         /**

   270         * By default Symbian 2nd phase constructor is private.

   271         *

   272         * @param aDatabase A landmark database.

   273         */

   274         void ConstructL(

   275         /* IN  */       TAny* aDatabase

   276         );

   277 

   278         /**

   279         * Creates the proper CPosLmSearchHandler and stores it in

   280         * iSearchHandler. Then creates the CPosLmLocalSearchOperation and

   281         * stores it in iSearchOperation.

   282         *

   283         * If a search is already running, this function will leave with error

   284         * code @p KErrInUse.

   285         *

   286         * If the search criteria is not supported, this function will leave

   287         * with error code @p KErrNotSupported.

   288         *

   289         * If the search criteria is incorrect, this function will leave

   290         * with error code @p KErrArgument.

   291         *

   292         * The client is allowed to delete the criteria object after the search

   293         * is started.

   294         *

   295         * @param aSearchForLandmarks Search for landmarks if this flag is true,

   296         *   otherwise search for categories.

   297         * @param aCriteria The search criteria.

   298         * @param aSortPref The sort preference for the search.

   299         * @param aSearchOnlyPreviousMatches This flag may be used to perform a

   300         *   search within the results of previous search.

   301         */

   302         void StartSearchL(

   303         /* IN  */       TBool aSearchForLandmarks,

   304         /* IN  */       const CPosLmSearchCriteria& aCriteria,

   305         /* IN  */       const TPosLmLocalSortPref& aSortPref,

   306         /* IN  */       TBool aSearchOnlyPreviousMatches

   307         );

   308 

   309     private:

   310 

   311         // By default, prohibit copy constructor

   312         CPosLmLocalSearch( const CPosLmLocalSearch& );

   313         // Prohibit assigment operator

   314         CPosLmLocalSearch& operator= ( const CPosLmLocalSearch& );

   315 

   316     private:    // Data

   317 

   318         // The local database. Not owned by this class.

   319         CPosLmLocalDatabase*        iDb;

   320 

   321         // Pointer to the current search operation. Not owned by this class.

   322         CPosLmLocalSearchOperation* iSearchOperation;

   323 

   324         // Pointer to a search handler.

   325         // Owned by this class when iOwnsSearchHandler is true.

   326         CPosLmLocalSearchHandler*   iSearchHandler;

   327 

   328         // Tells whether this class owns an instance of CPosLmLocalSearchHandler

   329         TBool                       iOwnsSearchHandler;

   330 

   331         // The displayable data. Not owned by this class.

   332         CPosLmDisplayData*  iDisplayData;

   333     };

   334 

   335 #endif      // CPOSLMLOCALSEARCH_H

   336 

   337 // End of File