1.1 --- a/epoc32/include/mw/epos_cposlmcategorymanager.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/epos_cposlmcategorymanager.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,479 @@
1.4 -epos_cposlmcategorymanager.h
1.5 +/*
1.6 +* Copyright (c) 2005-2007 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: CPosLmCategoryManager class
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef CPOSLMCATEGORYMANAGER_H
1.24 +#define CPOSLMCATEGORYMANAGER_H
1.25 +
1.26 +#include <e32base.h>
1.27 +#include "epos_cposlandmarkdatabase.h"
1.28 +#include "epos_cposlandmarkcategory.h"
1.29 +#include "epos_cposlmitemiterator.h"
1.30 +#include "epos_cposlmoperation.h"
1.31 +
1.32 +/**
1.33 +* Category management for a landmark database.
1.34 +*
1.35 +* A landmark database can contain a number of categories which can be
1.36 +* assigned to the landmarks in the database. A landmark can be associated
1.37 +* with multiple categories, e.g. a landmark can be a "Restaurant" and a "Pub".
1.38 +* Categories also enable filtered searches, e.g. a client could search for
1.39 +* nearby restaurants.
1.40 +*
1.41 +* This class contains functions for managing landmark categories. This includes
1.42 +* reading, listing, creating and updating landmark categories.
1.43 +*
1.44 +* @p NetworkServices capability is required for remote databases.
1.45 +*
1.46 +* @lib eposlandmarks.lib
1.47 +* @since S60 3.0
1.48 +*/
1.49 +class CPosLmCategoryManager : public CBase
1.50 + {
1.51 + public:
1.52 +
1.53 + /**
1.54 + * Specifies the sort preference for landmark categories.
1.55 + */
1.56 + enum TCategorySortPref
1.57 + {
1.58 + ECategorySortOrderNone = 0 /**<
1.59 + Categories not sorted */,
1.60 + ECategorySortOrderNameAscending /**<
1.61 + Sorted ascending by category name. */,
1.62 + ECategorySortOrderNameDescending /**<
1.63 + Sorted descending by category name. */
1.64 + };
1.65 +
1.66 + public:
1.67 +
1.68 + /**
1.69 + * Two-phased constructor.
1.70 + *
1.71 + * The client takes ownership of the category manager.
1.72 + *
1.73 + * @param[in] aLandmarkDatabase The landmark database to manage categories in.
1.74 + * @returns A new instance of this class.
1.75 + */
1.76 + IMPORT_C static CPosLmCategoryManager* NewL(
1.77 + CPosLandmarkDatabase& aLandmarkDatabase
1.78 + );
1.79 +
1.80 + /**
1.81 + * Destructor.
1.82 + */
1.83 + IMPORT_C virtual ~CPosLmCategoryManager();
1.84 +
1.85 + public:
1.86 +
1.87 + /**
1.88 + * Reads a landmark category from the database.
1.89 + *
1.90 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.91 + *
1.92 + * The client takes ownership of the returned category object.
1.93 + *
1.94 + * This function requires @p ReadUserData capability.
1.95 + *
1.96 + * @param aCategoryId The ID of the landmark category to read.
1.97 + * @returns The requested landmark category. The category object is put
1.98 + * on the cleanup stack.
1.99 + *
1.100 + * @leave KErrNotFound The landmark category does not exist in the database.
1.101 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.102 + */
1.103 + virtual CPosLandmarkCategory* ReadCategoryLC( TPosLmItemId aCategoryId ) = 0;
1.104 +
1.105 + /**
1.106 + * Returns an object for iterating the landmark categories in the
1.107 + * database.
1.108 + *
1.109 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.110 + *
1.111 + * The iterator object is reset, so that the first
1.112 + * @ref CPosLmItemIterator::NextL call will return the first landmark
1.113 + * category.
1.114 + *
1.115 + * The client takes ownership of the returned iterator object.
1.116 + *
1.117 + * This function requires @p ReadUserData capability.
1.118 + *
1.119 + * @param[in] aSortPref How to sort the categories. Default is no sorting.
1.120 + * @return The landmark iterator.
1.121 + *
1.122 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.123 + *
1.124 + * @panic "Landmarks Client"-EPosInvalidEnumValue
1.125 + * Client specified invalid sort preference.
1.126 + */
1.127 + virtual CPosLmItemIterator* CategoryIteratorL(
1.128 + TCategorySortPref aSortPref = ECategorySortOrderNone
1.129 + ) = 0;
1.130 +
1.131 + /**
1.132 + * Returns an object for iterating referenced landmark categories in
1.133 + * the database.
1.134 + *
1.135 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.136 + *
1.137 + * A category is referenced if there are landmarks in the database which
1.138 + * contains this category.
1.139 + *
1.140 + * The iterator object is reset, so that the first
1.141 + * @ref CPosLmItemIterator::NextL call will return the first landmark
1.142 + * category.
1.143 + *
1.144 + * The client takes ownership of the returned iterator object.
1.145 + *
1.146 + * This function requires @p ReadUserData capability.
1.147 + *
1.148 + * @param[in] aSortPref How to sort the categories. Default is no sorting.
1.149 + * @return The landmark iterator.
1.150 + *
1.151 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.152 + *
1.153 + * @panic "Landmarks Client"-EPosInvalidEnumValue
1.154 + * Client specified invalid sort preference.
1.155 + */
1.156 + virtual CPosLmItemIterator* ReferencedCategoryIteratorL(
1.157 + TCategorySortPref aSortPref = ECategorySortOrderNone
1.158 + ) = 0;
1.159 +
1.160 + /**
1.161 + * Adds a landmark category to the database and returns its ID.
1.162 + *
1.163 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.164 + *
1.165 + * Note: Clients are not allowed to create global categories.
1.166 + *
1.167 + * This function requires @p ReadUserData and @p WriteUserData
1.168 + * capabilities.
1.169 + *
1.170 + * @post Category is added to the database and category object
1.171 + * has database item set (CPosLandmarkCategory::CategoryId()).
1.172 + *
1.173 + * @param[in,out] aCategory The landmark category to add.
1.174 + * @return The ID of the new category.
1.175 + *
1.176 + * @leave KErrArgument 1) Input category does not have a name set or
1.177 + * 2) if a global category is set in the category object.
1.178 + * @leave KErrAlreadyExists A category with the same name
1.179 + * already exists in the database.
1.180 + * @leave KErrAccessDenied The database is read-only.
1.181 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.182 + */
1.183 + virtual TPosLmItemId AddCategoryL(
1.184 + CPosLandmarkCategory& aCategory
1.185 + ) = 0;
1.186 +
1.187 + /**
1.188 + * Updates a landmark category in the database.
1.189 + *
1.190 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.191 + *
1.192 + * Note: Clients are not allowed to change the global category identifier in
1.193 + * the category object.
1.194 + *
1.195 + * This function requires @p ReadUserData and @p WriteUserData
1.196 + * capabilities.
1.197 + *
1.198 + * @param[in] aCategory The new landmark category data.
1.199 + *
1.200 + * @leave KErrArgument 1) Input category does not have a name set or
1.201 + * 2) if a global category identifier is changed in the category object.
1.202 + * @leave KErrAlreadyExists A category with the same name
1.203 + * already exists in the database.
1.204 + * @leave KErrAccessDenied The database is read-only.
1.205 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.206 + */
1.207 + virtual void UpdateCategoryL(
1.208 + const CPosLandmarkCategory& aCategory
1.209 + ) = 0;
1.210 +
1.211 + /**
1.212 + * Removes a landmark category from the database.
1.213 + *
1.214 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.215 + *
1.216 + * If the landmark category does not exist in the database, nothing
1.217 + * happens.
1.218 + *
1.219 + * This call will also remove the category from all landmarks which
1.220 + * contained it.
1.221 + *
1.222 + * The function returns an operation object which can be run in either
1.223 + * synchronous or asynchronous mode. If it is run in asynchronous mode
1.224 + * the client can supervise the progress of the operation.
1.225 + *
1.226 + * If the @ref CPosLmOperation object is deleted before the operation
1.227 + * is complete, it is possible that the category has not been removed,
1.228 + * but some landmarks may no longer contain this category
1.229 + *
1.230 + * The client takes ownership of the returned operation object.
1.231 + *
1.232 + * While removing the category, this operation will acquire a
1.233 + * write-lock on the database.
1.234 + *
1.235 + * This function requires @p ReadUserData and @p WriteUserData
1.236 + * capabilities.
1.237 + *
1.238 + * @param aCategoryId The ID of the landmark category to delete.
1.239 + * @returns A handle to the operation.
1.240 + *
1.241 + * @leave KErrAccessDenied The database is read-only.
1.242 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.243 + */
1.244 + virtual CPosLmOperation* RemoveCategoryL( TPosLmItemId aCategoryId ) = 0;
1.245 +
1.246 + /**
1.247 + * Remove a set of landmark categories from the database.
1.248 + *
1.249 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.250 + *
1.251 + * If any of the landmark categories does not exist in the database, it
1.252 + * is ignored.
1.253 + *
1.254 + * This call will also remove the categories from all landmarks which
1.255 + * contained them.
1.256 + *
1.257 + * The function returns an operation object which can be run in either
1.258 + * synchronous or asynchronous mode. If it is run in asynchronous mode
1.259 + * the client can supervise the progress of the operation.
1.260 + *
1.261 + * If the @ref CPosLmOperation object is deleted before the operation
1.262 + * is complete, it is possible that only a subset of the landmark
1.263 + * categories have been deleted.
1.264 + *
1.265 + * The client takes ownership of the returned operation object.
1.266 + *
1.267 + * If the database is read only, the returned operation will fail with error
1.268 + * code @p KErrAccessDenied.
1.269 + *
1.270 + * This call will also remove the categories from all landmarks which
1.271 + * contained them.
1.272 + *
1.273 + * While removing the category, this operation will acquire a
1.274 + * write-lock on the database.
1.275 + *
1.276 + * This function requires @p ReadUserData and @p WriteUserData
1.277 + * capabilities.
1.278 + *
1.279 + * @param aCategoryIdArray The IDs of the landmark categories to delete.
1.280 + * @returns A handle to the operation.
1.281 + *
1.282 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.283 + */
1.284 + virtual CPosLmOperation* RemoveCategoriesL(
1.285 + const RArray<TPosLmItemId>& aCategoryIdArray
1.286 + ) = 0;
1.287 +
1.288 + /**
1.289 + * Adds a category to a set of landmarks.
1.290 + *
1.291 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.292 + *
1.293 + * If any of the specified landmarks does not exist, the category will
1.294 + * be added to the other landmarks. No error will be reported though.
1.295 + *
1.296 + * If the category is already contained in one of the landmarks, nothing
1.297 + * will be further added to that landmark.
1.298 + *
1.299 + * The function returns an operation object which can be run in either
1.300 + * synchronous or asynchronous mode. If it is run in asynchronous mode
1.301 + * the client can supervise the progress of the operation.
1.302 + *
1.303 + * If the @ref CPosLmOperation object is deleted before the operation
1.304 + * is complete, it is possible that the category has only been added
1.305 + * to a subset of the landmarks.
1.306 + *
1.307 + * The client takes ownership of the returned operation object.
1.308 + *
1.309 + * Note: There is no need to call
1.310 + * @p CPosLandmarkDatabase::UpdateLandmark for this change to take
1.311 + * place.
1.312 + *
1.313 + * If the database is read only, the returned operation will fail with error
1.314 + * code @p KErrAccessDenied.
1.315 + *
1.316 + * While adding the category to the landmarks, this operation will
1.317 + * acquire a write-lock on the database.
1.318 + *
1.319 + * This function requires @p ReadUserData and @p WriteUserData
1.320 + * capabilities.
1.321 + *
1.322 + * @param[in] aCategoryId The category to add to the set of landmarks.
1.323 + * @param[in] aLandmarkIdArray The landmarks to add the category to.
1.324 + * @returns A handle to the operation.
1.325 + *
1.326 + * @leave KErrNotFound The specified category does not exist in database.
1.327 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.328 + */
1.329 + virtual CPosLmOperation* AddCategoryToLandmarksL(
1.330 + TPosLmItemId aCategoryId,
1.331 + RArray<TPosLmItemId>& aLandmarkIdArray
1.332 + ) = 0;
1.333 +
1.334 + /**
1.335 + * Removes a category from a set of landmarks.
1.336 + *
1.337 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.338 + *
1.339 + * If any of the specified landmarks does not exist, the category will
1.340 + * be removed from the other landmarks. No error will be reported though.
1.341 + *
1.342 + * If the category is not found in one of the landmarks, nothing will
1.343 + * happen for that landmark.
1.344 + *
1.345 + * The function returns an operation object which can be run in either
1.346 + * synchronous or asynchronous mode. If it is run in asynchronous mode
1.347 + * the client can supervise the progress of the operation.
1.348 + *
1.349 + * If the @ref CPosLmOperation object is deleted before the operation
1.350 + * is complete, it is possible that the category has only been removed
1.351 + * from a subset of the landmarks.
1.352 + *
1.353 + * The client takes ownership of the returned operation object.
1.354 + *
1.355 + * If the database is read only, the returned operation will fail with error
1.356 + * code @p KErrAccessDenied.
1.357 + *
1.358 + * While removing the category from the landmarks, this operation will
1.359 + * acquire a write-lock on the database.
1.360 + *
1.361 + * This function requires @p ReadUserData and @p WriteUserData
1.362 + * capabilities.
1.363 + *
1.364 + * @param[in] aCategoryId The category to remove from the set of landmarks.
1.365 + * @param[in] aLandmarkIdArray The landmarks to remove the category from.
1.366 + * @returns A handle to the operation.
1.367 + *
1.368 + * @leave KErrNotFound The specified category does not exist in database.
1.369 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.370 + */
1.371 + virtual CPosLmOperation* RemoveCategoryFromLandmarksL(
1.372 + TPosLmItemId aCategoryId,
1.373 + RArray<TPosLmItemId>& aLandmarkIdArray
1.374 + ) = 0;
1.375 +
1.376 + /**
1.377 + * Gets a category by name.
1.378 + *
1.379 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.380 + *
1.381 + * The category name must be unique in the database, so there cannot be
1.382 + * multiple matches.
1.383 + *
1.384 + * This function only looks for an exact match.
1.385 + *
1.386 + * This function requires @p ReadUserData capability.
1.387 + *
1.388 + * @param[in] aCategoryName The name of the category to get.
1.389 + * @return @p KPosLmNullItemId if the category was not found, otherwise
1.390 + * the ID of the category item in the database.
1.391 + *
1.392 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.393 + */
1.394 + virtual TPosLmItemId GetCategoryL(
1.395 + const TDesC& aCategoryName
1.396 + ) = 0;
1.397 +
1.398 + /**
1.399 + * Gets the ID of a global category.
1.400 + *
1.401 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.402 + *
1.403 + * This function requires @p ReadUserData capability.
1.404 + *
1.405 + * @param[in] aGlobalCategory The global category to look for.
1.406 + * @return @p KPosLmNullItemId if the category was not found, otherwise
1.407 + * the ID of the category item in the database.
1.408 + *
1.409 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.410 + */
1.411 + virtual TPosLmItemId GetGlobalCategoryL(
1.412 + TPosLmGlobalCategory aGlobalCategory
1.413 + ) = 0;
1.414 +
1.415 + /**
1.416 + * Gets the predefined name of a global category.
1.417 + *
1.418 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.419 + *
1.420 + * @param[in] aGlobalCategory The global category to get a name for.
1.421 + * @return The name of the global category or @p NULL if the category
1.422 + * is not recognized.
1.423 + *
1.424 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.425 + */
1.426 + virtual HBufC* GlobalCategoryNameL(
1.427 + TPosLmGlobalCategory aGlobalCategory
1.428 + ) = 0;
1.429 +
1.430 + /**
1.431 + * Resets the information for all global categories.
1.432 + *
1.433 + * @pre Database is initialized (see @ref CPosLandmarkDatabase::IsInitializingNeeded).
1.434 + *
1.435 + * Global categories usually has a default name and icon. The client
1.436 + * can change the name and icon. This function resets the name and
1.437 + * icon to the default ones.
1.438 + *
1.439 + * The function returns an operation object which can be run in either
1.440 + * synchronous or asynchronous mode. If it is run in asynchronous mode
1.441 + * the client can supervise the progress of the operation.
1.442 + *
1.443 + * If the @ref CPosLmOperation object is deleted before the operation
1.444 + * is complete, it is possible that that only a subset of the global
1.445 + * categories have been resetted.
1.446 + *
1.447 + * The client takes ownership of the returned operation object.
1.448 + *
1.449 + * While resetting, this operation will acquire a write-lock on the
1.450 + * database.
1.451 + *
1.452 + * This function requires @p ReadUserData and @p WriteUserData
1.453 + * capabilities.
1.454 + *
1.455 + * @returns A handle to the operation.
1.456 + *
1.457 + * @leave KErrAccessDenied The database is read-only.
1.458 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.459 + */
1.460 + virtual CPosLmOperation* ResetGlobalCategoriesL() = 0;
1.461 +
1.462 + protected:
1.463 +
1.464 + // C++ constructor.
1.465 + IMPORT_C CPosLmCategoryManager();
1.466 +
1.467 + private:
1.468 +
1.469 + // Prohibit copy constructor
1.470 + CPosLmCategoryManager( const CPosLmCategoryManager& );
1.471 + // Prohibit assigment operator
1.472 + CPosLmCategoryManager& operator= ( const CPosLmCategoryManager& );
1.473 +
1.474 + private:
1.475 +
1.476 + // Implementation UID
1.477 + TUid iDtorIdKey;
1.478 +
1.479 + };
1.480 +
1.481 +#endif // CPOSLMCATEGORYMANAGER_H
1.482 +
1.483 +