1 epos_cposlandmarksearch.h

     1 /*

     2 * Copyright (c) 2005-2006 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CPosLandmarkSearch class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLANDMARKSEARCH_H

    20 #define CPOSLANDMARKSEARCH_H

    21 

    22 #include <e32base.h>

    23 #include <EPos_CPosLandmarkDatabase.h>

    24 #include <EPos_CPosLmCategoryManager.h>

    25 #include <EPos_CPosLmItemIterator.h>

    26 #include <EPos_CPosLmOperation.h>

    27 #include <EPos_TPosLmSortPref.h>

    28 

    29 class CPosLmSearchCriteria;

    30 class CPosLmDisplayData;

    31 

    32 const TInt KPosLmMaxNumOfMatchesUnlimited = -1;

    33 

    34 /**

    35 *  This class is used to perform searches for landmarks or landmark categories

    36 *  in a landmark database.

    37 *

    38 *  To search a landmark database, an instance of this class is created,

    39 *  supplying the database to search. The client creates a criterion object to

    40 *  specify what to search for. There are different criterion classes which all

    41 *  inherit from @ref CPosLmSearchCriteria. For instance, the client can search

    42 *  for landmarks which contain a certain text string by passing a

    43 *  @ref CPosLmTextCriteria.

    44 *

    45 *  Some criterion classes are used for searching for landmarks (e.g.

    46 *  @ref CPosLmCategoryCriteria is used for searching for landmarks which

    47 *  contain a certain category) and some are used

    48 *  to search for landmark categories (e.g. @ref CPosLmCatNameCriteria is used

    49 *  to search for landmark categories by specifying a category name which may

    50 *  contain wild-card characters).

    51 *

    52 *  Searches can be run in incremental mode.

    53 *  @ref StartLandmarkSearchL and @ref StartCategorySearchL both return a

    54 *  @p CPosLmOperation object which is used to execute the search. If it is

    55 *  run incrementally the client can supervise the progress of the operation.

    56 *  If it is sufficient to run the search synchronously, the client only has to

    57 *  call @p CPosLmOperation::ExecuteL. The client can cancel

    58 *  the search by deleting the @p CPosLmOperation object.

    59 *

    60 *  By default, these functions start a new search, but the client can specify

    61 *  that only previous matches should be searched. This can be used to refine

    62 *  the search when there are many matches.

    63 *

    64 *  During the search execution a read-lock is acquired for each database.

    65 *

    66 *  Only one search can be performed at a time by the single instance of

    67 *  the class. If a search is already running, the search function leaves

    68 *  with error code @p KErrInUse.

    69 *

    70 *  After search completion, the client can make a second search and specify

    71 *  that only the matches from the previous search shall be considered.

    72 *

    73 *  The client can also set a limit on how many search matches should be

    74 *  returned (see @ref SetMaxNumOfMatches).

    75 *

    76 *  The client retrieves the matches from the search by requesting an iterator

    77 *  (see @ref MatchIteratorL) or by using display data (see @ref SetDisplayData).

    78 *

    79 *  @p NetworkServices capability is required for remote databases.

    80 *

    81 *  @lib eposlmsearchlib.lib

    82 *  @since S60 3.0

    83 */

    84 class CPosLandmarkSearch : public CBase

    85     {

    86     public:

    87 

    88         /**

    89         * Two-phased constructor.

    90         *

    91         * The client takes ownership of the returned search object.

    92         *

    93         * @param[in] aDatabase The landmark database to search.

    94         * @returns A new instance of this class.

    95         */

    96         IMPORT_C static CPosLandmarkSearch* NewL(

    97             CPosLandmarkDatabase&  aDatabase

    98         );

    99 

   100         /**

   101         * Destructor.

   102         */

   103         IMPORT_C virtual ~CPosLandmarkSearch();

   104 

   105     public:

   106 

   107         /**

   108         * Retrieves the maximum number of search matches limit.

   109         *

   110         * By default the maximum number of matches is unlimited.

   111         *

   112         * @return The maximum number of search matches or

   113         *   @p KPosLmMaxNumOfMatchesUnlimited if unlimited.

   114         */

   115         IMPORT_C TInt MaxNumOfMatches() const;

   116 

   117         /**

   118         * Sets the maximum number of search matches limit.

   119         *

   120         * If the limit is set, the search operation will stop when this limit

   121         * is reached.

   122         *

   123         * By default the maximum number of matches is unlimited.

   124         *

   125         * If a new value for maximum number of matches is set when a search is

   126         * ongoing, it will not affect the current search. The new maximum will

   127         * be utilized in the next search.

   128         *

   129         * @param[in] aMaxNumOfMatches the maximum number of search matches.

   130         *   KPosLmMaxNumOfMatchesUnlimited means that the number of matches is

   131         *   unlimited.

   132         */

   133         IMPORT_C void SetMaxNumOfMatches(

   134             TInt  aMaxNumOfMatches = KPosLmMaxNumOfMatchesUnlimited

   135         );

   136 

   137         /**

   138         * Starts a search for landmarks.

   139         *

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

   141         *

   142         * This function requires @p ReadUserData capability.

   143         *

   144         * @param[in] aCriteria The search criterion.

   145         * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a

   146         *   search within the results of previous search.

   147         * @returns A handle to the search operation.

   148         *

   149         * @leave KErrInUse Search is already running.

   150         * @leave KErrNotSupported search criterion is not supported.

   151         * @leave KErrArgument Search criterion is not valid for landmark searching.

   152         * @leave KErrArgument There are no previous matches and the client specifies that

   153         *   previous matches should be used.

   154         */

   155         virtual CPosLmOperation* StartLandmarkSearchL(

   156             const CPosLmSearchCriteria& aCriteria,

   157             TBool aSearchOnlyPreviousMatches = EFalse

   158         ) = 0;

   159 

   160         /**

   161         * Starts a search for landmarks.

   162         *

   163         * This overload of the @ref StartLandmarkSearchL function lets the

   164         * client define the sort order for the search matches. 

   165         * Only sorting by landmark name is supported.

   166         *

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

   168         *

   169         * This function requires @p ReadUserData capability.

   170         *

   171         * @param[in] aCriteria The search criterion.

   172         * @param[in] aSortPref A sort preference object.

   173         * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a

   174         *   search within the results of previous search.

   175         * @returns A handle to the search operation.

   176         *

   177         * @leave KErrInUse Search is already running.

   178         * @leave KErrArgument Search criterion is not valid for landmark searching.

   179         * @leave KErrArgument There are no previous matches and the client specifies that

   180         *   previous matches should be used.

   181         * @leave KErrNotSupported Search criterion is not supported.

   182         * @leave KErrNotSupported Client tries to sort by other attribute than name.

   183         */

   184         virtual CPosLmOperation* StartLandmarkSearchL(

   185             const CPosLmSearchCriteria& aCriteria,

   186             const TPosLmSortPref& aSortPref,

   187             TBool  aSearchOnlyPreviousMatches = EFalse

   188         ) = 0;

   189 

   190         /**

   191         * Starts a search for landmark categories.

   192         *

   193         * The criterion which defines whether a landmark category is a match or

   194         * not is passed as input to this function.

   195         *

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

   197         *

   198         * This function requires @p ReadUserData capability.

   199         *

   200         * @param[in] aCriteria The search criterion.

   201         * @param[in] aSortPref Sort preference for the search results.

   202         * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a

   203         *   search within the results of previous search.

   204         * @returns A handle to the search operation.

   205         *

   206         * @leave KErrInUse Search is already running.

   207         * @leave KErrArgument Search criterion is not valid for category searching.

   208         * @leave KErrNotSupported Search criterion is not supported.

   209         */

   210         virtual CPosLmOperation* StartCategorySearchL(

   211             const CPosLmSearchCriteria& aCriteria,

   212             CPosLmCategoryManager::TCategorySortPref aSortPref,

   213             TBool aSearchOnlyPreviousMatches = EFalse

   214         ) = 0;

   215 

   216         /**

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

   218         *

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

   220         *

   221         * @return The number of search matches.

   222         */

   223         virtual TUint NumOfMatches() const = 0;

   224 

   225         /**

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

   227         * landmark categories.

   228         *

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

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

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

   232         * created.

   233         *

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

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

   236         * but the items are not necessarily sorted if this function is called

   237         * during a search.

   238         *

   239         * Note: If the client has set display data and resets the display data

   240         * during a search, the sort order in the iterator might be incorrect.

   241         *

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

   243         *

   244         * Note that the iterator iterates matches in @ref CPosLandmarkSearch.

   245         * It cannot be used after the search object has been deleted. Make sure

   246         * to delete the iterator first.

   247         *

   248         * @return A search match iterator.

   249         */

   250         virtual CPosLmItemIterator* MatchIteratorL() = 0;

   251 

   252         /**

   253         * Display data can be used as an alternative way to get result

   254         * from a database search. Landmarks or categories are added to the

   255         * display data collection during a search depending on the search type.

   256         *

   257         * This function may replace the combination of using

   258         * @ref MatchIteratorL and reading landmark or category data.

   259         * Result data is read already during the search and no duplicate

   260         * access to database is needed.

   261         *

   262         * The display data object will be reset each time a new search is

   263         * started. No items during the search are removed from the

   264         * collection. New found matches can be added every time next

   265         * search step is completed, see @ref CPosLmDisplayData::NewItemIndex.

   266         *

   267         * Note: The database index of displayable data items in

   268         * @ref CPosLmDisplayData will be set to 0 as it has no meaning in a

   269         * single database search.

   270         *

   271         * The client owns the display data object. If the client deletes it

   272         * during a search, this may lead to unexpected errors. The client must

   273         * call @ref UnsetDisplayData before it deletes the display data object.

   274         *

   275         * Note: If the client resets the display data during a search, the sort

   276         * order in the iterator might become incorrect.

   277         *

   278         * @param[in,out] aData The displayable data.

   279         *

   280         * @panic "Landmarks Client"-EPosSearchOperationInUse 

   281         *   The client set display data during an ongoing search.

   282         */

   283         virtual void SetDisplayData( CPosLmDisplayData& aData ) = 0;

   284 

   285         /**

   286         * Unsets display data. No further data will be added to the display

   287         * data that was set with @ref SetDisplayData.

   288         *

   289         * @panic "Landmarks Client"-EPosSearchOperationInUse 

   290         *   The client unset display data during an ongoing search.

   291         */

   292         virtual void UnsetDisplayData() = 0;

   293 

   294     protected:

   295 

   296         // C++ constructor.

   297         IMPORT_C CPosLandmarkSearch();

   298 

   299     private:

   300 

   301         // Prohibit copy constructor

   302         CPosLandmarkSearch( const CPosLandmarkSearch& );

   303         // Prohibit assigment operator

   304         CPosLandmarkSearch& operator= ( const CPosLandmarkSearch& );

   305 

   306     private:

   307 

   308         TUid iDtorIdKey;

   309         TInt iMaxNumOfMatches;

   310     };

   311 

   312 #endif      // CPOSLANDMARKSEARCH_H

   313 

   314