1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __LBSCOMMON_H__
17 #define __LBSCOMMON_H__
21 #include <lbsrequestor.h>
22 #include <lbsclasstypes.h>
23 #include <lbserrors.h>
24 #include <lbsvariant.h>
29 // A compile time assert macro. The aExpr parameter must evaluate to an
30 // integer value at compile time.
31 // eg. sizeof(TTime) == KSizeOfTInt64
32 // If aExpr is false, the compiler generates an error.
33 // If aExpr is true, the compilation continues, and use of this macro will not
34 // result in any extra object code.
36 #define POSITION_COMPILE_TIME_ASSERT(aExpr) typedef char assert_type[aExpr ? 1 : -1]
42 Maximum characters in module name.
43 If __S60_ is defined in lbsvariant.h the constant is 64 otherwise it is 20
45 const TInt KPositionMaxModuleName = __LBS_MAX_MODULE_NAME;
51 Maximum size for TUInt
53 const TUint KPositionMaxSizeQualityItem = sizeof(TInt64);
59 Maximum size for fields
61 const TUint KPositionMaxSectionFields = 10;
67 Defines typedef for TPositionModuleId
69 typedef TUid TPositionModuleId;
77 const TPositionModuleId KPositionNullModuleId = {KNullUidValue};
80 class TPositionClassTypeBase
82 The base class for classes used to store position information
89 IMPORT_C TUint32 PositionClassType() const;
90 IMPORT_C TUint PositionClassSize() const;
93 TPositionClassTypeBase();
96 /** The type of the derived class */
97 TUint32 iPosClassType;
98 /** The size of the derived class */
102 class TPositionQualityItem
104 The class for classes used to store position quality
111 /** Quality result */
123 enum TValuePreference
125 /** Smaller values */
126 EPreferSmallerValues,
127 /** Greater values */
131 /** Size of data type
157 /** Time in microseconds */
158 ETTimeIntervalMicroSeconds
161 Constructor for TPositionQualityItem
163 TPositionQualityItem();
168 TInt Compare(const TPositionQualityItem& aItem, TResult& aComparison) const;
170 Sets Position Quality
172 void Set(TDataType aDataType, TValuePreference aValuePreference,
173 const TAny* aData, TUint aSizeOfData);
175 Gets position quality
177 TInt Get(TDataType aDataType, TAny* aData, TUint aSizeOfData) const;
180 Whether or not this element has a defined state
182 TBool IsDefined() const;
185 /** Internal datatype */
187 /** Internel value preference */
188 TValuePreference iScaleDirection;
189 /** Unused variable for future expansion. */
190 TUint8 iData[KPositionMaxSizeQualityItem];
193 class TPositionQualityBase : public TPositionClassTypeBase
195 The base class for classes used to store position quality information
202 IMPORT_C TInt Compare(const TPositionQualityBase& aPositionQuality,
203 TInt aElementToCompare,
204 TPositionQualityItem::TResult& aComparison) const;
207 Returns whether an element is defined
208 @param aElementId The element Id of that we're interested in.
209 @return TBool if defined
211 IMPORT_C TBool IsDefined(TInt aElementId) const;
212 IMPORT_C TInt HighWaterMark() const;
214 IMPORT_C TPositionQualityBase();
216 IMPORT_C void ResetElement(TInt aElementId);
220 Sets the data of an element from the array of elements.
221 @param aElementId The element Id of that we're interested in.
222 @param aDataType The datatype of the data to be fetched.
223 @param aValuePreference Quality preferences
224 @param aData A pointer to the data to be written into.
227 inline void SetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
228 TPositionQualityItem::TValuePreference aValuePreference, T aData)
229 {DoSetElement(aElementId, aDataType, aValuePreference, &aData, sizeof(T));}
232 Gets the data of an element from the array of elements.
233 @param aElementId The element Id of that we're interested in.
234 @param aDataType The datatype of the data to be fetched.
235 @param aData A pointer to the data to be written into.
236 @return Standard Symbian OS Error code
239 inline TInt GetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
241 {return DoGetElement(aElementId, aDataType, &aData, sizeof(T));}
244 IMPORT_C void DoSetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
245 TPositionQualityItem::TValuePreference aValuePreference,
246 const TAny* aData, TUint aSizeOfData);
248 IMPORT_C TInt DoGetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
249 TAny* aData, TUint aSizeOfData) const;
251 /** Internal array */
252 TFixedArray<TPositionQualityItem, KPositionMaxSectionFields> iPositionQualityData;
253 /** Internal highwater mark */
257 class TPositionQuality : public TPositionQualityBase
259 The standard position quality class.
266 /** Cost Indicator for position request */
270 This is the unassigned value and should not be returned */
274 No cost is expected to be incurred when obtaining a position fix */
278 The positioning module is uncertain if the user will incur a charge. */
282 The positioning module expects a charge to be levied when obtaining
283 position information */
287 /** Power consumption */
288 enum TPowerConsumption
290 /** Unknown power consumption
291 The positioning module is unable to determine the likely power drain */
294 /** Zero power consumption
295 No internal power will be used when obtaining a position fix */
298 /** Low power consumption
299 The positioning module expects a minimum power drain when using the
300 associated technology. This may be comparable to the power usage when
301 the phone is in standby mode. */
304 /** Medium power consumption
305 The positioning module expects a moderate power drain when using the
306 associated technology. This may be comparable to the power usage when
307 the phone is being actively used */
310 /** High power consumption
311 The positioning module expects a high power drain when using the
312 associated technology. Use of this module will quickly consume the phone's batteries */
317 IMPORT_C TPositionQuality();
319 IMPORT_C TTimeIntervalMicroSeconds TimeToFirstFix() const;
320 IMPORT_C TTimeIntervalMicroSeconds TimeToNextFix() const;
322 IMPORT_C TReal32 HorizontalAccuracy() const;
323 IMPORT_C TReal32 VerticalAccuracy() const;
325 IMPORT_C TCostIndicator CostIndicator() const;
326 IMPORT_C TPowerConsumption PowerConsumption() const;
328 IMPORT_C void SetTimeToFirstFix(TTimeIntervalMicroSeconds aTimeToFirstFix);
329 IMPORT_C void SetTimeToNextFix(TTimeIntervalMicroSeconds aTimeToNextFix);
331 IMPORT_C void SetHorizontalAccuracy(TReal32 aHorizontalAccuracy);
332 IMPORT_C void SetVerticalAccuracy(TReal32 aVerticalAccuracy);
334 IMPORT_C void SetCostIndicator(TCostIndicator aCost);
335 IMPORT_C void SetPowerConsumption(TPowerConsumption aPower);
338 /** Unused variable for future expansion. */
339 TUint8 iReserved[16];
343 class TPositionModuleInfoBase : public TPositionClassTypeBase
345 The base class for classes storing information on position modules
352 IMPORT_C TPositionModuleInfoBase();
355 class TPositionModuleInfo : public TPositionModuleInfoBase
357 The standard class for storing information on position modules
367 typedef TUint32 TTechnologyType;
372 enum _TTechnologyType
374 /** Indicates that the positioning module is unaware of the technology
375 used to obtain position information */
376 ETechnologyUnknown = 0,
377 /** The primary positioning technology is handset based.
378 For example standard GPS */
379 ETechnologyTerminal = 0x01,
380 /** The primary positioning technology is network based.
381 For example, E-OTD */
382 ETechnologyNetwork = 0x02,
383 /** The primary positioning mechanism receives assistance in some form.
384 Generally to obtain a quicker or more accurate fix */
385 ETechnologyAssisted = 0x04
391 typedef TUint32 TDeviceLocation;
396 enum _TDeviceLocation
398 /** The positioning module is unaware of the hardware used to supply
399 positioning information */
401 /** The positioning hardware is integral to the terminal */
402 EDeviceInternal = 0x01,
403 /** The positioning hardware is separate from the terminal */
404 EDeviceExternal = 0x02
408 Position module capabilities
410 typedef TUint32 TCapabilities;
417 /** No Capabilities */
420 /** Positioning modules with this capability will support the
421 TPositionInfo class and are able to provide latitude and longitude
424 ECapabilityHorizontal = 0x0001,
426 /** Positioning modules with this capability will support the
427 TPositionInfo class and are able to provide height related information
429 ECapabilityVertical = 0x0002,
431 /** Positioning modules with this capability will support the
432 TPositionCourseInfo class and are able to provide information related
433 to the current horizontal speed
435 ECapabilitySpeed = 0x0004,
437 /** Positioning modules with this capability will support the
438 TPositionCourseInfo class and are able to provide heading related information
440 ECapabilityDirection = 0x0008,
442 /** Positioning modules with this capability will support the
443 TPositionSatelliteInfo class. Such a module will be able to return at
444 least some satellite data - but the extent of the information could vary.
445 Applications must ensure that any value returned is valid before it is used
447 ECapabilitySatellite = 0x0010,
449 /** This value is reserved for future expansion.
450 Positioning modules with this capability will be able to return
451 information related to a magnetic compass. The API does not currently
452 define an extended class that encapsulates this type of information
454 ECapabilityCompass = 0x0020,
456 /** This value is reserved for future expansion.
457 Positioning modules with this capability will be able to return
458 location information using NMEA formatted text strings.
459 The API does not currently define an extended class that encapsulates
460 this type of information
462 ECapabilityNmea = 0x0040,
464 /** This value is reserved for future expansion.
465 Positioning modules with this capability will be able to return
466 information related to the postal address of the current location
468 ECapabilityAddress = 0x0080,
470 /** This value is reserved for future expansion.
471 Positioning modules with this capability will be able to return the
472 current position in terms of where within a building it is. For
473 example, this may include the floor and the room name.
474 The API does not currently define an extended class that encapsulates
475 this type of information
477 ECapabilityBuilding = 0x0100,
479 /** This value is reserved for future expansion.
480 Positioning modules with this capability will be able to return provide
481 a link to further information about the location. The standard mechanism
483 The API does not currently define an extended class that encapsulates
484 this type of information
486 ECapabilityMedia = 0x0200
490 IMPORT_C TPositionModuleInfo();
492 IMPORT_C TPositionModuleId ModuleId() const;
493 IMPORT_C TBool IsAvailable() const;
494 IMPORT_C void GetModuleName(TDes& aModuleName) const;
495 IMPORT_C void GetPositionQuality(TPositionQuality& aPosQuality) const;
496 IMPORT_C TTechnologyType TechnologyType() const;
497 IMPORT_C TDeviceLocation DeviceLocation() const;
498 IMPORT_C TCapabilities Capabilities() const ;
499 IMPORT_C TUint32 ClassesSupported(TPositionClassFamily aClassType) const;
500 IMPORT_C TVersion Version() const;
502 IMPORT_C void SetModuleId(TPositionModuleId aModuleId);
503 IMPORT_C void SetIsAvailable(TBool aIsAvailable);
504 IMPORT_C void SetModuleName(const TDesC& aModuleName);
505 IMPORT_C void SetPositionQuality(const TPositionQuality& aPosQuality);
506 IMPORT_C void SetTechnologyType(TTechnologyType aTechnologyType);
507 IMPORT_C void SetDeviceLocation(TDeviceLocation aDeviceLocation);
508 IMPORT_C void SetCapabilities(TCapabilities aDeviceCapabilities);
509 IMPORT_C void SetClassesSupported(TPositionClassFamily aClassType,
510 TUint32 aSupportedClasses);
511 IMPORT_C void SetVersion(TVersion aVersion);
515 TPositionModuleId iModuleId;
516 /** Whether or not the module is available */
518 /** The module name */
519 TBuf<KPositionMaxModuleName> iModuleName;
520 /** The position quality */
521 TPositionQuality iPosQuality;
522 /** The technology type */
523 TTechnologyType iTechnologyType;
524 /** The location of the device associated with this module */
525 TDeviceLocation iDeviceLocation;
526 /** The capabilities of this module */
527 TCapabilities iCapabilities;
528 /** The array of supported classes for the different class types */
529 TFixedArray<TUint32, EPositionLastFamily> iSupportedClassTypes;
530 /** The version of this module */
534 /** Unused variable for future expansion. */
535 TUint8 iReserved[16];
539 class TPositionModuleStatusBase : public TPositionClassTypeBase
541 The base class for classes storing a position module's status
548 IMPORT_C TPositionModuleStatusBase();
551 class TPositionModuleStatus : public TPositionModuleStatusBase
553 The normal class for storing a position module's status
560 /** defined type for TDeviceStatus */
561 typedef TInt TDeviceStatus;
569 This is not a valid state and should never be reported */
573 There are problems using the device. For example, there may be
574 hardware errors. It should not be confused with complete loss of data
575 quality which indicates that the device is functioning correctly but
576 is currently unable to obtain position information.
577 The error state will be reported if the device can not be successfully
578 brought on line. For example, the positioning module may have been unable
579 to communicate with the device or it is not responding as expected.
584 Although the device may be working properly, it has been taken off line
585 and is regarded as being unavailable to obtain position information.
586 This will generally have been done by the user via the control panel.
587 In this state, positioning framework will not use the device.
592 The device is not being used by the positioning framework. This is
593 typically because there are no clients currently obtaining the position
594 from it. This is the normal status that is returned for a module that
595 is not currently loaded by the system
599 /** Device initialising
600 This is a transient state. The device is being brought out of the
601 "inactive" state but has not reached either the "ready" or "stand by"
602 modes. The initialising state will occur when the positioning module
603 is first selected to provide a client application with location information
608 This state indicates the device has entered "sleep" or "power save"
609 mode. This signifies that the device is online, but is not actively
610 retrieving position information. A device will generally enter this mode
611 when the next position update is not required for some time and it is
612 more efficient to partially power down.
613 Note: Not all positioning modules will support this state - particularly
614 when there is external hardware
619 The positioning device is online and is ready to retrieve
625 The positioning device is actively in the process of retrieving
626 position information.
627 Note: Not all positioning modules will support this state - particularly
628 when there is external hardware
633 /** defined type for TDataQualityStatus */
634 typedef TInt TDataQualityStatus;
637 * The data quality status
639 enum _TDataQualityStatus
641 /** Data Quality Unknown
642 This is the unassigned valued. This state should only be reported
643 during an event indicating that a positioning module has been removed
644 or is not yet loaded.
648 /** Data Quality Loss
649 The accuracy and contents of the position information has been
650 completely compromised. It is no longer possible to return any
652 This situation will occur if the device has lost track of all the
653 transmitters (for example, satellites or base stations).
654 It should be noted although it is currently not possible to obtain
655 position information, the device may still be functioning correctly.
656 This state should not be confused with a device error.
660 /** Data Quality Partial
661 There has been a partial degradation in the available position
662 information. In particular, it is not possible to provide the required
663 (or expected) quality of information.
664 This situation could occur if the device has lost track of one of the
665 transmitters (for example, satellites or base stations)
669 /** Data Quality Normal
670 The positioning device is functioning as expected
675 IMPORT_C TPositionModuleStatus();
677 IMPORT_C TDeviceStatus DeviceStatus() const;
678 IMPORT_C TDataQualityStatus DataQualityStatus() const;
681 IMPORT_C void SetDeviceStatus(TDeviceStatus aStatus);
682 IMPORT_C void SetDataQualityStatus(TDataQualityStatus aStatus);
685 /** The device status */
686 TDeviceStatus iDeviceStatus;
687 /** The data quality status */
688 TDataQualityStatus iDataQualityStatus;
691 /** Unused variable for future expansion. */
696 class TPositionModuleStatusEventBase : public TPositionClassTypeBase
698 The base class for classes storing position module status events
705 /** defined type for TSystemModuleEvent */
706 typedef TUint32 TSystemModuleEvent;
711 enum _TSystemModuleEvent
714 This is not a valid state and should never be reported */
718 There are problems using the module. For example, the module may have
719 terminated abnormally. It should not be confused with the module
720 reporting the error EDeviceError via TPositionModuleStatus::DeviceStatus().
721 That signifies the module itself is up and running - but it may be
722 unable to successful communicate with the hardware
726 /** System Module Installed
727 A new positioning module has been dynamically added to the system. To
728 receive this event, the client application must have expressed interest
729 in status notifications from any positioning module. The Id of the newly
730 installed module can be found by calling TPositionModuleStatusEvent::ModuleId().
732 ESystemModuleInstalled,
734 /** System Module Removed
735 A positioning module is uninstalled. The Id of the removed module can
736 be found by calling TPositionModuleStatusEvent::ModuleId()
741 /** defined type for TModuleEvent */
742 typedef TUint32 TModuleEvent;
750 This is the unassigned value and should not be reported or used
754 /** Module event device status
755 Events about the general status of the device. When this type of event
756 occurs, client applications should inspect the value returned by the
757 TPositionModuleInfo::DeviceStatus() method for more information
759 EEventDeviceStatus = 0x01,
761 /** Module Data Quality status
762 Events about the quality of the data a module is able to return. When
763 this type of event occurs, client applications should inspect the
764 value returned by the TPositionModuleInfo::DataQualityStatus() method
765 for more information.
767 EEventDataQualityStatus = 0x02,
769 /** Module System Event
770 System level events about the status of modules. Events of this type
771 indicate when modules have been added or removed from the system. When
772 this event type occurs, client applications should inspect the value
773 returned by TPositionModuleInfo::SystemModuleEvent() to determine which
774 particular event was responsible
776 EEventSystemModuleEvent = 0x04,
779 EEventAll = EEventDeviceStatus |
780 EEventDataQualityStatus |
781 EEventSystemModuleEvent
785 IMPORT_C TPositionModuleStatusEventBase();
786 IMPORT_C TPositionModuleStatusEventBase(TModuleEvent aRequestedEventMask);
789 IMPORT_C void SetRequestedEvents(TModuleEvent aRequestedEventMask);
790 IMPORT_C TModuleEvent RequestedEvents() const;
792 IMPORT_C void SetOccurredEvents(TModuleEvent aOccurredEventMask);
793 IMPORT_C TModuleEvent OccurredEvents() const;
795 IMPORT_C TPositionModuleId ModuleId() const;
796 IMPORT_C void SetModuleId(TPositionModuleId aModuleId);
798 IMPORT_C void SetSystemModuleEvent(TSystemModuleEvent aSystemModuleEvent);
799 IMPORT_C TSystemModuleEvent SystemModuleEvent() const;
802 IMPORT_C virtual void DoReset(TInt aSizeOfClass);
805 friend class RPositionServer;
809 /** A bitmask of the requested events */
810 TModuleEvent iRequestedEvents;
811 /** A bitmask of the events which occurred */
812 TModuleEvent iOccurredEvents;
813 /** System level module status events*/
814 TSystemModuleEvent iSystemModuleEvent;
815 /** The module ID causing the event*/
816 TPositionModuleId iModuleId;
819 class TPositionModuleStatusEvent : public TPositionModuleStatusEventBase
821 The normal class for storing position module status events
828 IMPORT_C TPositionModuleStatusEvent();
829 IMPORT_C TPositionModuleStatusEvent(TModuleEvent aRequestedEventMask);
831 IMPORT_C void SetModuleStatus(const TPositionModuleStatus& aModuleStatus);
832 IMPORT_C void GetModuleStatus(TPositionModuleStatus& aModuleStatus) const;
835 IMPORT_C virtual void DoReset(TInt aSizeOfClass);
838 /** The module status */
839 TPositionModuleStatus iModuleStatus;
843 class TPositionUpdateOptionsBase : public TPositionClassTypeBase
845 The base class for classes storing position update options
852 IMPORT_C TPositionUpdateOptionsBase();
853 IMPORT_C TPositionUpdateOptionsBase(TTimeIntervalMicroSeconds aInterval,
854 TTimeIntervalMicroSeconds aTimeOut = TTimeIntervalMicroSeconds(0),
855 TTimeIntervalMicroSeconds aMaxAge = TTimeIntervalMicroSeconds(0));
858 IMPORT_C void SetUpdateInterval(TTimeIntervalMicroSeconds aInterval);
859 IMPORT_C void SetUpdateTimeOut(TTimeIntervalMicroSeconds aTimeOut);
860 IMPORT_C void SetMaxUpdateAge(TTimeIntervalMicroSeconds aMaxAge);
862 IMPORT_C TTimeIntervalMicroSeconds UpdateInterval() const;
863 IMPORT_C TTimeIntervalMicroSeconds UpdateTimeOut() const;
864 IMPORT_C TTimeIntervalMicroSeconds MaxUpdateAge() const;
867 /** The update interval */
868 TTimeIntervalMicroSeconds iUpdateInterval;
869 /** The update timeout */
870 TTimeIntervalMicroSeconds iUpdateTimeOut;
871 /** The maximum update age */
872 TTimeIntervalMicroSeconds iMaxUpdateAge;
875 /** Unused variable for future expansion. */
879 class TPositionUpdateOptions : public TPositionUpdateOptionsBase
881 The normal class for storing position update options
888 IMPORT_C TPositionUpdateOptions();
889 IMPORT_C TPositionUpdateOptions(TTimeIntervalMicroSeconds aInterval,
890 TTimeIntervalMicroSeconds aTimeOut = TTimeIntervalMicroSeconds(0),
891 TTimeIntervalMicroSeconds aMaxAge = TTimeIntervalMicroSeconds(0),
892 TBool aAcceptPartialUpdates = EFalse);
894 IMPORT_C void SetAcceptPartialUpdates(TBool aAcceptPartialUpdates);
895 IMPORT_C TBool AcceptPartialUpdates() const;
898 /** Whether partial updates are accepted */
899 TBool iAcceptPartialUpdates;
902 /** Unused variable for future expansion. */
903 TUint8 iReserved[16];
907 #endif //__LBSCOMMON_H__