1.1 --- a/epoc32/include/mw/epos_cposlandmarksearch.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/epos_cposlandmarksearch.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,314 @@
1.4 -epos_cposlandmarksearch.h
1.5 +/*
1.6 +* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: CPosLandmarkSearch class
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef CPOSLANDMARKSEARCH_H
1.24 +#define CPOSLANDMARKSEARCH_H
1.25 +
1.26 +#include <e32base.h>
1.27 +#include <EPos_CPosLandmarkDatabase.h>
1.28 +#include <EPos_CPosLmCategoryManager.h>
1.29 +#include <EPos_CPosLmItemIterator.h>
1.30 +#include <EPos_CPosLmOperation.h>
1.31 +#include <EPos_TPosLmSortPref.h>
1.32 +
1.33 +class CPosLmSearchCriteria;
1.34 +class CPosLmDisplayData;
1.35 +
1.36 +const TInt KPosLmMaxNumOfMatchesUnlimited = -1;
1.37 +
1.38 +/**
1.39 +* This class is used to perform searches for landmarks or landmark categories
1.40 +* in a landmark database.
1.41 +*
1.42 +* To search a landmark database, an instance of this class is created,
1.43 +* supplying the database to search. The client creates a criterion object to
1.44 +* specify what to search for. There are different criterion classes which all
1.45 +* inherit from @ref CPosLmSearchCriteria. For instance, the client can search
1.46 +* for landmarks which contain a certain text string by passing a
1.47 +* @ref CPosLmTextCriteria.
1.48 +*
1.49 +* Some criterion classes are used for searching for landmarks (e.g.
1.50 +* @ref CPosLmCategoryCriteria is used for searching for landmarks which
1.51 +* contain a certain category) and some are used
1.52 +* to search for landmark categories (e.g. @ref CPosLmCatNameCriteria is used
1.53 +* to search for landmark categories by specifying a category name which may
1.54 +* contain wild-card characters).
1.55 +*
1.56 +* Searches can be run in incremental mode.
1.57 +* @ref StartLandmarkSearchL and @ref StartCategorySearchL both return a
1.58 +* @p CPosLmOperation object which is used to execute the search. If it is
1.59 +* run incrementally the client can supervise the progress of the operation.
1.60 +* If it is sufficient to run the search synchronously, the client only has to
1.61 +* call @p CPosLmOperation::ExecuteL. The client can cancel
1.62 +* the search by deleting the @p CPosLmOperation object.
1.63 +*
1.64 +* By default, these functions start a new search, but the client can specify
1.65 +* that only previous matches should be searched. This can be used to refine
1.66 +* the search when there are many matches.
1.67 +*
1.68 +* During the search execution a read-lock is acquired for each database.
1.69 +*
1.70 +* Only one search can be performed at a time by the single instance of
1.71 +* the class. If a search is already running, the search function leaves
1.72 +* with error code @p KErrInUse.
1.73 +*
1.74 +* After search completion, the client can make a second search and specify
1.75 +* that only the matches from the previous search shall be considered.
1.76 +*
1.77 +* The client can also set a limit on how many search matches should be
1.78 +* returned (see @ref SetMaxNumOfMatches).
1.79 +*
1.80 +* The client retrieves the matches from the search by requesting an iterator
1.81 +* (see @ref MatchIteratorL) or by using display data (see @ref SetDisplayData).
1.82 +*
1.83 +* @p NetworkServices capability is required for remote databases.
1.84 +*
1.85 +* @lib eposlmsearchlib.lib
1.86 +* @since S60 3.0
1.87 +*/
1.88 +class CPosLandmarkSearch : public CBase
1.89 + {
1.90 + public:
1.91 +
1.92 + /**
1.93 + * Two-phased constructor.
1.94 + *
1.95 + * The client takes ownership of the returned search object.
1.96 + *
1.97 + * @param[in] aDatabase The landmark database to search.
1.98 + * @returns A new instance of this class.
1.99 + */
1.100 + IMPORT_C static CPosLandmarkSearch* NewL(
1.101 + CPosLandmarkDatabase& aDatabase
1.102 + );
1.103 +
1.104 + /**
1.105 + * Destructor.
1.106 + */
1.107 + IMPORT_C virtual ~CPosLandmarkSearch();
1.108 +
1.109 + public:
1.110 +
1.111 + /**
1.112 + * Retrieves the maximum number of search matches limit.
1.113 + *
1.114 + * By default the maximum number of matches is unlimited.
1.115 + *
1.116 + * @return The maximum number of search matches or
1.117 + * @p KPosLmMaxNumOfMatchesUnlimited if unlimited.
1.118 + */
1.119 + IMPORT_C TInt MaxNumOfMatches() const;
1.120 +
1.121 + /**
1.122 + * Sets the maximum number of search matches limit.
1.123 + *
1.124 + * If the limit is set, the search operation will stop when this limit
1.125 + * is reached.
1.126 + *
1.127 + * By default the maximum number of matches is unlimited.
1.128 + *
1.129 + * If a new value for maximum number of matches is set when a search is
1.130 + * ongoing, it will not affect the current search. The new maximum will
1.131 + * be utilized in the next search.
1.132 + *
1.133 + * @param[in] aMaxNumOfMatches the maximum number of search matches.
1.134 + * KPosLmMaxNumOfMatchesUnlimited means that the number of matches is
1.135 + * unlimited.
1.136 + */
1.137 + IMPORT_C void SetMaxNumOfMatches(
1.138 + TInt aMaxNumOfMatches = KPosLmMaxNumOfMatchesUnlimited
1.139 + );
1.140 +
1.141 + /**
1.142 + * Starts a search for landmarks.
1.143 + *
1.144 + * The client takes ownership of the returned operation object.
1.145 + *
1.146 + * This function requires @p ReadUserData capability.
1.147 + *
1.148 + * @param[in] aCriteria The search criterion.
1.149 + * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a
1.150 + * search within the results of previous search.
1.151 + * @returns A handle to the search operation.
1.152 + *
1.153 + * @leave KErrInUse Search is already running.
1.154 + * @leave KErrNotSupported search criterion is not supported.
1.155 + * @leave KErrArgument Search criterion is not valid for landmark searching.
1.156 + * @leave KErrArgument There are no previous matches and the client specifies that
1.157 + * previous matches should be used.
1.158 + */
1.159 + virtual CPosLmOperation* StartLandmarkSearchL(
1.160 + const CPosLmSearchCriteria& aCriteria,
1.161 + TBool aSearchOnlyPreviousMatches = EFalse
1.162 + ) = 0;
1.163 +
1.164 + /**
1.165 + * Starts a search for landmarks.
1.166 + *
1.167 + * This overload of the @ref StartLandmarkSearchL function lets the
1.168 + * client define the sort order for the search matches.
1.169 + * Only sorting by landmark name is supported.
1.170 + *
1.171 + * The client takes ownership of the returned operation object.
1.172 + *
1.173 + * This function requires @p ReadUserData capability.
1.174 + *
1.175 + * @param[in] aCriteria The search criterion.
1.176 + * @param[in] aSortPref A sort preference object.
1.177 + * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a
1.178 + * search within the results of previous search.
1.179 + * @returns A handle to the search operation.
1.180 + *
1.181 + * @leave KErrInUse Search is already running.
1.182 + * @leave KErrArgument Search criterion is not valid for landmark searching.
1.183 + * @leave KErrArgument There are no previous matches and the client specifies that
1.184 + * previous matches should be used.
1.185 + * @leave KErrNotSupported Search criterion is not supported.
1.186 + * @leave KErrNotSupported Client tries to sort by other attribute than name.
1.187 + */
1.188 + virtual CPosLmOperation* StartLandmarkSearchL(
1.189 + const CPosLmSearchCriteria& aCriteria,
1.190 + const TPosLmSortPref& aSortPref,
1.191 + TBool aSearchOnlyPreviousMatches = EFalse
1.192 + ) = 0;
1.193 +
1.194 + /**
1.195 + * Starts a search for landmark categories.
1.196 + *
1.197 + * The criterion which defines whether a landmark category is a match or
1.198 + * not is passed as input to this function.
1.199 + *
1.200 + * The client takes ownership of the returned operation object.
1.201 + *
1.202 + * This function requires @p ReadUserData capability.
1.203 + *
1.204 + * @param[in] aCriteria The search criterion.
1.205 + * @param[in] aSortPref Sort preference for the search results.
1.206 + * @param[in] aSearchOnlyPreviousMatches This flag may be used to perform a
1.207 + * search within the results of previous search.
1.208 + * @returns A handle to the search operation.
1.209 + *
1.210 + * @leave KErrInUse Search is already running.
1.211 + * @leave KErrArgument Search criterion is not valid for category searching.
1.212 + * @leave KErrNotSupported Search criterion is not supported.
1.213 + */
1.214 + virtual CPosLmOperation* StartCategorySearchL(
1.215 + const CPosLmSearchCriteria& aCriteria,
1.216 + CPosLmCategoryManager::TCategorySortPref aSortPref,
1.217 + TBool aSearchOnlyPreviousMatches = EFalse
1.218 + ) = 0;
1.219 +
1.220 + /**
1.221 + * Returns the number of matches so far in the search.
1.222 + *
1.223 + * This function can also be called during a search operation.
1.224 + *
1.225 + * @return The number of search matches.
1.226 + */
1.227 + virtual TUint NumOfMatches() const = 0;
1.228 +
1.229 + /**
1.230 + * Creates an iterator object to iterate the matching landmarks or
1.231 + * landmark categories.
1.232 + *
1.233 + * This function can also be called during a search in order to read the
1.234 + * matches encountered so far. Note that the iterator will not iterate
1.235 + * any new matches. If new matches are found, a new iterator must be
1.236 + * created.
1.237 + *
1.238 + * If a sort preference was specified when the search was started,
1.239 + * the landmarks/categories will be sorted when the search is complete
1.240 + * but the items are not necessarily sorted if this function is called
1.241 + * during a search.
1.242 + *
1.243 + * Note: If the client has set display data and resets the display data
1.244 + * during a search, the sort order in the iterator might be incorrect.
1.245 + *
1.246 + * The client takes ownership of the returned iterator object.
1.247 + *
1.248 + * Note that the iterator iterates matches in @ref CPosLandmarkSearch.
1.249 + * It cannot be used after the search object has been deleted. Make sure
1.250 + * to delete the iterator first.
1.251 + *
1.252 + * @return A search match iterator.
1.253 + */
1.254 + virtual CPosLmItemIterator* MatchIteratorL() = 0;
1.255 +
1.256 + /**
1.257 + * Display data can be used as an alternative way to get result
1.258 + * from a database search. Landmarks or categories are added to the
1.259 + * display data collection during a search depending on the search type.
1.260 + *
1.261 + * This function may replace the combination of using
1.262 + * @ref MatchIteratorL and reading landmark or category data.
1.263 + * Result data is read already during the search and no duplicate
1.264 + * access to database is needed.
1.265 + *
1.266 + * The display data object will be reset each time a new search is
1.267 + * started. No items during the search are removed from the
1.268 + * collection. New found matches can be added every time next
1.269 + * search step is completed, see @ref CPosLmDisplayData::NewItemIndex.
1.270 + *
1.271 + * Note: The database index of displayable data items in
1.272 + * @ref CPosLmDisplayData will be set to 0 as it has no meaning in a
1.273 + * single database search.
1.274 + *
1.275 + * The client owns the display data object. If the client deletes it
1.276 + * during a search, this may lead to unexpected errors. The client must
1.277 + * call @ref UnsetDisplayData before it deletes the display data object.
1.278 + *
1.279 + * Note: If the client resets the display data during a search, the sort
1.280 + * order in the iterator might become incorrect.
1.281 + *
1.282 + * @param[in,out] aData The displayable data.
1.283 + *
1.284 + * @panic "Landmarks Client"-EPosSearchOperationInUse
1.285 + * The client set display data during an ongoing search.
1.286 + */
1.287 + virtual void SetDisplayData( CPosLmDisplayData& aData ) = 0;
1.288 +
1.289 + /**
1.290 + * Unsets display data. No further data will be added to the display
1.291 + * data that was set with @ref SetDisplayData.
1.292 + *
1.293 + * @panic "Landmarks Client"-EPosSearchOperationInUse
1.294 + * The client unset display data during an ongoing search.
1.295 + */
1.296 + virtual void UnsetDisplayData() = 0;
1.297 +
1.298 + protected:
1.299 +
1.300 + // C++ constructor.
1.301 + IMPORT_C CPosLandmarkSearch();
1.302 +
1.303 + private:
1.304 +
1.305 + // Prohibit copy constructor
1.306 + CPosLandmarkSearch( const CPosLandmarkSearch& );
1.307 + // Prohibit assigment operator
1.308 + CPosLandmarkSearch& operator= ( const CPosLandmarkSearch& );
1.309 +
1.310 + private:
1.311 +
1.312 + TUid iDtorIdKey;
1.313 + TInt iMaxNumOfMatches;
1.314 + };
1.315 +
1.316 +#endif // CPOSLANDMARKSEARCH_H
1.317 +
1.318 +