1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/EPos_CPosLandmark.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,608 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: CPosLandmark class
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef CPOSLANDMARK_H
1.23 +#define CPOSLANDMARK_H
1.24 +
1.25 +#include <e32base.h>
1.26 +#include <lbsfields.h>
1.27 +#include <badesca.h>
1.28 +
1.29 +#include "EPos_Landmarks.h"
1.30 +
1.31 +class TLocality;
1.32 +
1.33 +
1.34 +/**
1.35 +* This is a container class for a landmark.
1.36 +*
1.37 +* A landmark is principally a location with a name.
1.38 +*
1.39 +* The landmark object can either be created by a client or retrieved from
1.40 +* @ref CPosLandmarkDatabase.
1.41 +*
1.42 +* A landmark consists of a number of landmark attributes, e.g. landmark name,
1.43 +* landmark position, coverage area, etc.
1.44 +*
1.45 +* A landmark may also contain generic position fields. These position fields
1.46 +* are defined in LbsFieldIds.h. Only text fields are supported.If the client
1.47 +* wants to store a non-text field, the value must first be converted to a
1.48 +* textual representation.
1.49 +* EPositionPlaceId position field added in extension of TPositionFieldId to support Place id
1.50 +* EPositionTimeStamp position field added in extension of TPositionFieldId to support TimeStamp
1.51 +*
1.52 +* CPosLandmark contains functions for setting and getting landmark attributes
1.53 +* and position fields.
1.54 +*
1.55 +* Note: CPosLandmark is only a local representation of the landmark. To
1.56 +* update the database, call @ref CPosLandmarkDatabase::UpdateLandmarkL (or
1.57 +* @ref CPosLandmarkDatabase::AddLandmarkL for a new landmark).
1.58 +*
1.59 +* @lib eposlandmarks.lib
1.60 +* @since S60 3.0
1.61 +*/
1.62 +class CPosLandmark : public CBase
1.63 + {
1.64 + public:
1.65 +
1.66 + /**
1.67 + * Bitmap for specifying a group of landmark attributes. Bit values are
1.68 + * defined by @ref _TAttributes.
1.69 + */
1.70 + typedef TUint32 TAttributes;
1.71 +
1.72 + /**
1.73 + * Specifies a landmark attribute such as landmark name or landmark
1.74 + * position.
1.75 + */
1.76 + enum _TAttributes
1.77 + {
1.78 + /**
1.79 + * No attribute specified.
1.80 + */
1.81 + ENoAttribute = 0x0000 ,
1.82 + /**
1.83 + * The name of the landmark.
1.84 + */
1.85 + ELandmarkName = 0x0001 ,
1.86 + /**
1.87 + * The position of the landmark.
1.88 + */
1.89 + EPosition = 0x0002 ,
1.90 + /**
1.91 + * The landmark coverage radius.
1.92 + */
1.93 + ECoverageRadius = 0x0004 ,
1.94 + /**
1.95 + * The categories of the landmark.
1.96 + */
1.97 + ECategoryInfo = 0x0008 ,
1.98 + /**
1.99 + * The icon that represents the landmark in a UI.
1.100 + */
1.101 + EIcon = 0x0010 ,
1.102 + /**
1.103 + * A description of the landmark.
1.104 + */
1.105 + EDescription = 0x0020 ,
1.106 + /**
1.107 + * PlaceId for the landmark
1.108 + */
1.109 + EPlaceId = 0x0040 ,
1.110 + /**
1.111 + * Timestamp associated with the landmark
1.112 + */
1.113 + ETimeStamp = 0x0080 ,
1.114 + /*
1.115 + * All landmark attributes.
1.116 + */
1.117 + EAllAttributes = 0xFFFF
1.118 + };
1.119 +
1.120 + public:
1.121 +
1.122 + /**
1.123 + * Two-phased constructor.
1.124 + *
1.125 + * @returns A new instance of this class.
1.126 + */
1.127 + IMPORT_C static CPosLandmark* NewLC();
1.128 +
1.129 + /**
1.130 + * Two-phased constructor.
1.131 + *
1.132 + * @returns A new instance of this class.
1.133 + */
1.134 + IMPORT_C static CPosLandmark* NewL();
1.135 +
1.136 + /**
1.137 + * Two-phased copy constructor.
1.138 + *
1.139 + * @param[in] aLandmark The landmark to copy.
1.140 + * @returns A copy of the specified landmark object.
1.141 + */
1.142 + IMPORT_C static CPosLandmark* NewLC(
1.143 + const CPosLandmark& aLandmark
1.144 + );
1.145 +
1.146 + /**
1.147 + * Two-phased copy constructor.
1.148 + *
1.149 + * @param[in] aLandmark The landmark to copy.
1.150 + * @returns A copy of the specified landmark object.
1.151 + */
1.152 + IMPORT_C static CPosLandmark* NewL(
1.153 + const CPosLandmark& aLandmark
1.154 + );
1.155 +
1.156 + /**
1.157 + * Destructor.
1.158 + */
1.159 + virtual ~CPosLandmark();
1.160 +
1.161 + public:
1.162 +
1.163 + /**
1.164 + * Reads the ID of the landmark entry in the database.
1.165 + *
1.166 + * @returns The ID of the landmark entry in the database, or
1.167 + * @p KPosLmNullItemId if the landmark has not been added to the
1.168 + * database yet.
1.169 + */
1.170 + IMPORT_C TPosLmItemId LandmarkId() const;
1.171 +
1.172 + /**
1.173 + * Checks if the landmark is partial.
1.174 + *
1.175 + * A client can read partial information about a landmark from the
1.176 + * database. This function checks if only partial information is
1.177 + * included in the landmark object. Partial landmark can not be used
1.178 + * with @ref CPosLandmarkDatabase::UpdateLandmarkL().
1.179 + *
1.180 + * For more about partial landmarks, see
1.181 + * @ref CPosLandmarkDatabase::ReadPartialLandmarkLC().
1.182 + *
1.183 + * @returns @p EFalse if the landmark contains all the landmark
1.184 + * information, otherwise @p ETrue.
1.185 + */
1.186 + IMPORT_C TBool IsPartial() const;
1.187 +
1.188 + /**
1.189 + * Reads the name of the landmark.
1.190 + *
1.191 + * This function returns error code @p KErrNotFound if the landmark
1.192 + * name is not set in this landmark object. This will be the case if
1.193 + * the landmark is read from the database using partial read and
1.194 + * landmark name is excluded. Note that if a landmark is fully read
1.195 + * from the database, the landmark name will always be included. If no
1.196 + * name has been set for the landmark in the database, it will
1.197 + * have an empty name string "".
1.198 + *
1.199 + * @param[out] aLandmarkName On return contains the landmark name.
1.200 + * @returns @p KErrNone if successful, @p KErrNotFound if the landmark
1.201 + * name is not specified.
1.202 + */
1.203 + IMPORT_C TInt GetLandmarkName(
1.204 + TPtrC& aLandmarkName
1.205 + ) const;
1.206 +
1.207 + /**
1.208 + * Sets the name of the landmark.
1.209 + *
1.210 + * If no name is set for the landmark when it is written to the database,
1.211 + * the landmark in the database will have an empty name string "".
1.212 + *
1.213 + * @param[in] aLandmarkName The landmark name.
1.214 + *
1.215 + * @leave KErrArgument If the name of the landmark is longer than
1.216 + * @p KPosLmMaxTextFieldLength
1.217 + */
1.218 + IMPORT_C void SetLandmarkNameL(
1.219 + const TDesC& aLandmarkName
1.220 + );
1.221 +
1.222 + /**
1.223 + * Reads the landmark position.
1.224 + *
1.225 + * @param[out] aPosition On return contains the landmark position.
1.226 + * @returns @p KErrNone if successful, @p KErrNotFound if the landmark
1.227 + * position is not set.
1.228 + */
1.229 + IMPORT_C TInt GetPosition(
1.230 + TLocality& aPosition
1.231 + ) const;
1.232 +
1.233 + /**
1.234 + * Sets the landmark position.
1.235 + *
1.236 + * Latitude and longitude must be set in the position.
1.237 + *
1.238 + * Only WGS 84 coordinates are allowed. @p KPositionDatumWgs84 must be set as datum.
1.239 + *
1.240 + * @param[in] aPosition The landmark position.
1.241 + *
1.242 + * @leave KErrArgument Latitude and/or longitude is not set or other datum
1.243 + * than @p KPositionDatumWgs84 is used in @p aPosition.
1.244 + */
1.245 + IMPORT_C void SetPositionL(
1.246 + const TLocality& aPosition
1.247 + );
1.248 +
1.249 + /**
1.250 + * Reads the landmark coverage radius.
1.251 + *
1.252 + * Coverage radius is set if the landmark is big, e.g. a city. It
1.253 + * defines the size of the area which the landmark represents.
1.254 + *
1.255 + * @param[out] aCoverageRadius On return contains the coverage radius.
1.256 + * @returns @p KErrNone if successful, @p KErrNotFound if the landmark
1.257 + * coverage radius is not set.
1.258 + */
1.259 + IMPORT_C TInt GetCoverageRadius(
1.260 + TReal32& aCoverageRadius
1.261 + ) const;
1.262 +
1.263 + /**
1.264 + * Sets the landmark coverage radius.
1.265 + *
1.266 + * Coverage radius is set if the landmark is big, e.g. a city. It
1.267 + * defines the size of the area which the landmark represents.
1.268 + *
1.269 + * If coverage radius is set to NaN, then the coverage radius will be
1.270 + * removed.
1.271 + *
1.272 + * @param aCoverageRadius The coverage radius.
1.273 + */
1.274 + IMPORT_C void SetCoverageRadius(
1.275 + TReal32 aCoverageRadius
1.276 + );
1.277 +
1.278 + /**
1.279 + * Adds a category to the landmark.
1.280 + *
1.281 + * If the specified category has already been added, nothing happens.
1.282 + *
1.283 + * @param aCategoryId The category to add.
1.284 + */
1.285 + IMPORT_C void AddCategoryL(
1.286 + TPosLmItemId aCategoryId
1.287 + );
1.288 +
1.289 + /**
1.290 + * Removes a category from the landmark.
1.291 + *
1.292 + * If the specified category is not in the landmark, nothing happens.
1.293 + *
1.294 + * @param aCategoryId The category to remove
1.295 + */
1.296 + IMPORT_C void RemoveCategory(
1.297 + TPosLmItemId aCategoryId
1.298 + );
1.299 +
1.300 + /**
1.301 + * Retrieves the database item IDs for the categories contained in this
1.302 + * landmark.
1.303 + *
1.304 + * @param[out] aCategoryIdArray On return contains the list of this
1.305 + * landmark's categories.
1.306 + */
1.307 + IMPORT_C void GetCategoriesL(
1.308 + RArray<TPosLmItemId>& aCategoryIdArray
1.309 + ) const;
1.310 +
1.311 + /**
1.312 + * Checks if the landmark contains a specific position field.
1.313 + *
1.314 + * @param aFieldId The position field.
1.315 + * @returns @p ETrue if the landmark contains the field, otherwise
1.316 + * @p EFalse.
1.317 + */
1.318 + IMPORT_C TBool IsPositionFieldAvailable(
1.319 + TPositionFieldId aFieldId
1.320 + ) const;
1.321 +
1.322 + /**
1.323 + * Returns the number of position fields set in the landmark.
1.324 + *
1.325 + * @returns The number of position fields set in the landmark.
1.326 + */
1.327 + IMPORT_C TUint NumOfAvailablePositionFields() const;
1.328 +
1.329 + /**
1.330 + * Returns the first position field contained in the landmark.
1.331 + *
1.332 + * This function is used to initiate iteration over the position fields.
1.333 + * @ref NextPositionFieldId() is called to continue the iteration.
1.334 + *
1.335 + * @returns The first position field contained by the landmark, or
1.336 + * @p EPositionFieldNone if there are no position fields in the
1.337 + * landmark.
1.338 + */
1.339 + IMPORT_C TPositionFieldId FirstPositionFieldId() const;
1.340 +
1.341 + /**
1.342 + * Returns the next position field contained in the landmark.
1.343 + *
1.344 + * This function is used to iterate the position fields in the landmark.
1.345 + * @ref FirstPositionFieldId() is called to get the first ID. This ID is
1.346 + * passed to @ref NextPositionFieldId() to obtain the second ID, etc.
1.347 + *
1.348 + * If the client specifies an ID which is not contained in the landmark,
1.349 + * this function will panic with code @p EPosInvalidPositionFieldId. It
1.350 + * is therefore important that the client does not remove the current
1.351 + * field while iterating. If the client still removes the current field,
1.352 + * the client must pass the previous field.
1.353 + *
1.354 + * @param aFieldId The last position field which was read.
1.355 + * @returns The next position field contained by the landmark, or
1.356 + * @p EPositionFieldNone if there are no more position fields in the
1.357 + * landmark.
1.358 + *
1.359 + * @panic "Landmarks Client"-EPosInvalidPositionFieldId Client specified a field ID,
1.360 + * which is not contained in the landmark.
1.361 + */
1.362 + IMPORT_C TPositionFieldId NextPositionFieldId(
1.363 + TPositionFieldId aFieldId
1.364 + ) const;
1.365 +
1.366 + /**
1.367 + * Reads the value of a position field.
1.368 + *
1.369 + * @param[in] aFieldId The position field to read.
1.370 + * @param[out] aFieldValue On return contains the value of the position field.
1.371 + * @returns @p KErrNone if successful, @p KErrNotFound if the landmark
1.372 + * does not contain the specified position field.
1.373 + */
1.374 + IMPORT_C TInt GetPositionField(
1.375 + TPositionFieldId aFieldId,
1.376 + TPtrC& aFieldValue
1.377 + ) const;
1.378 +
1.379 + /**
1.380 + * Sets a position field in the landmark.
1.381 + *
1.382 + * @param[in] aFieldId The position field to set.
1.383 + * @param[in] aFieldValue The new value for the position field.
1.384 + *
1.385 + * @leave KErrArgument If the position field text is longer than
1.386 + * @p KPosLmMaxTextFieldLength.
1.387 + */
1.388 + IMPORT_C void SetPositionFieldL(
1.389 + TPositionFieldId aFieldId,
1.390 + const TDesC& aFieldValue
1.391 + );
1.392 +
1.393 + /**
1.394 + * Removes a position field from the landmark.
1.395 + *
1.396 + * If the specified position field is not contained in the landmark,
1.397 + * nothing will happen.
1.398 + *
1.399 + * @param aFieldId The position field to remove.
1.400 + */
1.401 + IMPORT_C void RemovePositionField(
1.402 + TPositionFieldId aFieldId
1.403 + );
1.404 +
1.405 + /**
1.406 + * Associates the landmark with an icon.
1.407 + *
1.408 + * Icons are found in icon files. To set an icon, the client
1.409 + * must specify the name of the icon file and the index of the
1.410 + * icon within the file.
1.411 + *
1.412 + * The landmark is not affected if the icon file is changed or
1.413 + * removed. It only contains a link to the icon.
1.414 + *
1.415 + * @param[in] aIconFileName The full icon file name.
1.416 + * @param[in] aIconIndex The index of the icon within the icon file.
1.417 + * @param[in] aIconMaskIndex The index of the icon mask within the
1.418 + * icon file.
1.419 + *
1.420 + * @leave KErrArgument The icon file name is longer than @p KMaxFileName.
1.421 + *
1.422 + * @panic "Landmarks Client"-EPosLmInvalidArgument The icon index is negative or
1.423 + * the icon mask index is negative and not equal to @p KPosLmIconMaskNotUsed.
1.424 + */
1.425 + IMPORT_C void SetIconL(
1.426 + const TDesC& aIconFileName,
1.427 + TInt aIconIndex,
1.428 + TInt aIconMaskIndex
1.429 + );
1.430 +
1.431 + /**
1.432 + * Returns the link to the icon associated with the landmark.
1.433 + *
1.434 + * Icons are found in icon files. It is referenced by the name of
1.435 + * the icon file and the index of the icon within the file.
1.436 + *
1.437 + * The landmark is not affected if the icon file is changed or
1.438 + * removed. It only contains a link to the icon. This means that the
1.439 + * link could be invalid.
1.440 + *
1.441 + * @param[out] aIconFileName The full icon file name.
1.442 + * @param[out] aIconIndex The index of the icon within the icon file.
1.443 + * @param[out] aIconMaskIndex The index of the icon mask within the
1.444 + * icon file. If no icon mask index is defined @p KPosLmIconMaskNotUsed
1.445 + * is returned.
1.446 + *
1.447 + * @returns @p KErrNone if successful, @p KErrNotFound if the icon is
1.448 + * not set.
1.449 + */
1.450 + IMPORT_C TInt GetIcon(
1.451 + TPtrC& aIconFileName,
1.452 + TInt& aIconIndex,
1.453 + TInt& aIconMaskIndex
1.454 + ) const;
1.455 +
1.456 + /**
1.457 + * Reads the description of the landmark.
1.458 + *
1.459 + * This function returns error code @p KErrNotFound if the landmark
1.460 + * description is not set in this landmark object. This will be the case
1.461 + * if the landmark is read from the database using partial read and
1.462 + * landmark description is excluded. Note that if a landmark is fully
1.463 + * read from the database, the landmark description is always
1.464 + * included. If no description has been set for the landmark in
1.465 + * the database, it is set to an empty string "".
1.466 + *
1.467 + * @param[out] aLandmarkDescription On return contains the landmark description.
1.468 + * @returns @p KErrNone if successful, @p KErrNotFound if the landmark
1.469 + * description is not specified.
1.470 + */
1.471 + IMPORT_C TInt GetLandmarkDescription(
1.472 + TPtrC& aLandmarkDescription
1.473 + ) const;
1.474 +
1.475 + /**
1.476 + * Sets a description for the landmark.
1.477 + *
1.478 + * If no description is set for the landmark when it is written to the
1.479 + * database, the landmark in the database will have an empty description
1.480 + * string "".
1.481 + *
1.482 + * @param[in] aLandmarkDescription The landmark description.
1.483 + *
1.484 + * @leave KErrArgument The name of the landmark is longer than
1.485 + * @p KPosLmMaxDescriptionLength.
1.486 + */
1.487 + IMPORT_C void SetLandmarkDescriptionL(
1.488 + const TDesC& aLandmarkDescription
1.489 + );
1.490 +
1.491 + /**
1.492 + * Removes landmark attributes from the landmark.
1.493 + *
1.494 + * @param aAttributes A bitmap specifying which landmark attributes to
1.495 + * remove.
1.496 + */
1.497 + IMPORT_C void RemoveLandmarkAttributes(
1.498 + TAttributes aAttributes
1.499 + );
1.500 +
1.501 + /**
1.502 + * @internal */
1.503 + /*
1.504 + * Sets the partial update flag to the landmark.
1.505 + * This flag is used to indicate if only partial information is included
1.506 + * in the landmark object.
1.507 + *
1.508 + * @param aPartial @p EFalse if the landmark contains all the landmark
1.509 + * information, otherwise @p ETrue.
1.510 + */
1.511 + void SetPartialL(
1.512 + TBool aPartial
1.513 + );
1.514 +
1.515 + /**
1.516 + * @internal */
1.517 + /*
1.518 + * Sets the landmark ID to the landmark.
1.519 + *
1.520 + * @param aId The landmark ID to set.
1.521 + */
1.522 + void SetLandmarkIdL(
1.523 + TPosLmItemId aId
1.524 + );
1.525 +
1.526 + /**
1.527 + * Sets the PlaceId for the landmark
1.528 + * @param[in] aPId The place id of the landmark
1.529 + * @leave Symbian error codes
1.530 + */
1.531 + IMPORT_C void SetPlaceIdL( const TDesC& aPId );
1.532 +
1.533 + /**
1.534 + * Gets the PlaceId of the landmark
1.535 + * @param[out] aPId On return contains the place id of the landmark
1.536 + * @return KErrNone if successful , else KErrNotFound if PlaceId is
1.537 + * not specified.
1.538 + */
1.539 + IMPORT_C TInt GetPlaceId( TPtrC& aPId ) const;
1.540 +
1.541 + /**
1.542 + * Sets the timestamp of the landmark.
1.543 + * @param[in] aTimeStamp Timestamp of the landmark(Full date & time)
1.544 + * @leave KErrArgument If the full date & time have not been specified.
1.545 + */
1.546 + IMPORT_C void SetTimeStampL( const TTime aTimeStamp );
1.547 +
1.548 + /**
1.549 + * Gets the timestamp of the landmark
1.550 + * @param[out] aTimeStamp On return contains the timestamp of the landamrk
1.551 + * @return KErrNone if successful , else KErrNotFound if TimeStamp is
1.552 + * not specified.
1.553 + */
1.554 + IMPORT_C TInt GetTimeStamp( TTime& aTimeStamp )const;
1.555 +
1.556 + private:
1.557 +
1.558 + // C++ constructor.
1.559 + CPosLandmark();
1.560 +
1.561 + // Prohibit copy constructor
1.562 + CPosLandmark(const CPosLandmark&);
1.563 +
1.564 + // Prohibit assigment operator
1.565 + CPosLandmark& operator= (const CPosLandmark&);
1.566 +
1.567 + void ConstructL();
1.568 + void ConstructL(const CPosLandmark& aLandmark);
1.569 +
1.570 + private:
1.571 +
1.572 + // Landmark ID
1.573 + TPosLmItemId iId;
1.574 +
1.575 + // Partial landmark flag
1.576 + TBool iIsPartial;
1.577 +
1.578 + // Landmark name
1.579 + HBufC* iLandmarkName;
1.580 +
1.581 + // Landmark position information
1.582 + TLocality* iPosition;
1.583 +
1.584 + // Landmark coverage radius
1.585 + TReal32 iCoverageRadius;
1.586 +
1.587 + // Landmark categories
1.588 + RArray<TPosLmItemId> iCategoryArray;
1.589 +
1.590 + // Landmark position field IDs
1.591 + RArray<TUint> iPositionFieldIds;
1.592 +
1.593 + // Landmark position field strings
1.594 + CDesCArray* iPositionFieldStrings;
1.595 +
1.596 + // Landmark icon filename
1.597 + HBufC* iIconFileName;
1.598 +
1.599 + // Landmark icon index
1.600 + TInt iIconIndex;
1.601 +
1.602 + // Landmark icon mask index
1.603 + TInt iIconMaskIndex;
1.604 +
1.605 + // Landmark description
1.606 + HBufC* iLandmarkDescription;
1.607 + };
1.608 +
1.609 +#endif // CPOSLANDMARK_H
1.610 +
1.611 +