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@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.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 __LBSPOSITIONINFO_H__
williamr@2: #define __LBSPOSITIONINFO_H__
williamr@2: 
williamr@2: #include <lbsposition.h>
williamr@2: #include <lbscommon.h>
williamr@2: #include <lbsfields.h>
williamr@2: 
williamr@4: #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: class TPositionFieldIndex;
williamr@4: #endif // SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: 
williamr@4: 
williamr@2: /**
williamr@2: The default size for a HPositionGenericInfo position information buffer
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KPositionGenericInfoDefaultBufferSize = 1024;
williamr@2: 
williamr@2: /**
williamr@2: The default number of requested fields for a HPositionGenericInfo 
williamr@2: position information buffer
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KPositionGenericInfoDefaultMaxFields = 32;
williamr@2: 
williamr@2: /**
williamr@2: Position update types
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: enum _TPositionUpdateType
williamr@2: 	{
williamr@2: 	/** EPositionUpdateUnknown */
williamr@2: 	EPositionUpdateUnknown = 0,
williamr@2: 	/** EPositionUpdateGeneral */
williamr@2: 	EPositionUpdateGeneral = 0x01
williamr@2: 	};
williamr@2: /**
williamr@2: TPositionUpdateType code
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: typedef TUint32 TPositionUpdateType;
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Position mode reasons. These values summarise the reasons why module
williamr@2: was unable to uses its preferred calculation mode when producing a 
williamr@2: position update. The values are a bit mask that can be combined
williamr@2: to describe the various reasons.
williamr@2: 
williamr@2: NetworkError is used when there is no network coverage or
williamr@2: the service is unavailable.
williamr@2: 
williamr@2: LocalError represents environmental reasons that prevent a terminal
williamr@2: based calculation - such as no satellites in view.
williamr@2: 
williamr@2: DataError is returned when there is a problem with the initialisation
williamr@2: data. For example, GPS assistance data was received but it was
williamr@2: either invalid or could not be used..
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: enum _TPositionModeReason
williamr@2: 	{
williamr@2: 	/** Mode reason none */
williamr@2: 	EPositionModeReasonNone         = 0,
williamr@2: 	/** Mode reason network error */
williamr@2: 	EPositionModeReasonNetworkError = 1 << 0,
williamr@2: 	/** Mode reason local error */
williamr@2: 	EPositionModeReasonLocalError   = 1 << 1,
williamr@2: 	/** Mode reason data error */
williamr@2: 	EPositionModeReasonDataError    = 1 << 2
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: TPositionModeReason code
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: typedef TUint32 TPositionModeReason;
williamr@2: 
williamr@2: 
williamr@2: class TPositionInfoBase : public TPositionClassTypeBase
williamr@2: /**
williamr@2: This class provides the interface used by RPositioner to get a location fix,
williamr@2: and as such all classes used to get location info from the location server should
williamr@2: derive from this class.
williamr@2: 
williamr@2: Class contains info about the update type and the ID of the module that gave the 
williamr@2: location fix
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TPositionModuleId ModuleId() const;
williamr@2: 	IMPORT_C void SetModuleId(TPositionModuleId aModuleId);
williamr@2: 
williamr@2: 	IMPORT_C TPositionUpdateType UpdateType() const;
williamr@2: 	IMPORT_C void SetUpdateType(TPositionUpdateType aUpdateType);
williamr@2: 
williamr@2: 	IMPORT_C TPositionModuleInfo::TTechnologyType PositionMode() const;
williamr@2: 	IMPORT_C void SetPositionMode(TPositionModuleInfo::TTechnologyType aMode);
williamr@2: 
williamr@2: 	IMPORT_C TPositionModeReason PositionModeReason() const;
williamr@2: 	IMPORT_C void SetPositionModeReason(TPositionModeReason aReason);
williamr@2: 
williamr@2: protected:
williamr@2: 	IMPORT_C TPositionInfoBase();
williamr@2: 
williamr@2: protected:
williamr@2: 	/** The Id of the module that gave the location fix. */
williamr@2: 	TPositionModuleId iModuleId;
williamr@2: 	/** The type of update that this location fix represents. */
williamr@2: 	TUint32 iUpdateType;
williamr@2: 
williamr@2: 	/** The positioning mode used to calculate this location fix. */
williamr@2: 	TPositionModuleInfo::TTechnologyType iPositionMode;
williamr@2: 
williamr@2: 	/** The reason why the prefered position mode was not used. */
williamr@2: 	TPositionModeReason iPositionModeReason;
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 TPositionInfo : public TPositionInfoBase
williamr@2: /**
williamr@2: Standard class for getting a TPosition location fix from the location server.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TPositionInfo();
williamr@2: 
williamr@2: 	IMPORT_C void GetPosition(TPosition& aPosition) const;
williamr@2: 	IMPORT_C void SetPosition(const TPosition& aPosition);
williamr@2: 
williamr@2: protected:
williamr@2: 	/** The TPosition. */
williamr@2: 	TPosition iPosition;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class TPositionCourseInfo : public TPositionInfo
williamr@2: /**
williamr@2: Class for getting a TCourse from the location server.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C TPositionCourseInfo();
williamr@2: 
williamr@2: 	IMPORT_C void GetCourse(TCourse& aCourse) const;
williamr@2: 	IMPORT_C void SetCourse(const TCourse& aCourse);
williamr@2: 
williamr@2: protected:
williamr@2: 	/** The TCourse. */
williamr@2: 	TCourse iCourse;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Class for getting arbitrary positioning related information back from the location server. 
williamr@2: The client can set upto KPositionMaxRequestedFields as the number of requested fields.
williamr@2: The definitions of the fields are given in the enum #_TPositionFieldId. The client must 
williamr@2: know what data type will be returned for each of the fields. The server will make a best 
williamr@2: attempt to fill in the requested fields.
williamr@2: 
williamr@2: The client needs to allocate a big enough buffer to store the information it is requesting.
williamr@2: In order to be sure of getting back all the information the client must know and allocate 
williamr@2: memory considering the return value for each requested field.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  */
williamr@2: class HPositionGenericInfo : public TPositionInfo
williamr@2: 	{
williamr@2: public:
williamr@2: 
williamr@2: 	IMPORT_C static HPositionGenericInfo* New(TInt aBufferSize = KPositionGenericInfoDefaultBufferSize,
williamr@2: 											  TInt aMaxFields = KPositionGenericInfoDefaultMaxFields);
williamr@2: 	IMPORT_C static HPositionGenericInfo* NewL(TInt aBufferSize = KPositionGenericInfoDefaultBufferSize,
williamr@2: 											   TInt aMaxFields = KPositionGenericInfoDefaultMaxFields);
williamr@2: 	IMPORT_C static HPositionGenericInfo* NewLC(TInt aBufferSize = KPositionGenericInfoDefaultBufferSize,
williamr@2: 												TInt aMaxFields = KPositionGenericInfoDefaultMaxFields);
williamr@2: 	IMPORT_C void ClearRequestedFields();
williamr@2: 	IMPORT_C TInt SetRequestedField(TPositionFieldId aFieldId);
williamr@2: 	IMPORT_C TInt SetRequestedFields(const TPositionFieldIdList aFieldIdList);
williamr@2: 	IMPORT_C TInt IsRequestedField(TPositionFieldId aFieldId) const;
williamr@2: 	IMPORT_C TPositionFieldId FirstRequestedFieldId() const;
williamr@2: 	IMPORT_C TPositionFieldId NextRequestedFieldId(TPositionFieldId aFieldId) const;
williamr@2: 	IMPORT_C TBool IsFieldAvailable(TPositionFieldId aFieldId) const;
williamr@2: 	IMPORT_C void ClearPositionData();	//Required on server side
williamr@2: 	IMPORT_C TInt BufferSize() const;
williamr@2: 	IMPORT_C TInt MaxFields() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Used to store position information.
williamr@2:      * @param aFieldId Standard position field identifier. See _TPositionFieldId
williamr@4:      * @param [in] aValue The parameter aValue can be of the type 
williamr@2:      * TInt8, TInt16, TInt32, TInt64, TUint8, TUint16, TUint32, 
williamr@2:      * TReal32, TReal64, TTime, TTimeIntervalMicroSeconds, Des8, or Des16.
williamr@2:      * @return a symbian OS error code.
williamr@2:      * @return KErrNone on successful operation.
williamr@2:      * @return KErrPositionBufferOverflow if the data contained in the 
williamr@2:      * parameter aValue cannot be added to the class due to the buffer being too small.
williamr@2:      */
williamr@2: 	template <class TType>
williamr@2: 		inline TInt SetValue(TPositionFieldId aFieldId, const TType& aValue) 
williamr@2: 			{return PositionFieldManager::SetValue(aFieldId, aValue, *this);}
williamr@2: 
williamr@2:     /**
williamr@2:      * Used to retrieve position information.
williamr@2:      * @param aFieldId Standard position field identifier. See _TPositionFieldId
williamr@4:      * @param [out] aValue The parameter aValue can be of the type 
williamr@2:      * TInt8, TInt16, TInt32, TInt64, TUint8, TUint16, TUint32, 
williamr@2:      * TReal32, TReal64, TTime, TTimeIntervalMicroSeconds, Des8, or Des16.
williamr@2:      * Panics with EPositionGenericInfoMismatchDataType if there is a 
williamr@2:      * mismatch in the data type of a field. 
williamr@2:      * @return a symbian OS error code.
williamr@2:      * @return KErrNone on successful operation.
williamr@2:      * @return KErrOverflow if the supplied descriptor is too short to contain the requested field.
williamr@2:      * This method must use the same data type as that assigned by SetValue() .
williamr@2:      */
williamr@2: 	template <class TType>
williamr@2: 		inline TInt GetValue(TPositionFieldId aFieldId, TType& aValue) const 
williamr@2: 			{return PositionFieldManager::GetValue(aFieldId, aValue, *this);}
williamr@2: 
williamr@2: private:
williamr@2: 	HPositionGenericInfo(TInt aDataBufferSize, TInt aMaxFields, 
williamr@2: 		TUint aFieldIndexStartPoint, TUint aDataStartPoint, TBool aResetRequestedFields);
williamr@2:     /**
williamr@2:      * internal private method 
williamr@2:      */
williamr@2: 	HPositionGenericInfo& operator=(const HPositionGenericInfo&);
williamr@2:     /**
williamr@2:      * internal private method 
williamr@2:      */
williamr@2: 	HPositionGenericInfo(const HPositionGenericInfo&);
williamr@2: 
williamr@2: 	TInt FindEmptyRequestedFieldOffset(TInt& aEmptyFieldOffset) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Helper method. For internal usage only 
williamr@2:      */
williamr@2: 	inline TPositionFieldId* RequestedFieldPtr();
williamr@2:     /**
williamr@2:      * Helper method. For internal usage only 
williamr@2:      */
williamr@2: 	inline const TPositionFieldId* RequestedFieldPtr() const;
williamr@2:     /**
williamr@2:      * Helper method. For internal usage only 
williamr@2:      */
williamr@2: 	inline TPositionFieldIndex* FieldIndexPtr();
williamr@2:     /**
williamr@2:      * Helper method. For internal usage only 
williamr@2:      */
williamr@2: 	inline const TPositionFieldIndex* FieldIndexPtr() const;
williamr@2: 
williamr@2: private:
williamr@2: 	friend class TPositionFieldSetter;
williamr@2: 	friend class TPositionFieldGetter;
williamr@2: 
williamr@2: 	/**	Max number of requesable/returnable fields. */
williamr@2: 	const TInt iMaxFields;
williamr@2: 
williamr@2: 	/** Offset into iBuffer of the field index. */
williamr@2: 	const TUint iFieldIndexStartPoint;
williamr@2: 
williamr@2: 	/** Offset into iBuffer of the actual location data. */
williamr@2: 	const TUint iDataStartPoint;
williamr@2: 
williamr@2: 	/** Total size of the buffer */
williamr@2: 	const TInt iTotalBufferSize;
williamr@2: 
williamr@2: 	/** Start of the buffer. The heap cell allocated for an instance of this class
williamr@2: 	has space for information up to iBuffer[iTotalBufferSize-1]*/
williamr@2: 	TUint8 iBuffer[1];	//Must be at end of class
williamr@2: 	};
williamr@2: 
williamr@2: #endif //__LBSPOSITIONINFO_H__