le_pos_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_pos Positioning
12  *
13  * @ref le_pos_interface.h "API Reference" <br>
14  * @subpage c_posCtrl "Positioning Control Reference"
15  *
16  * <HR>
17  *
18  * This API provides access to the device's physical position and movement information.
19  *
20  * @note Enabling and disabling the positioning system is a privileged operation available
21  * only through the @ref c_posCtrl.
22  *
23  * @section le_pos_binding IPC interfaces binding
24  *
25  * All the functions of this API are provided by the @b positioningService application service.
26  *
27  * Here's a code sample binding to Positioning services:
28  * @verbatim
29  bindings:
30  {
31  clientExe.clientComponent.le_pos -> positioningService.le_pos
32  }
33  @endverbatim
34  *
35  * @section le_pos_fix Fix On Demand
36  * The @c le_pos_Get2DLocation() function gets the last updated latitude, longitude
37  * and the horizontal accuracy values:
38  *
39  * - latitude is in degrees, positive North.
40  * - longitude is in degrees, positive East.
41  * - horizontal accuracy is in meters.
42  *
43  * The latitude and longitude are given in degrees with 6 decimal places like:
44  * - Latitude +48858300 = 48.858300 degrees North
45  * - Longitude +2294400 = 2.294400 degrees East
46  *
47  * The @c le_pos_Get3DLocation() function gets the last updated latitude, longitude,
48  * altitude and their associated accuracy values.
49  * - altitude is in meters, above Mean Sea Level, with 3 decimal places (3047 = 3.047 meters).
50  * - horizontal and vertical accuracies are in meters.
51  *
52  * The @c le_pos_GetTime() function gets the time of last updated position:
53  * - Hours into the day [range 0..23].
54  * - Minutes into the hour [range 0..59].
55  * - Seconds into the minute [range 0..59].
56  * - Milliseconds into the second [range 0..999].
57  *
58  * The @c le_pos_GetDate() function gets the date of last updated position:
59  * - Year A.D. [e.g. 2014].
60  * - Month into the year [range 1...12].
61  * - Days into the month [range 1...31].
62  *
63  * The @c le_pos_GetMotion() function gets the last updated horizontal and vertical
64  * speed values and the associated accuracy values:
65  * - horizontal speed is in m/sec.
66  * - vertical speed is in m/sec, positive up.
67  *
68  * The @c le_pos_GetHeading() function gets the last updated heading value in degrees and
69  * its associated accuracy value:
70  * - Heading in degrees, ranges from 0 to 359, 0 being True North.
71  * Heading is the direction that the vehicle or person is facing.
72  *
73  * The @c le_pos_GetDirection() function gets the last updated direction value in degrees and
74  * its associated accuracy value:
75  * - Direction in degrees, ranges from 0 to 359, 0 being True North.
76  * Direction of movement is the direction that the vehicle or person is actually moving.
77 
78  * The @c le_pos_GetFixState() function gets the position fix state. The fix state allows the user
79  * to determine if it is a 2-Dimensional or a 3-Dimensional position fix.
80  *
81  * A sample code can be seen in the following page:
82  * - @subpage c_posSampleCodeFixOnDemand
83  *
84  * @section le_pos_navigation Navigation
85  * To be notified when the device is in motion, you must register an handler function
86  * to get the new position's data. The @c le_pos_AddMovementHandler() API registers
87  * that handler. The horizontal and vertical change is measured in meters so only movement over
88  * the threshhold will trigger notification (0 means we don't care about changes).
89  *
90  * The handler will give a reference to the position sample object that has triggered the
91  * notification. You can then access parameters using accessor functions, and release
92  * the object when done with it.
93  *
94  * The accessor functions are:
95  * - le_pos_sample_Get2DLocation()
96  * - le_pos_sample_GetDate()
97  * - le_pos_sample_GetTime()
98  * - le_pos_sample_GetAltitude()
99  * - le_pos_sample_GetHorizontalSpeed()
100  * - le_pos_sample_GetVerticalSpeed()
101  * - le_pos_sample_GetHeading()
102  * - le_pos_sample_GetDirection()
103  * - le_pos_sample_GetFixState()
104  *
105  * @c le_pos_sample_Release() releases the object.
106  *
107  * You can uninstall the handler function by calling the le_pos_RemoveMovementHandler() API.
108  * @note The le_pos_RemoveMovementHandler() API does not delete the Position Object. The caller has
109  * to delete it by calling the le_pos_sample_Release() function.
110  *
111  * A sample code can be seen in the following page:
112  * - @subpage c_posSampleCodeNavigation
113  *
114  * @section le_pos_acquisitionRate Positioning acquisition rate
115  *
116  * The acquisition rate value can be set or get with le_pos_SetAcquisitionRate() and
117  * le_pos_GetAcquisitionRate().
118  * @note
119  * If the acquisition rate was not previously configured, it will be set to a default value
120  * of 5 seconds.
121  * @note
122  * The acquisition rate set with le_pos_SetAcquisitionRate() will take effect once a request of
123  * activation of the positioning service by le_posCtrl_Request() is done.
124  *
125  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
126  */
127 /**
128  * @page c_posSampleCodeFixOnDemand Sample code for Fix On Demand
129  *
130  * @include "apps/test/positioning/positioningTest/positioningTest/positioningTest.c"
131  */
132 /**
133  * @page c_posSampleCodeNavigation Sample code for Navigation
134  *
135  * @include "apps/test/positioning/posDaemonTest/le_posTest.c"
136  */
137 /**
138  * @file le_pos_interface.h
139  *
140  * Legato @ref c_pos include file.
141  *
142  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
143  */
144 
145 #ifndef LE_POS_INTERFACE_H_INCLUDE_GUARD
146 #define LE_POS_INTERFACE_H_INCLUDE_GUARD
147 
148 
149 #include "legato.h"
150 
151 //--------------------------------------------------------------------------------------------------
152 /**
153  *
154  * Connect the current client thread to the service providing this API. Block until the service is
155  * available.
156  *
157  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
158  * called before any other functions in this API. Normally, ConnectService is automatically called
159  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
160  *
161  * This function is created automatically.
162  */
163 //--------------------------------------------------------------------------------------------------
165 (
166  void
167 );
168 
169 //--------------------------------------------------------------------------------------------------
170 /**
171  *
172  * Try to connect the current client thread to the service providing this API. Return with an error
173  * if the service is not available.
174  *
175  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
176  * called before any other functions in this API. Normally, ConnectService is automatically called
177  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
178  *
179  * This function is created automatically.
180  *
181  * @return
182  * - LE_OK if the client connected successfully to the service.
183  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
184  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
185  * - LE_COMM_ERROR if the Service Directory cannot be reached.
186  */
187 //--------------------------------------------------------------------------------------------------
189 (
190  void
191 );
192 
193 //--------------------------------------------------------------------------------------------------
194 /**
195  *
196  * Disconnect the current client thread from the service providing this API.
197  *
198  * Normally, this function doesn't need to be called. After this function is called, there's no
199  * longer a connection to the service, and the functions in this API can't be used. For details, see
200  * @ref apiFilesC_client.
201  *
202  * This function is created automatically.
203  */
204 //--------------------------------------------------------------------------------------------------
206 (
207  void
208 );
209 
210 
211 //--------------------------------------------------------------------------------------------------
212 /**
213  * Fix position states.
214  */
215 //--------------------------------------------------------------------------------------------------
216 typedef enum
217 {
219  ///< The position is not fixed.
220 
222  ///< 2-Dimensional position fix.
223 
225  ///< 3-Dimensional position fix.
226 
228  ///< Estimated (i.e. forward predicted) position fix.
229 
231  ///< Unknow state.
232 }
234 
235 
236 //--------------------------------------------------------------------------------------------------
237 /**
238  * Reference type for dealing with Position samples.
239  */
240 //--------------------------------------------------------------------------------------------------
241 typedef struct le_pos_Sample* le_pos_SampleRef_t;
242 
243 
244 //--------------------------------------------------------------------------------------------------
245 /**
246  * Reference type used by Add/Remove functions for EVENT 'le_pos_Movement'
247  */
248 //--------------------------------------------------------------------------------------------------
249 typedef struct le_pos_MovementHandler* le_pos_MovementHandlerRef_t;
250 
251 
252 //--------------------------------------------------------------------------------------------------
253 /**
254  * Handler for Movement changes.
255  *
256  *
257  * @param positionSampleRef
258  * Position's sample reference
259  * @param contextPtr
260  */
261 //--------------------------------------------------------------------------------------------------
262 typedef void (*le_pos_MovementHandlerFunc_t)
263 (
264  le_pos_SampleRef_t positionSampleRef,
265  void* contextPtr
266 );
267 
268 //--------------------------------------------------------------------------------------------------
269 /**
270  * Add handler function for EVENT 'le_pos_Movement'
271  *
272  * This event provides information on movement changes.
273  */
274 //--------------------------------------------------------------------------------------------------
276 (
277  uint32_t horizontalMagnitude,
278  ///< [IN] Horizontal magnitude in meters.
279  ///< 0 means that I don't care about
280  ///< changes in the latitude and longitude.
281 
282  uint32_t verticalMagnitude,
283  ///< [IN] Vertical magnitude in meters.
284  ///< 0 means that I don't care about
285  ///< changes in the altitude.
286 
287  le_pos_MovementHandlerFunc_t handlerPtr,
288  ///< [IN]
289 
290  void* contextPtr
291  ///< [IN]
292 );
293 
294 //--------------------------------------------------------------------------------------------------
295 /**
296  * Remove handler function for EVENT 'le_pos_Movement'
297  */
298 //--------------------------------------------------------------------------------------------------
300 (
301  le_pos_MovementHandlerRef_t addHandlerRef
302  ///< [IN]
303 );
304 
305 //--------------------------------------------------------------------------------------------------
306 /**
307  * Get the 2D location's data (Latitude, Longitude, Horizontal
308  * accuracy).
309  *
310  * @return LE_FAULT Function failed to get the 2D location's data
311  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
312  * @return LE_OK Function succeeded.
313  *
314  * @note latitudePtr, longitudePtr, hAccuracyPtr can be set to NULL if not needed.
315  */
316 //--------------------------------------------------------------------------------------------------
318 (
319  int32_t* latitudePtr,
320  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
321 
322  int32_t* longitudePtr,
323  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
324 
325  int32_t* hAccuracyPtr
326  ///< [OUT] Horizontal position's accuracy in meters.
327 );
328 
329 //--------------------------------------------------------------------------------------------------
330 /**
331  * Get the 3D location's data (Latitude, Longitude, Altitude,
332  * Horizontal accuracy, Vertical accuracy).
333  *
334  * @return LE_FAULT Function failed to get the 3D location's data
335  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
336  * @return LE_OK Function succeeded.
337  *
338  * @note latitudePtr, longitudePtr,hAccuracyPtr, altitudePtr, vAccuracyPtr can be set to NULL
339  * if not needed.
340  */
341 //--------------------------------------------------------------------------------------------------
343 (
344  int32_t* latitudePtr,
345  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
346 
347  int32_t* longitudePtr,
348  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
349 
350  int32_t* hAccuracyPtr,
351  ///< [OUT] Horizontal position's accuracy in meters.
352 
353  int32_t* altitudePtr,
354  ///< [OUT] Altitude in meters, above Mean Sea Level.
355 
356  int32_t* vAccuracyPtr
357  ///< [OUT] Vertical position's accuracy in meters.
358 );
359 
360 //--------------------------------------------------------------------------------------------------
361 /**
362  * Get the time of the last updated location
363  *
364  * @return LE_FAULT Function failed to get the time.
365  * @return LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
366  * @return LE_OK Function succeeded.
367  *
368  */
369 //--------------------------------------------------------------------------------------------------
371 (
372  uint16_t* hoursPtr,
373  ///< [OUT] UTC Hours into the day [range 0..23].
374 
375  uint16_t* minutesPtr,
376  ///< [OUT] UTC Minutes into the hour [range 0..59].
377 
378  uint16_t* secondsPtr,
379  ///< [OUT] UTC Seconds into the minute [range 0..59].
380 
381  uint16_t* millisecondsPtr
382  ///< [OUT] UTC Milliseconds into the second [range 0..999].
383 );
384 
385 //--------------------------------------------------------------------------------------------------
386 /**
387  * Get the date of the last updated location
388  *
389  * @return LE_FAULT Function failed to get the date.
390  * @return LE_OUT_OF_RANGE The retrieved date is invalid (all fields are set to 0).
391  * @return LE_OK Function succeeded.
392  *
393  */
394 //--------------------------------------------------------------------------------------------------
396 (
397  uint16_t* yearPtr,
398  ///< [OUT] UTC Year A.D. [e.g. 2014].
399 
400  uint16_t* monthPtr,
401  ///< [OUT] UTC Month into the year [range 1...12].
402 
403  uint16_t* dayPtr
404  ///< [OUT] UTC Days into the month [range 1...31].
405 );
406 
407 //--------------------------------------------------------------------------------------------------
408 /**
409  * Get the motion's data (Horizontal Speed, Horizontal Speed's
410  * accuracy, Vertical Speed, Vertical Speed's accuracy).
411  *
412  * @return LE_FAULT Function failed to get the motion's data.
413  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX,
414  * UINT32_MAX).
415  * @return LE_OK Function succeeded.
416  *
417  * @note hSpeedPtr, hSpeedAccuracyPtr, vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not
418  * needed.
419  */
420 //--------------------------------------------------------------------------------------------------
422 (
423  uint32_t* hSpeedPtr,
424  ///< [OUT] Horizontal Speed in m/sec.
425 
426  uint32_t* hSpeedAccuracyPtr,
427  ///< [OUT] Horizontal Speed's accuracy in m/sec.
428 
429  int32_t* vSpeedPtr,
430  ///< [OUT] Vertical Speed in m/sec, positive up.
431 
432  int32_t* vSpeedAccuracyPtr
433  ///< [OUT] Vertical Speed's accuracy in m/sec.
434 );
435 
436 //--------------------------------------------------------------------------------------------------
437 /**
438  * Get the heading indication.
439  *
440  * @return LE_FAULT Function failed to get the heading indication.
441  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
442  * @return LE_OK Function succeeded.
443  *
444  * @note Heading is given in degrees.
445  * Heading ranges from 0 to 359 degrees, where 0 is True North.
446  *
447  * @note headingPtr, headingAccuracyPtr can be set to NULL if not needed.
448  */
449 //--------------------------------------------------------------------------------------------------
451 (
452  uint32_t* headingPtr,
453  ///< [OUT] Heading in degrees.
454  ///< Range: 0 to 359, where 0 is True North.
455 
456  uint32_t* headingAccuracyPtr
457  ///< [OUT] Heading's accuracy in degrees.
458 );
459 
460 //--------------------------------------------------------------------------------------------------
461 /**
462  * Get the direction indication. Direction of movement is the direction that the vehicle or person
463  * is actually moving.
464  *
465  * @return LE_FAULT Function failed to get the direction indication.
466  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
467  * @return LE_OK Function succeeded.
468  *
469  * @note Direction is given in degrees.
470  * Direction ranges from 0 to 359 degrees, where 0 is True North.
471  *
472  * @note directionPtr, directionAccuracyPtr can be set to NULL if not needed.
473  */
474 //--------------------------------------------------------------------------------------------------
476 (
477  uint32_t* directionPtr,
478  ///< [OUT] Direction indication in degrees.
479  ///< Range: 0 to 359, where 0 is True North.
480 
481  uint32_t* directionAccuracyPtr
482  ///< [OUT] Direction's accuracy estimate in degrees.
483 );
484 
485 //--------------------------------------------------------------------------------------------------
486 /**
487  * Get the position fix state
488  *
489  * @return LE_FAULT Function failed to get the position fix state.
490  * @return LE_OK Function succeeded.
491  *
492  * @note In case the function fails to get the position fix state, a fatal error occurs,
493  * the function will not return.
494  */
495 //--------------------------------------------------------------------------------------------------
497 (
498  le_pos_FixState_t* statePtr
499  ///< [OUT] Position fix state.
500 );
501 
502 //--------------------------------------------------------------------------------------------------
503 /**
504  * Get the position sample's 2D location (latitude, longitude,
505  * horizontal accuracy).
506  *
507  * @return LE_FAULT Function failed to find the positionSample.
508  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
509  * @return LE_OK Function succeeded.
510  *
511  * @note If the caller is passing an invalid Position reference into this function,
512  * it is a fatal error, the function will not return.
513  *
514  * @note latitudePtr, longitudePtr, horizontalAccuracyPtr can be set to NULL if not needed.
515  */
516 //--------------------------------------------------------------------------------------------------
518 (
519  le_pos_SampleRef_t positionSampleRef,
520  ///< [IN] Position sample's reference.
521 
522  int32_t* latitudePtr,
523  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
524 
525  int32_t* longitudePtr,
526  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
527 
528  int32_t* horizontalAccuracyPtr
529  ///< [OUT] Horizontal position's accuracy in meters.
530 );
531 
532 //--------------------------------------------------------------------------------------------------
533 /**
534  * Get the position sample's time.
535  *
536  * @return LE_FAULT Function failed to get the time.
537  * @return LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
538  * @return LE_OK Function succeeded.
539  *
540  */
541 //--------------------------------------------------------------------------------------------------
543 (
544  le_pos_SampleRef_t positionSampleRef,
545  ///< [IN] Position sample's reference.
546 
547  uint16_t* hoursPtr,
548  ///< [OUT] UTC Hours into the day [range 0..23].
549 
550  uint16_t* minutesPtr,
551  ///< [OUT] UTC Minutes into the hour [range 0..59].
552 
553  uint16_t* secondsPtr,
554  ///< [OUT] UTC Seconds into the minute [range 0..59].
555 
556  uint16_t* millisecondsPtr
557  ///< [OUT] UTC Milliseconds into the second [range 0..999].
558 );
559 
560 //--------------------------------------------------------------------------------------------------
561 /**
562  * Get the position sample's date.
563  *
564  * @return LE_FAULT Function failed to get the date.
565  * @return LE_OUT_OF_RANGE The retrieved date is invalid (all fields are set to 0).
566  * @return LE_OK Function succeeded.
567  *
568  */
569 //--------------------------------------------------------------------------------------------------
571 (
572  le_pos_SampleRef_t positionSampleRef,
573  ///< [IN] Position sample's reference.
574 
575  uint16_t* yearPtr,
576  ///< [OUT] UTC Year A.D. [e.g. 2014].
577 
578  uint16_t* monthPtr,
579  ///< [OUT] UTC Month into the year [range 1...12].
580 
581  uint16_t* dayPtr
582  ///< [OUT] UTC Days into the month [range 1...31].
583 );
584 
585 //--------------------------------------------------------------------------------------------------
586 /**
587  * Get the position sample's altitude.
588  *
589  * @return LE_FAULT Function failed to find the positionSample.
590  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
591  * @return LE_OK Function succeeded.
592  *
593  * @note If the caller is passing an invalid Position reference into this function,
594  * it is a fatal error, the function will not return.
595  *
596  * @note altitudePtr, altitudeAccuracyPtr can be set to NULL if not needed.
597  */
598 //--------------------------------------------------------------------------------------------------
600 (
601  le_pos_SampleRef_t positionSampleRef,
602  ///< [IN] Position sample's reference.
603 
604  int32_t* altitudePtr,
605  ///< [OUT] Altitude in meters, above Mean Sea Level.
606 
607  int32_t* altitudeAccuracyPtr
608  ///< [OUT] Vertical position's accuracy in meters.
609 );
610 
611 //--------------------------------------------------------------------------------------------------
612 /**
613  * Get the position sample's horizontal speed.
614  *
615  * @return LE_FAULT Function failed to find the positionSample.
616  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX,
617  * UINT32_MAX).
618  * @return LE_OK Function succeeded.
619  *
620  * @note If the caller is passing an invalid Position reference into this function,
621  * it is a fatal error, the function will not return.
622  *
623  * @note hSpeedPtr, hSpeedAccuracyPtr can be set to NULL if not needed.
624  */
625 //--------------------------------------------------------------------------------------------------
627 (
628  le_pos_SampleRef_t positionSampleRef,
629  ///< [IN] Position sample's reference.
630 
631  uint32_t* hSpeedPtr,
632  ///< [OUT] The Horizontal Speed in m/sec.
633 
634  uint32_t* hSpeedAccuracyPtr
635  ///< [OUT] The Horizontal Speed's accuracy in m/sec.
636 );
637 
638 //--------------------------------------------------------------------------------------------------
639 /**
640  * Get the position sample's vertical speed.
641  *
642  * @return LE_FAULT The function failed to find the positionSample.
643  * @return LE_OUT_OF_RANGE One of the retrieved parameter is not valid (set to INT32_MAX).
644  * @return LE_OK The function succeeded.
645  *
646  * @note If the caller is passing an invalid Position reference into this function,
647  * it is a fatal error, the function will not return.
648  *
649  * @note vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.
650  */
651 //--------------------------------------------------------------------------------------------------
653 (
654  le_pos_SampleRef_t positionSampleRef,
655  ///< [IN] Position sample's reference.
656 
657  int32_t* vspeedPtr,
658  ///< [OUT] The Vertical Speed in m/sec, positive up.
659 
660  int32_t* vspeedAccuracyPtr
661  ///< [OUT] The Vertical Speed's accuracy in m/sec.
662 );
663 
664 //--------------------------------------------------------------------------------------------------
665 /**
666  * Get the position sample's heading. Heading is the direction that the vehicle or person is facing.
667  *
668  * @return LE_FAULT Function failed to find the positionSample.
669  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
670  * @return LE_OK TFunction succeeded.
671  *
672  * @note Heading is given in degrees.
673  * Heading ranges from 0 to 359 degrees, where 0 is True North.
674  *
675  * @note If the caller is passing an invalid Position reference into this function,
676  * it is a fatal error, the function will not return.
677  *
678  * @note headingPtr, headingAccuracyPtr can be set to NULL if not needed.
679  */
680 //--------------------------------------------------------------------------------------------------
682 (
683  le_pos_SampleRef_t positionSampleRef,
684  ///< [IN] Position sample's reference.
685 
686  uint32_t* headingPtr,
687  ///< [OUT] Heading in degrees.
688  ///< Range: 0 to 359, where 0 is True North.
689 
690  uint32_t* headingAccuracyPtr
691  ///< [OUT] Heading's accuracy estimate in degrees.
692 );
693 
694 //--------------------------------------------------------------------------------------------------
695 /**
696  * Get the position sample's direction. Direction of movement is the direction that the vehicle or
697  * person is actually moving.
698  *
699  * @return LE_FAULT Function failed to find the positionSample.
700  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
701  * @return LE_OK Function succeeded.
702  *
703  * @note Direction is given in degrees.
704  * Direction ranges from 0 to 359 degrees, where 0 is True North.
705  *
706  * @note If the caller is passing an invalid Position reference into this function,
707  * it is a fatal error, the function will not return.
708  *
709  * @note directionPtr, directionAccuracyPtr can be set to NULL if not needed.
710  */
711 //--------------------------------------------------------------------------------------------------
713 (
714  le_pos_SampleRef_t positionSampleRef,
715  ///< [IN] Position sample's reference.
716 
717  uint32_t* directionPtr,
718  ///< [OUT] Direction indication in degrees.
719  ///< Range: 0 to 359, where 0 is True North.
720 
721  uint32_t* directionAccuracyPtr
722  ///< [OUT] Direction's accuracy estimate in degrees.
723 );
724 
725 //--------------------------------------------------------------------------------------------------
726 /**
727  * Get the position sample's fix state.
728  *
729  * @return LE_FAULT Function failed to get the position sample's fix state.
730  * @return LE_OK Function succeeded.
731  *
732  * @note If the caller is passing an invalid Position reference into this function,
733  * it is a fatal error, the function will not return.
734  */
735 //--------------------------------------------------------------------------------------------------
737 (
738  le_pos_SampleRef_t positionSampleRef,
739  ///< [IN] Position sample's reference.
740 
741  le_pos_FixState_t* statePtr
742  ///< [OUT] Position fix state.
743 );
744 
745 //--------------------------------------------------------------------------------------------------
746 /**
747  * Release the position sample.
748  *
749  * @note If the caller is passing an invalid Position reference into this function,
750  * it is a fatal error, the function will not return.
751  */
752 //--------------------------------------------------------------------------------------------------
754 (
755  le_pos_SampleRef_t positionSampleRef
756  ///< [IN] Position sample's reference.
757 );
758 
759 //--------------------------------------------------------------------------------------------------
760 /**
761  * Set the acquisition rate.
762  *
763  * @return
764  * LE_OUT_OF_RANGE Invalid acquisition rate.
765  * LE_OK The function succeeded.
766  */
767 //--------------------------------------------------------------------------------------------------
769 (
770  uint32_t acquisitionRate
771  ///< [IN] Acquisition rate in milliseconds.
772 );
773 
774 //--------------------------------------------------------------------------------------------------
775 /**
776  * Retrieve the acquisition rate.
777  *
778  * @return
779  * Acquisition rate in milliseconds.
780  */
781 //--------------------------------------------------------------------------------------------------
783 (
784  void
785 );
786 
787 
788 #endif // LE_POS_INTERFACE_H_INCLUDE_GUARD
789 
le_result_t le_pos_sample_GetDirection(le_pos_SampleRef_t positionSampleRef, uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
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_GetDate(uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
le_result_t
Definition: le_basics.h:35
le_pos_MovementHandlerRef_t le_pos_AddMovementHandler(uint32_t horizontalMagnitude, uint32_t verticalMagnitude, le_pos_MovementHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_pos_TryConnectService(void)
le_result_t le_pos_sample_GetTime(le_pos_SampleRef_t positionSampleRef, uint16_t *hoursPtr, uint16_t *minutesPtr, uint16_t *secondsPtr, uint16_t *millisecondsPtr)
le_pos_FixState_t
Definition: le_pos_interface.h:216
le_result_t le_pos_sample_GetDate(le_pos_SampleRef_t positionSampleRef, uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
The position is not fixed.
Definition: le_pos_interface.h:218
le_result_t le_pos_GetHeading(uint32_t *headingPtr, uint32_t *headingAccuracyPtr)
2-Dimensional position fix.
Definition: le_pos_interface.h:221
le_result_t le_pos_sample_GetAltitude(le_pos_SampleRef_t positionSampleRef, int32_t *altitudePtr, int32_t *altitudeAccuracyPtr)
void le_pos_DisconnectService(void)
le_result_t le_pos_GetMotion(uint32_t *hSpeedPtr, uint32_t *hSpeedAccuracyPtr, int32_t *vSpeedPtr, int32_t *vSpeedAccuracyPtr)
void le_pos_ConnectService(void)
le_result_t le_pos_Get3DLocation(int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr, int32_t *altitudePtr, int32_t *vAccuracyPtr)
struct le_pos_Sample * le_pos_SampleRef_t
Definition: le_pos_interface.h:241
le_result_t le_pos_sample_GetHorizontalSpeed(le_pos_SampleRef_t positionSampleRef, uint32_t *hSpeedPtr, uint32_t *hSpeedAccuracyPtr)
uint32_t le_pos_GetAcquisitionRate(void)
void(* le_pos_MovementHandlerFunc_t)(le_pos_SampleRef_t positionSampleRef, void *contextPtr)
Definition: le_pos_interface.h:263
le_result_t le_pos_Get2DLocation(int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr)
le_result_t le_pos_sample_GetHeading(le_pos_SampleRef_t positionSampleRef, uint32_t *headingPtr, uint32_t *headingAccuracyPtr)
le_result_t le_pos_sample_GetVerticalSpeed(le_pos_SampleRef_t positionSampleRef, int32_t *vspeedPtr, int32_t *vspeedAccuracyPtr)
Unknow state.
Definition: le_pos_interface.h:230
void le_pos_RemoveMovementHandler(le_pos_MovementHandlerRef_t addHandlerRef)
3-Dimensional position fix.
Definition: le_pos_interface.h:224
le_result_t le_pos_GetDirection(uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
le_result_t le_pos_GetTime(uint16_t *hoursPtr, uint16_t *minutesPtr, uint16_t *secondsPtr, uint16_t *millisecondsPtr)
le_result_t le_pos_SetAcquisitionRate(uint32_t acquisitionRate)
le_result_t le_pos_sample_GetFixState(le_pos_SampleRef_t positionSampleRef, le_pos_FixState_t *statePtr)
struct le_pos_MovementHandler * le_pos_MovementHandlerRef_t
Definition: le_pos_interface.h:249
le_result_t le_pos_GetFixState(le_pos_FixState_t *statePtr)
void le_pos_sample_Release(le_pos_SampleRef_t positionSampleRef)
Estimated (i.e. forward predicted) position fix.
Definition: le_pos_interface.h:227