|
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 "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: CPosLandmark class |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef CPOSLANDMARK_H |
|
20 #define CPOSLANDMARK_H |
|
21 |
|
22 #include <e32base.h> |
|
23 #include <lbsfields.h> |
|
24 #include <badesca.h> |
|
25 |
|
26 #include "EPos_Landmarks.h" |
|
27 |
|
28 class TLocality; |
|
29 |
|
30 |
|
31 /** |
|
32 * This is a container class for a landmark. |
|
33 * |
|
34 * A landmark is principally a location with a name. |
|
35 * |
|
36 * The landmark object can either be created by a client or retrieved from |
|
37 * @ref CPosLandmarkDatabase. |
|
38 * |
|
39 * A landmark consists of a number of landmark attributes, e.g. landmark name, |
|
40 * landmark position, coverage area, etc. |
|
41 * |
|
42 * A landmark may also contain generic position fields. These position fields |
|
43 * are defined in LbsFieldIds.h. Only text fields are supported.If the client |
|
44 * wants to store a non-text field, the value must first be converted to a |
|
45 * textual representation. |
|
46 * EPositionPlaceId position field added in extension of TPositionFieldId to support Place id |
|
47 * EPositionTimeStamp position field added in extension of TPositionFieldId to support TimeStamp |
|
48 * |
|
49 * CPosLandmark contains functions for setting and getting landmark attributes |
|
50 * and position fields. |
|
51 * |
|
52 * Note: CPosLandmark is only a local representation of the landmark. To |
|
53 * update the database, call @ref CPosLandmarkDatabase::UpdateLandmarkL (or |
|
54 * @ref CPosLandmarkDatabase::AddLandmarkL for a new landmark). |
|
55 * |
|
56 * @lib eposlandmarks.lib |
|
57 * @since S60 3.0 |
|
58 */ |
|
59 class CPosLandmark : public CBase |
|
60 { |
|
61 public: |
|
62 |
|
63 /** |
|
64 * Bitmap for specifying a group of landmark attributes. Bit values are |
|
65 * defined by @ref _TAttributes. |
|
66 */ |
|
67 typedef TUint32 TAttributes; |
|
68 |
|
69 /** |
|
70 * Specifies a landmark attribute such as landmark name or landmark |
|
71 * position. |
|
72 */ |
|
73 enum _TAttributes |
|
74 { |
|
75 /** |
|
76 * No attribute specified. |
|
77 */ |
|
78 ENoAttribute = 0x0000 , |
|
79 /** |
|
80 * The name of the landmark. |
|
81 */ |
|
82 ELandmarkName = 0x0001 , |
|
83 /** |
|
84 * The position of the landmark. |
|
85 */ |
|
86 EPosition = 0x0002 , |
|
87 /** |
|
88 * The landmark coverage radius. |
|
89 */ |
|
90 ECoverageRadius = 0x0004 , |
|
91 /** |
|
92 * The categories of the landmark. |
|
93 */ |
|
94 ECategoryInfo = 0x0008 , |
|
95 /** |
|
96 * The icon that represents the landmark in a UI. |
|
97 */ |
|
98 EIcon = 0x0010 , |
|
99 /** |
|
100 * A description of the landmark. |
|
101 */ |
|
102 EDescription = 0x0020 , |
|
103 /** |
|
104 * PlaceId for the landmark |
|
105 */ |
|
106 EPlaceId = 0x0040 , |
|
107 /** |
|
108 * Timestamp associated with the landmark |
|
109 */ |
|
110 ETimeStamp = 0x0080 , |
|
111 /* |
|
112 * All landmark attributes. |
|
113 */ |
|
114 EAllAttributes = 0xFFFF |
|
115 }; |
|
116 |
|
117 public: |
|
118 |
|
119 /** |
|
120 * Two-phased constructor. |
|
121 * |
|
122 * @returns A new instance of this class. |
|
123 */ |
|
124 IMPORT_C static CPosLandmark* NewLC(); |
|
125 |
|
126 /** |
|
127 * Two-phased constructor. |
|
128 * |
|
129 * @returns A new instance of this class. |
|
130 */ |
|
131 IMPORT_C static CPosLandmark* NewL(); |
|
132 |
|
133 /** |
|
134 * Two-phased copy constructor. |
|
135 * |
|
136 * @param[in] aLandmark The landmark to copy. |
|
137 * @returns A copy of the specified landmark object. |
|
138 */ |
|
139 IMPORT_C static CPosLandmark* NewLC( |
|
140 const CPosLandmark& aLandmark |
|
141 ); |
|
142 |
|
143 /** |
|
144 * Two-phased copy constructor. |
|
145 * |
|
146 * @param[in] aLandmark The landmark to copy. |
|
147 * @returns A copy of the specified landmark object. |
|
148 */ |
|
149 IMPORT_C static CPosLandmark* NewL( |
|
150 const CPosLandmark& aLandmark |
|
151 ); |
|
152 |
|
153 /** |
|
154 * Destructor. |
|
155 */ |
|
156 virtual ~CPosLandmark(); |
|
157 |
|
158 public: |
|
159 |
|
160 /** |
|
161 * Reads the ID of the landmark entry in the database. |
|
162 * |
|
163 * @returns The ID of the landmark entry in the database, or |
|
164 * @p KPosLmNullItemId if the landmark has not been added to the |
|
165 * database yet. |
|
166 */ |
|
167 IMPORT_C TPosLmItemId LandmarkId() const; |
|
168 |
|
169 /** |
|
170 * Checks if the landmark is partial. |
|
171 * |
|
172 * A client can read partial information about a landmark from the |
|
173 * database. This function checks if only partial information is |
|
174 * included in the landmark object. Partial landmark can not be used |
|
175 * with @ref CPosLandmarkDatabase::UpdateLandmarkL(). |
|
176 * |
|
177 * For more about partial landmarks, see |
|
178 * @ref CPosLandmarkDatabase::ReadPartialLandmarkLC(). |
|
179 * |
|
180 * @returns @p EFalse if the landmark contains all the landmark |
|
181 * information, otherwise @p ETrue. |
|
182 */ |
|
183 IMPORT_C TBool IsPartial() const; |
|
184 |
|
185 /** |
|
186 * Reads the name of the landmark. |
|
187 * |
|
188 * This function returns error code @p KErrNotFound if the landmark |
|
189 * name is not set in this landmark object. This will be the case if |
|
190 * the landmark is read from the database using partial read and |
|
191 * landmark name is excluded. Note that if a landmark is fully read |
|
192 * from the database, the landmark name will always be included. If no |
|
193 * name has been set for the landmark in the database, it will |
|
194 * have an empty name string "". |
|
195 * |
|
196 * @param[out] aLandmarkName On return contains the landmark name. |
|
197 * @returns @p KErrNone if successful, @p KErrNotFound if the landmark |
|
198 * name is not specified. |
|
199 */ |
|
200 IMPORT_C TInt GetLandmarkName( |
|
201 TPtrC& aLandmarkName |
|
202 ) const; |
|
203 |
|
204 /** |
|
205 * Sets the name of the landmark. |
|
206 * |
|
207 * If no name is set for the landmark when it is written to the database, |
|
208 * the landmark in the database will have an empty name string "". |
|
209 * |
|
210 * @param[in] aLandmarkName The landmark name. |
|
211 * |
|
212 * @leave KErrArgument If the name of the landmark is longer than |
|
213 * @p KPosLmMaxTextFieldLength |
|
214 */ |
|
215 IMPORT_C void SetLandmarkNameL( |
|
216 const TDesC& aLandmarkName |
|
217 ); |
|
218 |
|
219 /** |
|
220 * Reads the landmark position. |
|
221 * |
|
222 * @param[out] aPosition On return contains the landmark position. |
|
223 * @returns @p KErrNone if successful, @p KErrNotFound if the landmark |
|
224 * position is not set. |
|
225 */ |
|
226 IMPORT_C TInt GetPosition( |
|
227 TLocality& aPosition |
|
228 ) const; |
|
229 |
|
230 /** |
|
231 * Sets the landmark position. |
|
232 * |
|
233 * Latitude and longitude must be set in the position. |
|
234 * |
|
235 * Only WGS 84 coordinates are allowed. @p KPositionDatumWgs84 must be set as datum. |
|
236 * |
|
237 * @param[in] aPosition The landmark position. |
|
238 * |
|
239 * @leave KErrArgument Latitude and/or longitude is not set or other datum |
|
240 * than @p KPositionDatumWgs84 is used in @p aPosition. |
|
241 */ |
|
242 IMPORT_C void SetPositionL( |
|
243 const TLocality& aPosition |
|
244 ); |
|
245 |
|
246 /** |
|
247 * Reads the landmark coverage radius. |
|
248 * |
|
249 * Coverage radius is set if the landmark is big, e.g. a city. It |
|
250 * defines the size of the area which the landmark represents. |
|
251 * |
|
252 * @param[out] aCoverageRadius On return contains the coverage radius. |
|
253 * @returns @p KErrNone if successful, @p KErrNotFound if the landmark |
|
254 * coverage radius is not set. |
|
255 */ |
|
256 IMPORT_C TInt GetCoverageRadius( |
|
257 TReal32& aCoverageRadius |
|
258 ) const; |
|
259 |
|
260 /** |
|
261 * Sets the landmark coverage radius. |
|
262 * |
|
263 * Coverage radius is set if the landmark is big, e.g. a city. It |
|
264 * defines the size of the area which the landmark represents. |
|
265 * |
|
266 * If coverage radius is set to NaN, then the coverage radius will be |
|
267 * removed. |
|
268 * |
|
269 * @param aCoverageRadius The coverage radius. |
|
270 */ |
|
271 IMPORT_C void SetCoverageRadius( |
|
272 TReal32 aCoverageRadius |
|
273 ); |
|
274 |
|
275 /** |
|
276 * Adds a category to the landmark. |
|
277 * |
|
278 * If the specified category has already been added, nothing happens. |
|
279 * |
|
280 * @param aCategoryId The category to add. |
|
281 */ |
|
282 IMPORT_C void AddCategoryL( |
|
283 TPosLmItemId aCategoryId |
|
284 ); |
|
285 |
|
286 /** |
|
287 * Removes a category from the landmark. |
|
288 * |
|
289 * If the specified category is not in the landmark, nothing happens. |
|
290 * |
|
291 * @param aCategoryId The category to remove |
|
292 */ |
|
293 IMPORT_C void RemoveCategory( |
|
294 TPosLmItemId aCategoryId |
|
295 ); |
|
296 |
|
297 /** |
|
298 * Retrieves the database item IDs for the categories contained in this |
|
299 * landmark. |
|
300 * |
|
301 * @param[out] aCategoryIdArray On return contains the list of this |
|
302 * landmark's categories. |
|
303 */ |
|
304 IMPORT_C void GetCategoriesL( |
|
305 RArray<TPosLmItemId>& aCategoryIdArray |
|
306 ) const; |
|
307 |
|
308 /** |
|
309 * Checks if the landmark contains a specific position field. |
|
310 * |
|
311 * @param aFieldId The position field. |
|
312 * @returns @p ETrue if the landmark contains the field, otherwise |
|
313 * @p EFalse. |
|
314 */ |
|
315 IMPORT_C TBool IsPositionFieldAvailable( |
|
316 TPositionFieldId aFieldId |
|
317 ) const; |
|
318 |
|
319 /** |
|
320 * Returns the number of position fields set in the landmark. |
|
321 * |
|
322 * @returns The number of position fields set in the landmark. |
|
323 */ |
|
324 IMPORT_C TUint NumOfAvailablePositionFields() const; |
|
325 |
|
326 /** |
|
327 * Returns the first position field contained in the landmark. |
|
328 * |
|
329 * This function is used to initiate iteration over the position fields. |
|
330 * @ref NextPositionFieldId() is called to continue the iteration. |
|
331 * |
|
332 * @returns The first position field contained by the landmark, or |
|
333 * @p EPositionFieldNone if there are no position fields in the |
|
334 * landmark. |
|
335 */ |
|
336 IMPORT_C TPositionFieldId FirstPositionFieldId() const; |
|
337 |
|
338 /** |
|
339 * Returns the next position field contained in the landmark. |
|
340 * |
|
341 * This function is used to iterate the position fields in the landmark. |
|
342 * @ref FirstPositionFieldId() is called to get the first ID. This ID is |
|
343 * passed to @ref NextPositionFieldId() to obtain the second ID, etc. |
|
344 * |
|
345 * If the client specifies an ID which is not contained in the landmark, |
|
346 * this function will panic with code @p EPosInvalidPositionFieldId. It |
|
347 * is therefore important that the client does not remove the current |
|
348 * field while iterating. If the client still removes the current field, |
|
349 * the client must pass the previous field. |
|
350 * |
|
351 * @param aFieldId The last position field which was read. |
|
352 * @returns The next position field contained by the landmark, or |
|
353 * @p EPositionFieldNone if there are no more position fields in the |
|
354 * landmark. |
|
355 * |
|
356 * @panic "Landmarks Client"-EPosInvalidPositionFieldId Client specified a field ID, |
|
357 * which is not contained in the landmark. |
|
358 */ |
|
359 IMPORT_C TPositionFieldId NextPositionFieldId( |
|
360 TPositionFieldId aFieldId |
|
361 ) const; |
|
362 |
|
363 /** |
|
364 * Reads the value of a position field. |
|
365 * |
|
366 * @param[in] aFieldId The position field to read. |
|
367 * @param[out] aFieldValue On return contains the value of the position field. |
|
368 * @returns @p KErrNone if successful, @p KErrNotFound if the landmark |
|
369 * does not contain the specified position field. |
|
370 */ |
|
371 IMPORT_C TInt GetPositionField( |
|
372 TPositionFieldId aFieldId, |
|
373 TPtrC& aFieldValue |
|
374 ) const; |
|
375 |
|
376 /** |
|
377 * Sets a position field in the landmark. |
|
378 * |
|
379 * @param[in] aFieldId The position field to set. |
|
380 * @param[in] aFieldValue The new value for the position field. |
|
381 * |
|
382 * @leave KErrArgument If the position field text is longer than |
|
383 * @p KPosLmMaxTextFieldLength. |
|
384 */ |
|
385 IMPORT_C void SetPositionFieldL( |
|
386 TPositionFieldId aFieldId, |
|
387 const TDesC& aFieldValue |
|
388 ); |
|
389 |
|
390 /** |
|
391 * Removes a position field from the landmark. |
|
392 * |
|
393 * If the specified position field is not contained in the landmark, |
|
394 * nothing will happen. |
|
395 * |
|
396 * @param aFieldId The position field to remove. |
|
397 */ |
|
398 IMPORT_C void RemovePositionField( |
|
399 TPositionFieldId aFieldId |
|
400 ); |
|
401 |
|
402 /** |
|
403 * Associates the landmark with an icon. |
|
404 * |
|
405 * Icons are found in icon files. To set an icon, the client |
|
406 * must specify the name of the icon file and the index of the |
|
407 * icon within the file. |
|
408 * |
|
409 * The landmark is not affected if the icon file is changed or |
|
410 * removed. It only contains a link to the icon. |
|
411 * |
|
412 * @param[in] aIconFileName The full icon file name. |
|
413 * @param[in] aIconIndex The index of the icon within the icon file. |
|
414 * @param[in] aIconMaskIndex The index of the icon mask within the |
|
415 * icon file. |
|
416 * |
|
417 * @leave KErrArgument The icon file name is longer than @p KMaxFileName. |
|
418 * |
|
419 * @panic "Landmarks Client"-EPosLmInvalidArgument The icon index is negative or |
|
420 * the icon mask index is negative and not equal to @p KPosLmIconMaskNotUsed. |
|
421 */ |
|
422 IMPORT_C void SetIconL( |
|
423 const TDesC& aIconFileName, |
|
424 TInt aIconIndex, |
|
425 TInt aIconMaskIndex |
|
426 ); |
|
427 |
|
428 /** |
|
429 * Returns the link to the icon associated with the landmark. |
|
430 * |
|
431 * Icons are found in icon files. It is referenced by the name of |
|
432 * the icon file and the index of the icon within the file. |
|
433 * |
|
434 * The landmark is not affected if the icon file is changed or |
|
435 * removed. It only contains a link to the icon. This means that the |
|
436 * link could be invalid. |
|
437 * |
|
438 * @param[out] aIconFileName The full icon file name. |
|
439 * @param[out] aIconIndex The index of the icon within the icon file. |
|
440 * @param[out] aIconMaskIndex The index of the icon mask within the |
|
441 * icon file. If no icon mask index is defined @p KPosLmIconMaskNotUsed |
|
442 * is returned. |
|
443 * |
|
444 * @returns @p KErrNone if successful, @p KErrNotFound if the icon is |
|
445 * not set. |
|
446 */ |
|
447 IMPORT_C TInt GetIcon( |
|
448 TPtrC& aIconFileName, |
|
449 TInt& aIconIndex, |
|
450 TInt& aIconMaskIndex |
|
451 ) const; |
|
452 |
|
453 /** |
|
454 * Reads the description of the landmark. |
|
455 * |
|
456 * This function returns error code @p KErrNotFound if the landmark |
|
457 * description is not set in this landmark object. This will be the case |
|
458 * if the landmark is read from the database using partial read and |
|
459 * landmark description is excluded. Note that if a landmark is fully |
|
460 * read from the database, the landmark description is always |
|
461 * included. If no description has been set for the landmark in |
|
462 * the database, it is set to an empty string "". |
|
463 * |
|
464 * @param[out] aLandmarkDescription On return contains the landmark description. |
|
465 * @returns @p KErrNone if successful, @p KErrNotFound if the landmark |
|
466 * description is not specified. |
|
467 */ |
|
468 IMPORT_C TInt GetLandmarkDescription( |
|
469 TPtrC& aLandmarkDescription |
|
470 ) const; |
|
471 |
|
472 /** |
|
473 * Sets a description for the landmark. |
|
474 * |
|
475 * If no description is set for the landmark when it is written to the |
|
476 * database, the landmark in the database will have an empty description |
|
477 * string "". |
|
478 * |
|
479 * @param[in] aLandmarkDescription The landmark description. |
|
480 * |
|
481 * @leave KErrArgument The name of the landmark is longer than |
|
482 * @p KPosLmMaxDescriptionLength. |
|
483 */ |
|
484 IMPORT_C void SetLandmarkDescriptionL( |
|
485 const TDesC& aLandmarkDescription |
|
486 ); |
|
487 |
|
488 /** |
|
489 * Removes landmark attributes from the landmark. |
|
490 * |
|
491 * @param aAttributes A bitmap specifying which landmark attributes to |
|
492 * remove. |
|
493 */ |
|
494 IMPORT_C void RemoveLandmarkAttributes( |
|
495 TAttributes aAttributes |
|
496 ); |
|
497 |
|
498 /** |
|
499 * @internal */ |
|
500 /* |
|
501 * Sets the partial update flag to the landmark. |
|
502 * This flag is used to indicate if only partial information is included |
|
503 * in the landmark object. |
|
504 * |
|
505 * @param aPartial @p EFalse if the landmark contains all the landmark |
|
506 * information, otherwise @p ETrue. |
|
507 */ |
|
508 void SetPartialL( |
|
509 TBool aPartial |
|
510 ); |
|
511 |
|
512 /** |
|
513 * @internal */ |
|
514 /* |
|
515 * Sets the landmark ID to the landmark. |
|
516 * |
|
517 * @param aId The landmark ID to set. |
|
518 */ |
|
519 void SetLandmarkIdL( |
|
520 TPosLmItemId aId |
|
521 ); |
|
522 |
|
523 /** |
|
524 * Sets the PlaceId for the landmark |
|
525 * @param[in] aPId The place id of the landmark |
|
526 * @leave Symbian error codes |
|
527 */ |
|
528 IMPORT_C void SetPlaceIdL( const TDesC& aPId ); |
|
529 |
|
530 /** |
|
531 * Gets the PlaceId of the landmark |
|
532 * @param[out] aPId On return contains the place id of the landmark |
|
533 * @return KErrNone if successful , else KErrNotFound if PlaceId is |
|
534 * not specified. |
|
535 */ |
|
536 IMPORT_C TInt GetPlaceId( TPtrC& aPId ) const; |
|
537 |
|
538 /** |
|
539 * Sets the timestamp of the landmark. |
|
540 * @param[in] aTimeStamp Timestamp of the landmark(Full date & time) |
|
541 * @leave KErrArgument If the full date & time have not been specified. |
|
542 */ |
|
543 IMPORT_C void SetTimeStampL( const TTime aTimeStamp ); |
|
544 |
|
545 /** |
|
546 * Gets the timestamp of the landmark |
|
547 * @param[out] aTimeStamp On return contains the timestamp of the landamrk |
|
548 * @return KErrNone if successful , else KErrNotFound if TimeStamp is |
|
549 * not specified. |
|
550 */ |
|
551 IMPORT_C TInt GetTimeStamp( TTime& aTimeStamp )const; |
|
552 |
|
553 private: |
|
554 |
|
555 // C++ constructor. |
|
556 CPosLandmark(); |
|
557 |
|
558 // Prohibit copy constructor |
|
559 CPosLandmark(const CPosLandmark&); |
|
560 |
|
561 // Prohibit assigment operator |
|
562 CPosLandmark& operator= (const CPosLandmark&); |
|
563 |
|
564 void ConstructL(); |
|
565 void ConstructL(const CPosLandmark& aLandmark); |
|
566 |
|
567 private: |
|
568 |
|
569 // Landmark ID |
|
570 TPosLmItemId iId; |
|
571 |
|
572 // Partial landmark flag |
|
573 TBool iIsPartial; |
|
574 |
|
575 // Landmark name |
|
576 HBufC* iLandmarkName; |
|
577 |
|
578 // Landmark position information |
|
579 TLocality* iPosition; |
|
580 |
|
581 // Landmark coverage radius |
|
582 TReal32 iCoverageRadius; |
|
583 |
|
584 // Landmark categories |
|
585 RArray<TPosLmItemId> iCategoryArray; |
|
586 |
|
587 // Landmark position field IDs |
|
588 RArray<TUint> iPositionFieldIds; |
|
589 |
|
590 // Landmark position field strings |
|
591 CDesCArray* iPositionFieldStrings; |
|
592 |
|
593 // Landmark icon filename |
|
594 HBufC* iIconFileName; |
|
595 |
|
596 // Landmark icon index |
|
597 TInt iIconIndex; |
|
598 |
|
599 // Landmark icon mask index |
|
600 TInt iIconMaskIndex; |
|
601 |
|
602 // Landmark description |
|
603 HBufC* iLandmarkDescription; |
|
604 }; |
|
605 |
|
606 #endif // CPOSLANDMARK_H |
|
607 |
|
608 |