// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// 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

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __LBSCOMMON_H__

#define __LBSCOMMON_H__

#include <e32std.h>

#include <e32math.h>

#include <lbsrequestor.h>

#include <lbsclasstypes.h>

#include <lbserrors.h>

#include <lbs/lbsvariant.h>

/** 

@publishedAll

@released

// A compile time assert macro. The aExpr parameter must evaluate to an

// integer value at compile time.

// eg. sizeof(TTime) == KSizeOfTInt64

// If aExpr is false, the compiler generates an error.

// If aExpr is true, the compilation continues, and use of this macro will not

// result in any extra object code.

*/

#define POSITION_COMPILE_TIME_ASSERT(aExpr)   typedef char assert_type[aExpr ? 1 : -1]

/** 

@publishedAll

@released

Maximum characters in module name.

If __S60_ is defined in lbsvariant.h the constant is 64 otherwise it is 20

*/

const TInt KPositionMaxModuleName = __LBS_MAX_MODULE_NAME;

/** 

@publishedAll

@released

Maximum size for TUInt

*/

const TUint KPositionMaxSizeQualityItem = sizeof(TInt64);

/** 

@publishedAll

@released

Maximum size for fields

*/

const TUint KPositionMaxSectionFields = 10;

/** 

@publishedAll

@released

Defines typedef for TPositionModuleId

*/

typedef TUid  TPositionModuleId;

/** 

@publishedAll

@released

Defines NULL TUid

*/

const TPositionModuleId KPositionNullModuleId = {KNullUidValue};

class TPositionClassTypeBase

/**

The base class for classes used to store position information

@publishedAll

@released

 */

	{

public:

	IMPORT_C TUint32 PositionClassType() const;

	IMPORT_C TUint PositionClassSize() const;

protected:

	TPositionClassTypeBase();

protected:

	/** The type of the derived class */

	TUint32 iPosClassType;

	/** The size of the derived class */

	TUint iPosClassSize;

	};

class TPositionQualityItem

/**

The class for classes used to store position quality

@publishedAll

@released

 */

	{

public:

	/** Quality result */

	enum TResult

		{

		/** Better */

		EIsBetter,

		/** Equal */

		EIsEqual,

		/** Worse */

		EIsWorse

		};

	/** Preference */

	enum TValuePreference

		{

		/** Smaller values */

		EPreferSmallerValues,

		/** Greater values */

		EPreferGreaterValues

		};

	/** Size of data type

	 */

	enum TDataType

		{

		/** Undefined */

		EUndefined,

		/** TInt8 */

		ETInt8,

		/** TInt16 */

		ETInt16,

		/** TInt32 */

		ETInt32,

		/** Tint64 */

		ETInt64,

		/** TUint8 */

		ETUint8,

		/** TUint16 */

		ETUint16,

		/** TUint 32 */

		ETUint32,

		/** TReal32 */

		ETReal32,

		/** TReal64 */

		ETReal64,

		/** ETime */

		ETTime,

		/** Time in microseconds */

		ETTimeIntervalMicroSeconds

		};

	TPositionQualityItem();

	TInt Compare(const TPositionQualityItem& aItem, TResult& aComparison) const;

	void Set(TDataType aDataType, TValuePreference aValuePreference,

			 const TAny* aData, TUint aSizeOfData);

	TInt Get(TDataType aDataType, TAny* aData, TUint aSizeOfData) const;

	TBool IsDefined() const;

private:

	/** Internal datatype */

	TDataType iDataType;

	/** Internel value preference */

	TValuePreference iScaleDirection;

	/** Unused variable for future expansion. */

	TUint8 iData[KPositionMaxSizeQualityItem];

	};

class TPositionQualityBase : public TPositionClassTypeBase

/**

The base class for classes used to store position quality information

@publishedAll

@released

 */

	{

public:

	IMPORT_C TInt Compare(const TPositionQualityBase& aPositionQuality,

						  TInt aElementToCompare,

						  TPositionQualityItem::TResult& aComparison) const;

	/**

 	Returns whether an element is defined

	@publishedAll

	@released

	@param aElementId The element Id of that we're interested in.

	@return TBool if defined

 	*/

	IMPORT_C TBool IsDefined(TInt aElementId) const;

	IMPORT_C TInt HighWaterMark() const;

protected:

	IMPORT_C TPositionQualityBase();

	IMPORT_C void ResetElement(TInt aElementId);

	/**

	Sets the data of an element from the array of elements.

	@publishedAll

	@released

	@param aElementId The element Id of that we're interested in.

	@param aDataType The datatype of the data to be fetched.

	@param aValuePreference Quality preferences

	@param aData A pointer to the data to be written into.

 	*/

	template <class T>

		inline void SetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,

							   TPositionQualityItem::TValuePreference aValuePreference, T aData)

		{DoSetElement(aElementId, aDataType, aValuePreference, &aData, sizeof(T));}

	/**

	Gets the data of an element from the array of elements.

	@publishedAll

	@released

	@param aElementId The element Id of that we're interested in.

	@param aDataType The datatype of the data to be fetched.

	@param aData A pointer to the data to be written into.

	@return Standard Symbian OS Error code

 	*/	

	template <class T>

		inline TInt GetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,

							    T& aData) const

		{return DoGetElement(aElementId, aDataType, &aData, sizeof(T));}

private:

	IMPORT_C void DoSetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,

							   TPositionQualityItem::TValuePreference aValuePreference,

							   const TAny* aData, TUint aSizeOfData);

	IMPORT_C TInt DoGetElement(TInt aElementId, TPositionQualityItem::TDataType aDataType,

								TAny* aData, TUint aSizeOfData) const;

private:

	/** Internal array */

	TFixedArray<TPositionQualityItem, KPositionMaxSectionFields> iPositionQualityData;

	/** Internal highwater mark */

	TInt iHighwaterMark;

	};

class TPositionQuality : public TPositionQualityBase

/**

The standard position quality class.

@publishedAll

@released

 */

	{

public:

	/** Cost Indicator for position request */

	enum TCostIndicator

		{

		/** Unknown cost

		This is the unassigned value and should not be returned */

		ECostUnknown,

		/** Zero cost

		No cost is expected to be incurred when obtaining a position fix */

		ECostZero,

		/** Possible cost

		The positioning module is uncertain if the user will incur a charge. */

		ECostPossible,

		/** Charged

		The positioning module expects a charge to be levied when obtaining

 		position information */

		ECostCharge

		};

	/** Power consumption */

	enum TPowerConsumption

		{

		/** Unknown power consumption

		The positioning module is unable to determine the likely power drain */

		EPowerUnknown,

		/** Zero power consumption

		No internal power will be used when obtaining a position fix */

		EPowerZero,

		/** Low power consumption

		The positioning module expects a minimum power drain when using the

		associated technology. This may be comparable to the power usage when

		the phone is in standby mode. */

		EPowerLow,

		/** Medium power consumption

		The positioning module expects a moderate power drain when using the

		associated technology. This may be comparable to the power usage when

		the phone is being actively used */

		EPowerMedium,

		/** High power consumption

		The positioning module expects a high power drain when using the

		associated technology. Use of this module will quickly consume the phone's batteries */

		EPowerHigh

		};

public:

	IMPORT_C TPositionQuality();

	IMPORT_C TTimeIntervalMicroSeconds TimeToFirstFix() const;

	IMPORT_C TTimeIntervalMicroSeconds TimeToNextFix()  const;  

	IMPORT_C TReal32 HorizontalAccuracy() const;

	IMPORT_C TReal32 VerticalAccuracy()   const;

	IMPORT_C TCostIndicator CostIndicator() const;

	IMPORT_C TPowerConsumption PowerConsumption() const;

	IMPORT_C void SetTimeToFirstFix(TTimeIntervalMicroSeconds aTimeToFirstFix);

	IMPORT_C void SetTimeToNextFix(TTimeIntervalMicroSeconds aTimeToNextFix);

	IMPORT_C void SetHorizontalAccuracy(TReal32 aHorizontalAccuracy);

	IMPORT_C void SetVerticalAccuracy(TReal32 aVerticalAccuracy);

	IMPORT_C void SetCostIndicator(TCostIndicator aCost);

	IMPORT_C void SetPowerConsumption(TPowerConsumption aPower);

private:

	/** Unused variable for future expansion. */

	TUint8 iReserved[16];

	};

class TPositionModuleInfoBase : public TPositionClassTypeBase

/**

The base class for classes storing information on position modules

@publishedAll

@released

 */

	{

protected:

	IMPORT_C TPositionModuleInfoBase();

	};

class TPositionModuleInfo : public TPositionModuleInfoBase

/**

The standard class for storing information on position modules

@publishedAll

@released

 */

	{

public:

	/**

	 Technology types

	 */

	typedef TUint32 TTechnologyType;

	/**

	 Technology Type

	 */ 

	enum _TTechnologyType

		{

		/** Indicates that the positioning module is unaware of the technology

		used to obtain position information */

		ETechnologyUnknown	= 0,

		/** The primary positioning technology is handset based.

		For example standard GPS */

		ETechnologyTerminal	= 0x01,

		/** The primary positioning technology is network based.

		For example, E-OTD */

		ETechnologyNetwork	= 0x02,

		/** The primary positioning mechanism receives assistance in some form.

		Generally to obtain a quicker or more accurate fix */

		ETechnologyAssisted	= 0x04

		};

	/**

	 Device locations

	 */

	typedef TUint32 TDeviceLocation;

	/**

	 Device location

	 */ 

	enum _TDeviceLocation

		{

		/** The positioning module is unaware of the hardware used to supply

		positioning information */

		EDeviceUnknown	= 0,

		/** The positioning hardware is integral to the terminal */

		EDeviceInternal	= 0x01,

		/** The positioning hardware is separate from the terminal */

		EDeviceExternal	= 0x02

		};

	/**

	 Position module capabilities

	 */

	typedef TUint32 TCapabilities;

	/**

	 Module Capabilities

	 */ 

	enum _TCapabilities

		{

		/** No Capabilities */

		ECapabilityNone	       = 0,

		/** Positioning modules with this capability will support the

		TPositionInfo class and are able to provide latitude and longitude

		related information

		 */

		ECapabilityHorizontal  = 0x0001,

		/** Positioning modules with this capability will support the

	 	TPositionInfo class and are able to provide height related information

		 */

		ECapabilityVertical    = 0x0002,

		/** Positioning modules with this capability will support the

		TPositionCourseInfo class and are able to provide information related

		to the current horizontal speed

		 */

		ECapabilitySpeed       = 0x0004,

		/** Positioning modules with this capability will support the

		TPositionCourseInfo class and are able to provide heading related information

		 */

		ECapabilityDirection   = 0x0008,

		/** Positioning modules with this capability will support the

		TPositionSatelliteInfo class. Such a module will be able to return at

		least some satellite data - but the extent of the information could vary.

		Applications must ensure that any value returned is valid before it is used 

		*/

		ECapabilitySatellite   = 0x0010,

		/** This value is reserved for future expansion.

		Positioning modules with this capability will be able to return

		information related to a magnetic compass. The API does not currently

		define an extended class that encapsulates this type of information

 		*/

		ECapabilityCompass     = 0x0020,

		/** This value is reserved for future expansion.

		Positioning modules with this capability will be able to return

		location information using NMEA formatted text strings.

		The API does not currently define an extended class that encapsulates

		this type of information

 		*/

		ECapabilityNmea        = 0x0040,

		/** This value is reserved for future expansion.

		Positioning modules with this capability will be able to return

		information related to the postal address of the current location

		 */

		ECapabilityAddress     = 0x0080,

		/** This value is reserved for future expansion.

		Positioning modules with this capability will be able to return the

		current position in terms of where within a building it is. For

		example, this may include the floor and the room name.	

		The API does not currently define an extended class that encapsulates

		this type of information

		 */

		ECapabilityBuilding    = 0x0100,

		/** This value is reserved for future expansion.

		Positioning modules with this capability will be able to return provide

		a link to further information about the location. The standard mechanism

		is via a URL.

		The API does not currently define an extended class that encapsulates

		this type of information

 		*/

		ECapabilityMedia       = 0x0200

		};

public:

	IMPORT_C TPositionModuleInfo();

	IMPORT_C TPositionModuleId ModuleId() const;

	IMPORT_C TBool IsAvailable() const;

	IMPORT_C void GetModuleName(TDes& aModuleName) const;

	IMPORT_C void GetPositionQuality(TPositionQuality& aPosQuality) const;

	IMPORT_C TTechnologyType TechnologyType() const;

	IMPORT_C TDeviceLocation DeviceLocation() const;

	IMPORT_C TCapabilities Capabilities() const ;

	IMPORT_C TUint32 ClassesSupported(TPositionClassFamily aClassType) const;

	IMPORT_C TVersion Version() const;