le_pos_interface.h

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