interfaces/positioning/c/le_pos.h File Reference

#include "legato.h"

Go to the source code of this file.

Typedefs
typedef struct le_pos_Sample *	le_pos_SampleRef_t
typedef struct le_pos_MovementHandler *	le_pos_MovementHandlerRef_t
typedef void(*	le_pos_MovementHandlerFunc_t )(le_pos_SampleRef_t positionSampleRef, void *contextPtr)
Functions
le_pos_MovementHandlerRef_t	le_pos_AddMovementHandler (uint32_t horizontalMagnitude, uint32_t verticalMagnitude, le_pos_MovementHandlerFunc_t handlerPtr, void *contextPtr)
void	le_pos_RemoveMovementHandler (le_pos_MovementHandlerRef_t handlerRef)
le_result_t	le_pos_sample_Get2DLocation (le_pos_SampleRef_t positionSampleRef, int32_t *latitudePtr, int32_t *longitudePtr, int32_t *horizontalAccuracyPtr)
le_result_t	le_pos_sample_GetAltitude (le_pos_SampleRef_t positionSampleRef, int32_t *altitudePtr, int32_t *altitudeAccuracyPtr)
le_result_t	le_pos_sample_GetHorizontalSpeed (le_pos_SampleRef_t positionSampleRef, uint32_t *hSpeedPtr, int32_t *hSpeedAccuracyPtr)
le_result_t	le_pos_sample_GetVerticalSpeed (le_pos_SampleRef_t positionSampleRef, int32_t *vSpeedPtr, int32_t *vSpeedAccuracyPtr)
le_result_t	le_pos_sample_GetHeading (le_pos_SampleRef_t positionSampleRef, int32_t *headingPtr, int32_t *headingAccuracyPtr)
le_result_t	le_pos_sample_GetDirection (le_pos_SampleRef_t positionSampleRef, int32_t *directionPtr, int32_t *directionAccuracyPtr)
void	le_pos_sample_Release (le_pos_SampleRef_t positionSampleRef)
le_result_t	le_pos_Get2DLocation (int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr)
le_result_t	le_pos_Get3DLocation (int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr, int32_t *altitudePtr, int32_t *vAccuracyPtr)
le_result_t	le_pos_GetMotion (uint32_t *hSpeedPtr, int32_t *hSpeedAccuracyPtr, int32_t *vSpeedPtr, int32_t *vSpeedAccuracyPtr)
le_result_t	le_pos_GetHeading (int32_t *headingPtr, int32_t *headingAccuracyPtr)
le_result_t	le_pos_GetDirection (int32_t *directionPtr, int32_t *directionAccuracyPtr)

---

Detailed Description

Legato Positioning Service include file.

Copyright (C) Sierra Wireless, Inc. 2013. All rights reserved. Use of this work is subject to license.

---

Typedef Documentation

typedef void(* le_pos_MovementHandlerFunc_t)(le_pos_SampleRef_t positionSampleRef, void *contextPtr)

Prototype for handler functions used for movement notifications.

Parameters:

positionSampleRef	Position's sample reference.
contextPtr	Context information the movement handler may require.

typedef struct le_pos_MovementHandler* le_pos_MovementHandlerRef_t

Reference type for Movement notification's Handler.

typedef struct le_pos_Sample* le_pos_SampleRef_t

Reference type for dealing with Position samples.

---

Function Documentation

le_pos_MovementHandlerRef_t le_pos_AddMovementHandler	(	uint32_t	horizontalMagnitude,
		uint32_t	verticalMagnitude,
		le_pos_MovementHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

Register an handler for movement notifications.

Returns:

Handler reference, only needed for to remove the handler.

Note:

Doesn't return on failure, there's no need to check the return value for errors.

Parameters:

[in]	horizontalMagnitude	Horizontal magnitude in metres. 0 means that I don't care about changes in the latitude and longitude.
[in]	verticalMagnitude	Vertical magnitude in metres. 0 means that I don't care about changes in the altitude.
[in]	handlerPtr	Handler function.
[in]	contextPtr	The context pointer

le_result_t le_pos_Get2DLocation	(	int32_t *	latitudePtr,
		int32_t *	longitudePtr,
		int32_t *	hAccuracyPtr
	)

Get the 2D location's data (Latitude, Longitude, Horizontal accuracy).

Returns:

LE_FAULT Function failed to get the 2D location's data

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK Function succeeded.

Note:

latitudePtr, longitudePtr, hAccuracyPtr can be set to NULL if not needed.

Parameters:

[out]	latitudePtr	Latitude in degrees, positive North.
[out]	longitudePtr	Longitude in degrees, positive East.
[out]	hAccuracyPtr	Horizontal position's accuracy in metres.

le_result_t le_pos_Get3DLocation	(	int32_t *	latitudePtr,
		int32_t *	longitudePtr,
		int32_t *	hAccuracyPtr,
		int32_t *	altitudePtr,
		int32_t *	vAccuracyPtr
	)

Get the 3D location's data (Latitude, Longitude, Altitude, Horizontal accuracy, Vertical accuracy).

Returns:

LE_FAULT Function failed to get the 3D location's data

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK Function succeeded.

Note:

latitudePtr, longitudePtr,hAccuracyPtr, altitudePtr, vAccuracyPtr can be set to NULL if not needed.

Parameters:

[out]	latitudePtr	Latitude in degrees, positive North.
[out]	longitudePtr	Longitude in degrees, positive East.
[out]	hAccuracyPtr	Horizontal position's accuracy in metres.
[out]	altitudePtr	Altitude in metres, above Mean Sea Level.
[out]	vAccuracyPtr	Vertical position's accuracy in metres.

le_result_t le_pos_GetDirection	(	int32_t *	directionPtr,
		int32_t *	directionAccuracyPtr
	)

Get the direction indication. Direction of movement is the direction that the vehicle/person is actually moving.

Returns:

LE_FAULT Function failed to get the direction indication.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK Function succeeded.

Note:

directionPtr, directionAccuracyPtr can be set to NULL if not needed.

Parameters:

[out]	directionPtr	Direction indication in degrees (where 0 is True North).
[out]	directionAccuracyPtr	Direction's accuracy in degrees.

le_result_t le_pos_GetHeading	(	int32_t *	headingPtr,
		int32_t *	headingAccuracyPtr
	)

Get the heading indication.

Returns:

LE_FAULT Function failed to get the heading indication.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK Function succeeded.

Note:

headingPtr, headingAccuracyPtr can be set to NULL if not needed.

Parameters:

[out]	headingPtr	Heading in degrees (where 0 is True North).
[out]	headingAccuracyPtr	Heading's accuracy in degrees.

le_result_t le_pos_GetMotion	(	uint32_t *	hSpeedPtr,
		int32_t *	hSpeedAccuracyPtr,
		int32_t *	vSpeedPtr,
		int32_t *	vSpeedAccuracyPtr
	)

Get the motion's data (Horizontal Speed, Horizontal Speed's accuracy, Vertical Speed, Vertical Speed's accuracy).

Returns:

LE_FAULT Function failed to get the motion's data.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX, UINT32_MAX).

LE_OK Function succeeded.

Note:

hSpeedPtr, hSpeedAccuracyPtr, vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.

Parameters:

[out]	hSpeedPtr	Horizontal Speed in m/sec.
[out]	hSpeedAccuracyPtr	Horizontal Speed's accuracy in m/sec.
[out]	vSpeedPtr	Vertical Speed in m/sec, positive up.
[out]	vSpeedAccuracyPtr	Vertical Speed's accuracy in m/sec.

void le_pos_RemoveMovementHandler

(

le_pos_MovementHandlerRef_t

handlerRef

)

Remove a handler for movement notifications.

Note:

Doesn't return on failure, no need to check the return value for errors.

Parameters:

[in]

handlerRef

Handler reference.

le_result_t le_pos_sample_Get2DLocation	(	le_pos_SampleRef_t	positionSampleRef,
		int32_t *	latitudePtr,
		int32_t *	longitudePtr,
		int32_t *	horizontalAccuracyPtr
	)

Get the position sample's 2D location (latitude, longitude, horizontal accuracy).

Returns:

LE_FAULT Function failed to find the positionSample.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK Function succeeded.

Note:

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

latitudePtr, longitudePtr, horizontalAccuracyPtr can be set to NULL if not needed.

Parameters:

[in]	positionSampleRef	Position sample's reference.
[out]	latitudePtr	Latitude in degrees.
[out]	longitudePtr	Longitude in degrees.
[out]	horizontalAccuracyPtr	Horizontal's accuracy estimate in metres.

le_result_t le_pos_sample_GetAltitude	(	le_pos_SampleRef_t	positionSampleRef,
		int32_t *	altitudePtr,
		int32_t *	altitudeAccuracyPtr
	)

Get the position sample's altitude.

Returns:

LE_FAULT Function failed to find the positionSample.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK Function succeeded.

Note:

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

altitudePtr, altitudeAccuracyPtr can be set to NULL if not needed.

Parameters:

[in]	positionSampleRef	Position sample's reference.
[out]	altitudePtr	Altitude in metres.
[out]	altitudeAccuracyPtr	Altitude's accuracy estimate in metres.

le_result_t le_pos_sample_GetDirection	(	le_pos_SampleRef_t	positionSampleRef,
		int32_t *	directionPtr,
		int32_t *	directionAccuracyPtr
	)

Get the position sample's direction. Direction of movement is the direction that the vehicle/person is actually moving.

Returns:

LE_FAULT Function failed to find the positionSample.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK Function succeeded.

Note:

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

directionPtr, directionAccuracyPtr can be set to NULL if not needed.

Parameters:

[in]	positionSampleRef	Position sample's reference.
[out]	directionPtr	Direction in degrees (where 0 is True North).
[out]	directionAccuracyPtr	Direction's accuracy estimate in degrees.

le_result_t le_pos_sample_GetHeading	(	le_pos_SampleRef_t	positionSampleRef,
		int32_t *	headingPtr,
		int32_t *	headingAccuracyPtr
	)

Get the position sample's heading. Heading is the direction that the vehicle/person is facing.

Returns:

LE_FAULT Function failed to find the positionSample.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).

LE_OK TFunction succeeded.

Note:

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

headingPtr, headingAccuracyPtr can be set to NULL if not needed.

Parameters:

[in]	positionSampleRef	Position sample's reference.
[out]	headingPtr	Heading in degrees (where 0 is True North).
[out]	headingAccuracyPtr	Heading's accuracy estimate in degrees.

le_result_t le_pos_sample_GetHorizontalSpeed	(	le_pos_SampleRef_t	positionSampleRef,
		uint32_t *	hSpeedPtr,
		int32_t *	hSpeedAccuracyPtr
	)

Get the position sample's horizontal speed.

Returns:

LE_FAULT Function failed to find the positionSample.

LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX, UINT32_MAX).

LE_OK Function succeeded.

Note:

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

hSpeedPtr, hSpeedAccuracyPtr can be set to NULL if not needed.

Parameters:

[in]	positionSampleRef	Position sample's reference.
[out]	hSpeedPtr	Horizontal speed.
[out]	hSpeedAccuracyPtr	Horizontal speed's accuracy estimate.

le_result_t le_pos_sample_GetVerticalSpeed	(	le_pos_SampleRef_t	positionSampleRef,
		int32_t *	vSpeedPtr,
		int32_t *	vSpeedAccuracyPtr
	)

Get the position sample's vertical speed.

Returns:

LE_FAULT The function failed to find the positionSample.

LE_OUT_OF_RANGE One of the retrieved parameter is not valid (set to INT32_MAX).

LE_OK The function succeeded.

Note:

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.

Parameters:

[in]	positionSampleRef	Position sample's reference.
[out]	vSpeedPtr	Vertical speed.
[out]	vSpeedAccuracyPtr	Vertical speed's accuracy estimate.

void le_pos_sample_Release

(

le_pos_SampleRef_t

positionSampleRef

)

Release the position sample.

Note:

If the caller is passing an invalid Position reference into this function, it is a fatal error, the function will not return.

Parameters:

[in]

positionSampleRef

Position sample's reference.