williamr@2: // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@2: // 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
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef __LBSCOMMON_H__
williamr@2: #define __LBSCOMMON_H__
williamr@2: 
williamr@2: #include <e32std.h>
williamr@2: #include <e32math.h>
williamr@2: #include <lbsrequestor.h>
williamr@2: #include <lbsclasstypes.h>
williamr@2: #include <lbserrors.h>
williamr@2: #include <lbs/lbsvariant.h>
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: // A compile time assert macro. The aExpr parameter must evaluate to an
williamr@2: // integer value at compile time.
williamr@2: // eg. sizeof(TTime) == KSizeOfTInt64
williamr@2: // If aExpr is false, the compiler generates an error.
williamr@2: // If aExpr is true, the compilation continues, and use of this macro will not
williamr@2: // result in any extra object code.
williamr@2: */
williamr@2: #define POSITION_COMPILE_TIME_ASSERT(aExpr)   typedef char assert_type[aExpr ? 1 : -1]
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Maximum characters in module name.
williamr@2: If __S60_ is defined in lbsvariant.h the constant is 64 otherwise it is 20
williamr@2: */
williamr@2: const TInt KPositionMaxModuleName = __LBS_MAX_MODULE_NAME;
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Maximum size for TUInt
williamr@2: */
williamr@2: const TUint KPositionMaxSizeQualityItem = sizeof(TInt64);
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Maximum size for fields
williamr@2: */
williamr@2: const TUint KPositionMaxSectionFields = 10;
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines typedef for TPositionModuleId
williamr@2: */
williamr@2: typedef TUid  TPositionModuleId;
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines NULL TUid
williamr@2: */
williamr@2: const TPositionModuleId KPositionNullModuleId = {KNullUidValue};
williamr@2: 
williamr@2: 
williamr@2: class TPositionClassTypeBase
williamr@2: /**
williamr@2: The base class for classes used to store position information
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TUint32 PositionClassType() const;
williamr@2: 	IMPORT_C TUint PositionClassSize() const;
williamr@2: 
williamr@2: protected:
williamr@2: 	TPositionClassTypeBase();
williamr@2: 
williamr@2: protected:
williamr@2: 	/** The type of the derived class */
williamr@2: 	TUint32 iPosClassType;
williamr@2: 	/** The size of the derived class */
williamr@2: 	TUint iPosClassSize;
williamr@2: 	};
williamr@2: 
williamr@2: class TPositionQualityItem
williamr@2: /**
williamr@2: The class for classes used to store position quality
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Quality result */
williamr@2: 	enum TResult
williamr@2: 		{
williamr@2: 		/** Better */
williamr@2: 		EIsBetter,
williamr@2: 		/** Equal */
williamr@2: 		EIsEqual,
williamr@2: 		/** Worse */
williamr@2: 		EIsWorse
williamr@2: 		};
williamr@2: 
williamr@2: 	/** Preference */
williamr@2: 	enum TValuePreference
williamr@2: 		{
williamr@2: 		/** Smaller values */
williamr@2: 		EPreferSmallerValues,
williamr@2: 		/** Greater values */
williamr@2: 		EPreferGreaterValues
williamr@2: 		};
williamr@2: 
williamr@2: 	/** Size of data type
williamr@2: 	 */
williamr@2: 	enum TDataType
williamr@2: 		{
williamr@2: 		/** Undefined */
williamr@2: 		EUndefined,
williamr@2: 		/** TInt8 */
williamr@2: 		ETInt8,
williamr@2: 		/** TInt16 */
williamr@2: 		ETInt16,
williamr@2: 		/** TInt32 */
williamr@2: 		ETInt32,
williamr@2: 		/** Tint64 */
williamr@2: 		ETInt64,
williamr@2: 		/** TUint8 */
williamr@2: 		ETUint8,
williamr@2: 		/** TUint16 */
williamr@2: 		ETUint16,
williamr@2: 		/** TUint 32 */
williamr@2: 		ETUint32,
williamr@2: 		/** TReal32 */
williamr@2: 		ETReal32,
williamr@2: 		/** TReal64 */
williamr@2: 		ETReal64,
williamr@2: 		/** ETime */
williamr@2: 		ETTime,
williamr@2: 		/** Time in microseconds */
williamr@2: 		ETTimeIntervalMicroSeconds
williamr@2: 		};
williamr@2: 
williamr@2: 	TPositionQualityItem();
williamr@2: 
williamr@2: 	TInt Compare(const TPositionQualityItem& aItem, TResult& aComparison) const;
williamr@2: 
williamr@2: 	void Set(TDataType aDataType, TValuePreference aValuePreference,
williamr@2: 			 const TAny* aData, TUint aSizeOfData);
williamr@2: 
williamr@2: 	TInt Get(TDataType aDataType, TAny* aData, TUint aSizeOfData) const;
williamr@2: 
williamr@2: 	TBool IsDefined() const;
williamr@2: 
williamr@2: private:
williamr@2: 	/** Internal datatype */
williamr@2: 	TDataType iDataType;
williamr@2: 	/** Internel value preference */
williamr@2: 	TValuePreference iScaleDirection;
williamr@2: 	/** Unused variable for future expansion. */
williamr@2: 	TUint8 iData[KPositionMaxSizeQualityItem];
williamr@2: 	};
williamr@2: 
williamr@2: class TPositionQualityBase : public TPositionClassTypeBase
williamr@2: /**
williamr@2: The base class for classes used to store position quality information
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TInt Compare(const TPositionQualityBase& aPositionQuality,
williamr@2: 						  TInt aElementToCompare,
williamr@2: 						  TPositionQualityItem::TResult& aComparison) const;
williamr@2: 
williamr@2: 	/**
williamr@2:  	Returns whether an element is defined
williamr@2: 	@publishedAll
williamr@2: 	@released
williamr@2: 	@param aElementId The element Id of that we're interested in.
williamr@2: 	@return TBool if defined
williamr@2:  	*/
williamr@2: 	IMPORT_C TBool IsDefined(TInt aElementId) const;
williamr@2: 	IMPORT_C TInt HighWaterMark() const;
williamr@2: protected:
williamr@2: 	IMPORT_C TPositionQualityBase();
williamr@2: 
williamr@2: 	IMPORT_C void ResetElement(TInt aElementId);
williamr@2: 
williamr@2: 
williamr@2: 	/**
williamr@2: 	Sets the data of an element from the array of elements.
williamr@2: 	@publishedAll
williamr@2: 	@released
williamr@2: 	@param aElementId The element Id of that we're interested in.
williamr@2: 	@param aDataType The datatype of the data to be fetched.
williamr@2: 	@param aValuePreference Quality preferences
williamr@2: 	@param aData A pointer to the data to be written into.
williamr@2:  	*/
williamr@2: 	template <class T>
williamr@2: 		inline void SetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
williamr@2: 							   TPositionQualityItem::TValuePreference aValuePreference, T aData)
williamr@2: 		{DoSetElement(aElementId, aDataType, aValuePreference, &aData, sizeof(T));}
williamr@2: 
williamr@2: 	/**
williamr@2: 	Gets the data of an element from the array of elements.
williamr@2: 	@publishedAll
williamr@2: 	@released
williamr@2: 	@param aElementId The element Id of that we're interested in.
williamr@2: 	@param aDataType The datatype of the data to be fetched.
williamr@2: 	@param aData A pointer to the data to be written into.
williamr@2: 	@return Standard Symbian OS Error code
williamr@2:  	*/	
williamr@2: 	template <class T>
williamr@2: 		inline TInt GetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
williamr@2: 							    T& aData) const
williamr@2: 		{return DoGetElement(aElementId, aDataType, &aData, sizeof(T));}
williamr@2: 
williamr@2: private:
williamr@2: 	IMPORT_C void DoSetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
williamr@2: 							   TPositionQualityItem::TValuePreference aValuePreference,
williamr@2: 							   const TAny* aData, TUint aSizeOfData);
williamr@2: 
williamr@2: 	IMPORT_C TInt DoGetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,
williamr@2: 								TAny* aData, TUint aSizeOfData) const;
williamr@2: private:
williamr@2: 	/** Internal array */
williamr@2: 	TFixedArray<TPositionQualityItem, KPositionMaxSectionFields> iPositionQualityData;
williamr@2: 	/** Internal highwater mark */
williamr@2: 	TInt iHighwaterMark;
williamr@2: 	};
williamr@2: 
williamr@2: class TPositionQuality : public TPositionQualityBase
williamr@2: /**
williamr@2: The standard position quality class.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Cost Indicator for position request */
williamr@2: 	enum TCostIndicator
williamr@2: 		{
williamr@2: 		/** Unknown cost
williamr@2: 		This is the unassigned value and should not be returned */
williamr@2: 		ECostUnknown,
williamr@2: 
williamr@2: 		/** Zero cost
williamr@2: 		No cost is expected to be incurred when obtaining a position fix */
williamr@2: 		ECostZero,
williamr@2: 
williamr@2: 		/** Possible cost
williamr@2: 		The positioning module is uncertain if the user will incur a charge. */
williamr@2: 		ECostPossible,
williamr@2: 
williamr@2: 		/** Charged
williamr@2: 		The positioning module expects a charge to be levied when obtaining
williamr@2:  		position information */
williamr@2: 		ECostCharge
williamr@2: 		};
williamr@2: 
williamr@2: 	/** Power consumption */
williamr@2: 	enum TPowerConsumption
williamr@2: 		{
williamr@2: 		/** Unknown power consumption
williamr@2: 		The positioning module is unable to determine the likely power drain */
williamr@2: 		EPowerUnknown,
williamr@2: 
williamr@2: 		/** Zero power consumption
williamr@2: 		No internal power will be used when obtaining a position fix */
williamr@2: 		EPowerZero,
williamr@2: 
williamr@2: 		/** Low power consumption
williamr@2: 		The positioning module expects a minimum power drain when using the
williamr@2: 		associated technology. This may be comparable to the power usage when
williamr@2: 		the phone is in standby mode. */
williamr@2: 		EPowerLow,
williamr@2: 
williamr@2: 		/** Medium power consumption
williamr@2: 		The positioning module expects a moderate power drain when using the
williamr@2: 		associated technology. This may be comparable to the power usage when
williamr@2: 		the phone is being actively used */
williamr@2: 		EPowerMedium,
williamr@2: 
williamr@2: 		/** High power consumption
williamr@2: 		The positioning module expects a high power drain when using the
williamr@2: 		associated technology. Use of this module will quickly consume the phone's batteries */
williamr@2: 		EPowerHigh
williamr@2: 		};
williamr@2: 
williamr@2: public:
williamr@2: 	IMPORT_C TPositionQuality();
williamr@2: 
williamr@2: 	IMPORT_C TTimeIntervalMicroSeconds TimeToFirstFix() const;
williamr@2: 	IMPORT_C TTimeIntervalMicroSeconds TimeToNextFix()  const;  
williamr@2: 
williamr@2: 	IMPORT_C TReal32 HorizontalAccuracy() const;
williamr@2: 	IMPORT_C TReal32 VerticalAccuracy()   const;
williamr@2: 
williamr@2: 	IMPORT_C TCostIndicator CostIndicator() const;
williamr@2: 	IMPORT_C TPowerConsumption PowerConsumption() const;
williamr@2: 
williamr@2: 	IMPORT_C void SetTimeToFirstFix(TTimeIntervalMicroSeconds aTimeToFirstFix);
williamr@2: 	IMPORT_C void SetTimeToNextFix(TTimeIntervalMicroSeconds aTimeToNextFix);
williamr@2: 
williamr@2: 	IMPORT_C void SetHorizontalAccuracy(TReal32 aHorizontalAccuracy);
williamr@2: 	IMPORT_C void SetVerticalAccuracy(TReal32 aVerticalAccuracy);
williamr@2: 
williamr@2: 	IMPORT_C void SetCostIndicator(TCostIndicator aCost);
williamr@2: 	IMPORT_C void SetPowerConsumption(TPowerConsumption aPower);
williamr@2: 
williamr@2: private:
williamr@2: 	/** Unused variable for future expansion. */
williamr@2: 	TUint8 iReserved[16];
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class TPositionModuleInfoBase : public TPositionClassTypeBase
williamr@2: /**
williamr@2: The base class for classes storing information on position modules
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: protected:
williamr@2: 	IMPORT_C TPositionModuleInfoBase();
williamr@2: 	};
williamr@2: 
williamr@2: class TPositionModuleInfo : public TPositionModuleInfoBase
williamr@2: /**
williamr@2: The standard class for storing information on position modules
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@2: 	 Technology types
williamr@2: 	 */
williamr@2: 	typedef TUint32 TTechnologyType;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Technology Type
williamr@2: 	 */ 
williamr@2: 	enum _TTechnologyType
williamr@2: 		{
williamr@2: 		/** Indicates that the positioning module is unaware of the technology
williamr@2: 		used to obtain position information */
williamr@2: 		ETechnologyUnknown	= 0,
williamr@2: 		/** The primary positioning technology is handset based.
williamr@2: 		For example standard GPS */
williamr@2: 		ETechnologyTerminal	= 0x01,
williamr@2: 		/** The primary positioning technology is network based.
williamr@2: 		For example, E-OTD */
williamr@2: 		ETechnologyNetwork	= 0x02,
williamr@2: 		/** The primary positioning mechanism receives assistance in some form.
williamr@2: 		Generally to obtain a quicker or more accurate fix */
williamr@2: 		ETechnologyAssisted	= 0x04
williamr@2: 		};
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Device locations
williamr@2: 	 */
williamr@2: 	typedef TUint32 TDeviceLocation;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Device location
williamr@2: 	 */ 
williamr@2: 	enum _TDeviceLocation
williamr@2: 		{
williamr@2: 		/** The positioning module is unaware of the hardware used to supply
williamr@2: 		positioning information */
williamr@2: 		EDeviceUnknown	= 0,
williamr@2: 		/** The positioning hardware is integral to the terminal */
williamr@2: 		EDeviceInternal	= 0x01,
williamr@2: 		/** The positioning hardware is separate from the terminal */
williamr@2: 		EDeviceExternal	= 0x02
williamr@2: 		};
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Position module capabilities
williamr@2: 	 */
williamr@2: 	typedef TUint32 TCapabilities;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Module Capabilities
williamr@2: 	 */ 
williamr@2: 	enum _TCapabilities
williamr@2: 		{
williamr@2: 		/** No Capabilities */
williamr@2: 		ECapabilityNone	       = 0,
williamr@2: 
williamr@2: 		/** Positioning modules with this capability will support the
williamr@2: 		TPositionInfo class and are able to provide latitude and longitude
williamr@2: 		related information
williamr@2: 		 */
williamr@2: 		ECapabilityHorizontal  = 0x0001,
williamr@2: 
williamr@2: 		/** Positioning modules with this capability will support the
williamr@2: 	 	TPositionInfo class and are able to provide height related information
williamr@2: 		 */
williamr@2: 		ECapabilityVertical    = 0x0002,
williamr@2: 
williamr@2: 		/** Positioning modules with this capability will support the
williamr@2: 		TPositionCourseInfo class and are able to provide information related
williamr@2: 		to the current horizontal speed
williamr@2: 		 */
williamr@2: 		ECapabilitySpeed       = 0x0004,
williamr@2: 
williamr@2: 		/** Positioning modules with this capability will support the
williamr@2: 		TPositionCourseInfo class and are able to provide heading related information
williamr@2: 		 */
williamr@2: 		ECapabilityDirection   = 0x0008,
williamr@2: 
williamr@2: 		/** Positioning modules with this capability will support the
williamr@2: 		TPositionSatelliteInfo class. Such a module will be able to return at
williamr@2: 		least some satellite data - but the extent of the information could vary.
williamr@2: 		Applications must ensure that any value returned is valid before it is used 
williamr@2: 		*/
williamr@2: 		ECapabilitySatellite   = 0x0010,
williamr@2: 
williamr@2: 		/** This value is reserved for future expansion.
williamr@2: 		Positioning modules with this capability will be able to return
williamr@2: 		information related to a magnetic compass. The API does not currently
williamr@2: 		define an extended class that encapsulates this type of information
williamr@2:  		*/
williamr@2: 		ECapabilityCompass     = 0x0020,
williamr@2: 
williamr@2: 		/** This value is reserved for future expansion.
williamr@2: 		Positioning modules with this capability will be able to return
williamr@2: 		location information using NMEA formatted text strings.
williamr@2: 		The API does not currently define an extended class that encapsulates
williamr@2: 		this type of information
williamr@2:  		*/
williamr@2: 		ECapabilityNmea        = 0x0040,
williamr@2: 
williamr@2: 		/** This value is reserved for future expansion.
williamr@2: 		Positioning modules with this capability will be able to return
williamr@2: 		information related to the postal address of the current location
williamr@2: 		 */
williamr@2: 		ECapabilityAddress     = 0x0080,
williamr@2: 
williamr@2: 		/** This value is reserved for future expansion.
williamr@2: 		Positioning modules with this capability will be able to return the
williamr@2: 		current position in terms of where within a building it is. For
williamr@2: 		example, this may include the floor and the room name.	
williamr@2: 		The API does not currently define an extended class that encapsulates
williamr@2: 		this type of information
williamr@2: 		 */
williamr@2: 		ECapabilityBuilding    = 0x0100,
williamr@2: 
williamr@2: 		/** This value is reserved for future expansion.
williamr@2: 		Positioning modules with this capability will be able to return provide
williamr@2: 		a link to further information about the location. The standard mechanism
williamr@2: 		is via a URL.
williamr@2: 		The API does not currently define an extended class that encapsulates
williamr@2: 		this type of information
williamr@2:  		*/
williamr@2: 		ECapabilityMedia       = 0x0200
williamr@2: 		};
williamr@2: 
williamr@2: public:
williamr@2: 	IMPORT_C TPositionModuleInfo();
williamr@2: 
williamr@2: 	IMPORT_C TPositionModuleId ModuleId() const;
williamr@2: 	IMPORT_C TBool IsAvailable() const;
williamr@2: 	IMPORT_C void GetModuleName(TDes& aModuleName) const;
williamr@2: 	IMPORT_C void GetPositionQuality(TPositionQuality& aPosQuality) const;
williamr@2: 	IMPORT_C TTechnologyType TechnologyType() const;
williamr@2: 	IMPORT_C TDeviceLocation DeviceLocation() const;
williamr@2: 	IMPORT_C TCapabilities Capabilities() const ;
williamr@2: 	IMPORT_C TUint32 ClassesSupported(TPositionClassFamily aClassType) const;
williamr@2: 	IMPORT_C TVersion Version() const;
williamr@2: 
williamr@2: 	IMPORT_C void SetModuleId(TPositionModuleId aModuleId);
williamr@2: 	IMPORT_C void SetIsAvailable(TBool aIsAvailable);
williamr@2: 	IMPORT_C void SetModuleName(const TDesC& aModuleName);
williamr@2: 	IMPORT_C void SetPositionQuality(const TPositionQuality& aPosQuality);
williamr@2: 	IMPORT_C void SetTechnologyType(TTechnologyType aTechnologyType);
williamr@2: 	IMPORT_C void SetDeviceLocation(TDeviceLocation aDeviceLocation);
williamr@2: 	IMPORT_C void SetCapabilities(TCapabilities aDeviceCapabilities);
williamr@2: 	IMPORT_C void SetClassesSupported(TPositionClassFamily aClassType,
williamr@2: 									  TUint32 aSupportedClasses);
williamr@2: 	IMPORT_C void SetVersion(TVersion aVersion);
williamr@2: 
williamr@2: protected:
williamr@2: 	/** The module ID */
williamr@2: 	TPositionModuleId	iModuleId;
williamr@2: 	/** Whether or not the module is available */
williamr@2: 	TBool iIsAvailable;
williamr@2: 	/** The module name */
williamr@2: 	TBuf<KPositionMaxModuleName> iModuleName;
williamr@2: 	/** The position quality */
williamr@2: 	TPositionQuality    iPosQuality;
williamr@2: 	/** The technology type */
williamr@2: 	TTechnologyType     iTechnologyType;
williamr@2: 	/** The location of the device associated with this module */
williamr@2: 	TDeviceLocation     iDeviceLocation;
williamr@2: 	/** The capabilities of this module */
williamr@2: 	TCapabilities		iCapabilities;
williamr@2: 	/** The array of supported classes for the different class types */
williamr@2: 	TFixedArray<TUint32, EPositionLastFamily> iSupportedClassTypes;
williamr@2: 	/** The version of this module */
williamr@2: 	TVersion            iVersion;
williamr@2: 
williamr@2: private:
williamr@2: 	/** Unused variable for future expansion. */
williamr@2: 	TUint8 iReserved[16];
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class TPositionModuleStatusBase : public TPositionClassTypeBase
williamr@2: /**
williamr@2: The base class for classes storing a position module's status
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: protected:
williamr@2: 	IMPORT_C TPositionModuleStatusBase();
williamr@2: 	};
williamr@2: 
williamr@2: class TPositionModuleStatus : public TPositionModuleStatusBase
williamr@2: /**
williamr@2: The normal class for storing a position module's status
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** defined type for TDeviceStatus */
williamr@2: 	typedef TInt TDeviceStatus;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * The device status
williamr@2: 	 */
williamr@2: 	enum _TDeviceStatus 
williamr@2: 		{
williamr@2: 		/** Device unknown
williamr@2: 		This is not a valid state and should never be reported */
williamr@2: 		EDeviceUnknown,
williamr@2: 
williamr@2: 		/** Device error
williamr@2: 		There are problems using the device. For example, there may be
williamr@2: 		hardware errors. It should not be confused with complete loss of data
williamr@2: 		quality which indicates that the device is functioning correctly but
williamr@2: 		is currently unable to obtain position information.
williamr@2: 		The error state will be reported if the device can not be successfully
williamr@2: 		brought on line. For example, the positioning module may have been unable
williamr@2: 		to communicate with the device or it is not responding as expected.
williamr@2:  		*/
williamr@2: 		EDeviceError,
williamr@2: 
williamr@2: 		/** Device disabled
williamr@2: 		Although the device may be working properly, it has been taken off line
williamr@2: 		and is regarded as being unavailable to obtain position information.
williamr@2: 		This will generally have been done by the user via the control panel.
williamr@2: 		In this state, positioning framework will not use the device.
williamr@2: 		 */
williamr@2: 		EDeviceDisabled,
williamr@2: 
williamr@2: 		/** Device inactive
williamr@2: 		The device is not being used by the positioning framework. This is
williamr@2: 		typically because there are no clients currently obtaining the position
williamr@2: 		from it. This is the normal status that is returned for a module that
williamr@2: 		is not currently loaded by the system
williamr@2: 	 	*/
williamr@2: 		EDeviceInactive,
williamr@2: 
williamr@2: 		/** Device initialising
williamr@2: 		This is a transient state. The device is being brought out of the
williamr@2: 		"inactive" state but has not 	reached either the "ready" or "stand by"
williamr@2: 		modes. The initialising state will occur when the positioning module
williamr@2: 		is first selected to provide a client application with location information	
williamr@2: 		 */
williamr@2: 		EDeviceInitialising,
williamr@2: 
williamr@2: 		/** Device standby
williamr@2: 		This state indicates the device has entered "sleep" or "power save"
williamr@2: 		mode. This signifies that the device is online, but is not actively
williamr@2: 		retrieving position information. A device will generally enter this mode
williamr@2: 		when the next position update is not required for some time and it is
williamr@2: 		more 	efficient to partially power down.
williamr@2: 		Note: Not all positioning modules will support this state - particularly
williamr@2: 		when there is external hardware
williamr@2: 		 */
williamr@2: 		EDeviceStandBy,
williamr@2: 
williamr@2: 		/** Device ready
williamr@2: 		The positioning device is online and is ready to retrieve
williamr@2: 		position information
williamr@2: 		 */
williamr@2: 		EDeviceReady,
williamr@2: 
williamr@2: 		/** Device active
williamr@2: 		The positioning device is actively in the process of retrieving
williamr@2: 		position information.
williamr@2: 		Note: Not all positioning modules will support this state - particularly
williamr@2: 		when there is external hardware
williamr@2: 		 */
williamr@2: 		EDeviceActive
williamr@2: 		};
williamr@2: 
williamr@2: 	/** defined type for TDataQualityStatus */
williamr@2: 	typedef TInt TDataQualityStatus;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * The data quality status
williamr@2: 	 */
williamr@2: 	enum _TDataQualityStatus
williamr@2: 		{
williamr@2: 		/** Data Quality Unknown
williamr@2: 		This is the unassigned valued. This state should only be reported
williamr@2: 		during an event indicating that a positioning module has been removed
williamr@2:  		*/
williamr@2: 		EDataQualityUnknown,
williamr@2: 
williamr@2: 		/** Data Quality Loss
williamr@2: 		The accuracy and contents of the position information has been
williamr@2: 		completely compromised. It is no longer possible to return any
williamr@2: 		coherent data.
williamr@2: 		This situation will occur if the device has lost track of all the
williamr@2: 		transmitters (for example, satellites or base stations).
williamr@2: 		It should be noted although it is currently not possible to obtain
williamr@2: 		position information, the device may still be functioning correctly.
williamr@2: 		This state should not be confused with a device error.
williamr@2:  		*/
williamr@2: 		EDataQualityLoss,
williamr@2: 
williamr@2: 		/** Data Quality Partial
williamr@2: 		There has been a partial degradation in the available position
williamr@2: 		information. In particular, it is not possible to provide the required
williamr@2: 		(or expected) quality of information.
williamr@2: 		This situation could occur if the device has lost track of one of the
williamr@2: 		transmitters (for example, satellites or base stations)
williamr@2: 		 */
williamr@2: 		EDataQualityPartial,
williamr@2: 
williamr@2: 		/** Data Quality Normal
williamr@2: 		The positioning device is functioning as expected
williamr@2:  		*/
williamr@2: 		EDataQualityNormal
williamr@2: 		};
williamr@2: 
williamr@2: 	IMPORT_C TPositionModuleStatus();
williamr@2: 
williamr@2: 	IMPORT_C TDeviceStatus DeviceStatus() const;
williamr@2: 	IMPORT_C TDataQualityStatus DataQualityStatus() const;
williamr@2: 
williamr@2: 
williamr@2: 	IMPORT_C void SetDeviceStatus(TDeviceStatus aStatus);
williamr@2: 	IMPORT_C void SetDataQualityStatus(TDataQualityStatus aStatus);
williamr@2: 	
williamr@2: protected:
williamr@2: 	/** The device status */
williamr@2: 	TDeviceStatus      iDeviceStatus;
williamr@2: 	/** The data quality status */
williamr@2: 	TDataQualityStatus iDataQualityStatus;
williamr@2: 
williamr@2: private:
williamr@2: 	/** Unused variable for future expansion. */
williamr@2: 	TUint8 iReserved[8];
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class TPositionModuleStatusEventBase : public TPositionClassTypeBase
williamr@2: /**
williamr@2: The base class for classes storing position module status events
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** defined type for TSystemModuleEvent */
williamr@2: 	typedef TUint32 TSystemModuleEvent;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Module events
williamr@2: 	 */
williamr@2: 	enum _TSystemModuleEvent
williamr@2: 		{
williamr@2: 		/** System Unknown
williamr@2: 		This is not a valid state and should never be reported */
williamr@2: 		ESystemUnknown				= 0,
williamr@2: 
williamr@2: 		/** System Error
williamr@2: 		There are problems using the module. For example, the module may have
williamr@2: 		terminated abnormally. It should not be confused with the module
williamr@2: 		reporting the error EDeviceError via TPositionModuleStatus::DeviceStatus().
williamr@2: 		That signifies the module itself is up and running - but it may be
williamr@2: 		unable to successful communicate with the hardware
williamr@2:  		*/
williamr@2: 		ESystemError,
williamr@2: 	
williamr@2: 		/** System Module Installed
williamr@2: 		A new positioning module has been dynamically added to the system. To
williamr@2: 		receive this event, the client application must have expressed interest
williamr@2: 		in status notifications from any positioning module. The Id of the newly
williamr@2: 		installed module can be found by calling TPositionModuleStatusEvent::ModuleId().
williamr@2: 		 */
williamr@2: 		ESystemModuleInstalled,
williamr@2: 
williamr@2: 		/** System Module Removed
williamr@2: 		A positioning module is uninstalled. The Id of the removed module can
williamr@2: 		be found by calling TPositionModuleStatusEvent::ModuleId()
williamr@2: 		 */
williamr@2: 		ESystemModuleRemoved
williamr@2: 		};
williamr@2: 
williamr@2: 	/** defined type for TModuleEvent */
williamr@2: 	typedef TUint32 TModuleEvent;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Module events
williamr@2: 	 */
williamr@2: 	enum _TModuleEvent
williamr@2: 		{
williamr@2: 		/** No module event
williamr@2: 		This is the unassigned value and should not be reported or used
williamr@2:  		*/
williamr@2: 		EEventNone				= 0,
williamr@2: 
williamr@2: 		/** Module event device status
williamr@2: 		Events about the general status of the device. When this type of event
williamr@2: 		occurs, client applications should inspect the value returned by the
williamr@2:  		TPositionModuleInfo::DeviceStatus() method for more information
williamr@2:  		*/
williamr@2: 		EEventDeviceStatus      = 0x01,
williamr@2: 		
williamr@2: 		/** Module Data Quality status
williamr@2: 		Events about the quality of the data a module is able to return. When
williamr@2: 		this type of event occurs, client applications should inspect the
williamr@2: 		value returned by the TPositionModuleInfo::DataQualityStatus() method
williamr@2: 		for more information.
williamr@2:  		*/
williamr@2: 		EEventDataQualityStatus = 0x02,
williamr@2: 
williamr@2: 		/** Module System Event
williamr@2: 		System level events about the status of modules. Events of this type
williamr@2: 		indicate when modules have been added or removed from the system. When
williamr@2: 		this event type occurs, client applications should inspect the value
williamr@2: 		returned by TPositionModuleInfo::SystemModuleEvent() to determine which
williamr@2: 		particular event was responsible
williamr@2:  		*/
williamr@2: 		EEventSystemModuleEvent = 0x04,
williamr@2: 
williamr@2: 		/** All events */
williamr@2: 		EEventAll				= EEventDeviceStatus |
williamr@2: 								  EEventDataQualityStatus |
williamr@2: 								  EEventSystemModuleEvent
williamr@2: 		};
williamr@2: 
williamr@2: protected:
williamr@2: 	IMPORT_C TPositionModuleStatusEventBase();
williamr@2: 	IMPORT_C TPositionModuleStatusEventBase(TModuleEvent aRequestedEventMask);
williamr@2: 
williamr@2: public:
williamr@2: 	IMPORT_C void SetRequestedEvents(TModuleEvent aRequestedEventMask);
williamr@2: 	IMPORT_C TModuleEvent RequestedEvents() const;
williamr@2: 
williamr@2: 	IMPORT_C void SetOccurredEvents(TModuleEvent aOccurredEventMask);
williamr@2: 	IMPORT_C TModuleEvent OccurredEvents() const;
williamr@2: 
williamr@2: 	IMPORT_C TPositionModuleId ModuleId() const;
williamr@2: 	IMPORT_C void SetModuleId(TPositionModuleId aModuleId);
williamr@2: 
williamr@2: 	IMPORT_C void SetSystemModuleEvent(TSystemModuleEvent aSystemModuleEvent);
williamr@2: 	IMPORT_C TSystemModuleEvent SystemModuleEvent() const;
williamr@2: 
williamr@2: protected:
williamr@2: 	IMPORT_C virtual void DoReset(TInt aSizeOfClass);
williamr@2: 
williamr@2: private:
williamr@2: 	friend class RPositionServer;
williamr@2: 	void Reset();
williamr@2: 
williamr@2: protected:
williamr@2: 	/** A bitmask of the requested events */
williamr@2: 	TModuleEvent iRequestedEvents;
williamr@2: 	/** A bitmask of the events which occurred */
williamr@2: 	TModuleEvent iOccurredEvents;
williamr@2: 	/** System level module status events*/
williamr@2: 	TSystemModuleEvent iSystemModuleEvent;
williamr@2: 	/** The module ID causing the event*/
williamr@2: 	TPositionModuleId  iModuleId;
williamr@2: 	};
williamr@2: 
williamr@2: class TPositionModuleStatusEvent : public TPositionModuleStatusEventBase
williamr@2: /**
williamr@2: The normal class for storing position module status events
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TPositionModuleStatusEvent();
williamr@2: 	IMPORT_C TPositionModuleStatusEvent(TModuleEvent aRequestedEventMask);
williamr@2: 
williamr@2: 	IMPORT_C void SetModuleStatus(const TPositionModuleStatus& aModuleStatus);
williamr@2: 	IMPORT_C void GetModuleStatus(TPositionModuleStatus& aModuleStatus) const;
williamr@2: 
williamr@2: protected:
williamr@2: 	IMPORT_C virtual void DoReset(TInt aSizeOfClass);
williamr@2: 
williamr@2: protected:
williamr@2: 	/** The module status */
williamr@2: 	TPositionModuleStatus iModuleStatus;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class TPositionUpdateOptionsBase : public TPositionClassTypeBase
williamr@2: /**
williamr@2: The base class for classes storing position update options
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: protected:
williamr@2: 	IMPORT_C TPositionUpdateOptionsBase();
williamr@2: 	IMPORT_C TPositionUpdateOptionsBase(TTimeIntervalMicroSeconds aInterval,
williamr@2: 	                                    TTimeIntervalMicroSeconds aTimeOut = TTimeIntervalMicroSeconds(0),
williamr@2: 	                                    TTimeIntervalMicroSeconds aMaxAge = TTimeIntervalMicroSeconds(0));
williamr@2: 
williamr@2: public:
williamr@2: 	IMPORT_C void SetUpdateInterval(TTimeIntervalMicroSeconds aInterval);
williamr@2: 	IMPORT_C void SetUpdateTimeOut(TTimeIntervalMicroSeconds aTimeOut);
williamr@2: 	IMPORT_C void SetMaxUpdateAge(TTimeIntervalMicroSeconds aMaxAge);
williamr@2: 
williamr@2: 	IMPORT_C TTimeIntervalMicroSeconds UpdateInterval() const;
williamr@2: 	IMPORT_C TTimeIntervalMicroSeconds UpdateTimeOut() const;
williamr@2: 	IMPORT_C TTimeIntervalMicroSeconds MaxUpdateAge() const;
williamr@2: 
williamr@2: protected:
williamr@2: 	/** The update interval */
williamr@2: 	TTimeIntervalMicroSeconds iUpdateInterval;
williamr@2: 	/** The update timeout */
williamr@2: 	TTimeIntervalMicroSeconds iUpdateTimeOut;
williamr@2: 	/** The maximum update age */
williamr@2: 	TTimeIntervalMicroSeconds iMaxUpdateAge;
williamr@2: 
williamr@2: private:
williamr@2: 	/** Unused variable for future expansion. */
williamr@2: 	TUint8 iReserved[8];
williamr@2: 	};
williamr@2: 
williamr@2: class TPositionUpdateOptions : public TPositionUpdateOptionsBase
williamr@2: /**
williamr@2: The normal class for storing position update options
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TPositionUpdateOptions();
williamr@2: 	IMPORT_C TPositionUpdateOptions(TTimeIntervalMicroSeconds aInterval,
williamr@2: 	                                TTimeIntervalMicroSeconds aTimeOut = TTimeIntervalMicroSeconds(0),
williamr@2: 	                                TTimeIntervalMicroSeconds aMaxAge = TTimeIntervalMicroSeconds(0),
williamr@2: 	                                TBool aAcceptPartialUpdates = EFalse);
williamr@2: 
williamr@2: 	IMPORT_C void SetAcceptPartialUpdates(TBool aAcceptPartialUpdates);
williamr@2: 	IMPORT_C TBool AcceptPartialUpdates() const;
williamr@2: 
williamr@2: protected:
williamr@2: 	/** Whether partial updates are accepted */
williamr@2: 	TBool iAcceptPartialUpdates;
williamr@2: 
williamr@2: private:
williamr@2: 	/** Unused variable for future expansion. */
williamr@2: 	TUint8 iReserved[16];
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: #endif //__LBSCOMMON_H__