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 //--------------------------------------------------------------------------------------------------
163 /**
164  * Type for handler called when a server disconnects.
165  */
166 //--------------------------------------------------------------------------------------------------
167 typedef void (*le_pos_DisconnectHandler_t)(void *);
168 
169 //--------------------------------------------------------------------------------------------------
170 /**
171  *
172  * Connect the current client thread to the service providing this API. Block until the service is
173  * 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 //--------------------------------------------------------------------------------------------------
183 (
184  void
185 );
186 
187 //--------------------------------------------------------------------------------------------------
188 /**
189  *
190  * Try to connect the current client thread to the service providing this API. Return with an error
191  * if the service is not available.
192  *
193  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
194  * called before any other functions in this API. Normally, ConnectService is automatically called
195  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
196  *
197  * This function is created automatically.
198  *
199  * @return
200  * - LE_OK if the client connected successfully to the service.
201  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
202  * bound.
203  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
204  * - LE_COMM_ERROR if the Service Directory cannot be reached.
205  */
206 //--------------------------------------------------------------------------------------------------
208 (
209  void
210 );
211 
212 //--------------------------------------------------------------------------------------------------
213 /**
214  * Set handler called when server disconnection is detected.
215  *
216  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
217  * to continue without exiting, it should call longjmp() from inside the handler.
218  */
219 //--------------------------------------------------------------------------------------------------
221 (
222  le_pos_DisconnectHandler_t disconnectHandler,
223  void *contextPtr
224 );
225 
226 //--------------------------------------------------------------------------------------------------
227 /**
228  *
229  * Disconnect the current client thread from the service providing this API.
230  *
231  * Normally, this function doesn't need to be called. After this function is called, there's no
232  * longer a connection to the service, and the functions in this API can't be used. For details, see
233  * @ref apiFilesC_client.
234  *
235  * This function is created automatically.
236  */
237 //--------------------------------------------------------------------------------------------------
239 (
240  void
241 );
242 
243 
244 //--------------------------------------------------------------------------------------------------
245 /**
246  * Fix position states.
247  */
248 //--------------------------------------------------------------------------------------------------
249 
250 
251 //--------------------------------------------------------------------------------------------------
252 /**
253  * Resolution values.
254  */
255 //--------------------------------------------------------------------------------------------------
256 
257 
258 //--------------------------------------------------------------------------------------------------
259 /**
260  * Reference type for dealing with Position samples.
261  */
262 //--------------------------------------------------------------------------------------------------
263 
264 
265 //--------------------------------------------------------------------------------------------------
266 /**
267  * Handler for movement changes that returns the reference of a reported position sample.
268  *
269  */
270 //--------------------------------------------------------------------------------------------------
271 
272 
273 //--------------------------------------------------------------------------------------------------
274 /**
275  * Reference type used by Add/Remove functions for EVENT 'le_pos_Movement'
276  */
277 //--------------------------------------------------------------------------------------------------
278 
279 
280 //--------------------------------------------------------------------------------------------------
281 /**
282  * Add handler function for EVENT 'le_pos_Movement'
283  *
284  * This event provides information on movement changes.
285  *
286  */
287 //--------------------------------------------------------------------------------------------------
288 le_pos_MovementHandlerRef_t le_pos_AddMovementHandler
289 (
290  uint32_t horizontalMagnitude,
291  ///< [IN] Horizontal magnitude in meters.
292  ///< 0 means that I don't care about
293  ///< changes in the latitude and longitude.
294  uint32_t verticalMagnitude,
295  ///< [IN] Vertical magnitude in meters.
296  ///< 0 means that I don't care about
297  ///< changes in the altitude.
298  le_pos_MovementHandlerFunc_t handlerPtr,
299  ///< [IN]
300  void* contextPtr
301  ///< [IN]
302 );
303 
304 //--------------------------------------------------------------------------------------------------
305 /**
306  * Remove handler function for EVENT 'le_pos_Movement'
307  */
308 //--------------------------------------------------------------------------------------------------
310 (
311  le_pos_MovementHandlerRef_t handlerRef
312  ///< [IN]
313 );
314 
315 //--------------------------------------------------------------------------------------------------
316 /**
317  * Get the 2D location's data (Latitude, Longitude, Horizontal
318  * accuracy).
319  *
320  * @return LE_FAULT Function failed to get the 2D location's data
321  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
322  * @return LE_OK Function succeeded.
323  *
324  * @note latitudePtr, longitudePtr, hAccuracyPtr can be set to NULL if not needed.
325  */
326 //--------------------------------------------------------------------------------------------------
328 (
329  int32_t* latitudePtr,
330  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
331  int32_t* longitudePtr,
332  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
333  int32_t* hAccuracyPtr
334  ///< [OUT] Horizontal position's accuracy in meters by default.
335 );
336 
337 //--------------------------------------------------------------------------------------------------
338 /**
339  * Get the 3D location's data (Latitude, Longitude, Altitude,
340  * Horizontal accuracy, Vertical accuracy).
341  *
342  * @return LE_FAULT Function failed to get the 3D location's data
343  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
344  * @return LE_OK Function succeeded.
345  *
346  * @note latitudePtr, longitudePtr,hAccuracyPtr, altitudePtr, vAccuracyPtr can be set to NULL
347  * if not needed.
348  */
349 //--------------------------------------------------------------------------------------------------
351 (
352  int32_t* latitudePtr,
353  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
354  int32_t* longitudePtr,
355  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
356  int32_t* hAccuracyPtr,
357  ///< [OUT] Horizontal position's accuracy in meters by default.
358  int32_t* altitudePtr,
359  ///< [OUT] Altitude above Mean Sea Level in meters by default.
360  int32_t* vAccuracyPtr
361  ///< [OUT] Vertical position's accuracy in meters by default.
362 );
363 
364 //--------------------------------------------------------------------------------------------------
365 /**
366  * Get the time of the last updated location
367  *
368  * @return LE_FAULT Function failed to get the time.
369  * @return LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
370  * @return LE_OK Function succeeded.
371  *
372  */
373 //--------------------------------------------------------------------------------------------------
375 (
376  uint16_t* hoursPtr,
377  ///< [OUT] UTC Hours into the day [range 0..23].
378  uint16_t* minutesPtr,
379  ///< [OUT] UTC Minutes into the hour [range 0..59].
380  uint16_t* secondsPtr,
381  ///< [OUT] UTC Seconds into the minute [range 0..59].
382  uint16_t* millisecondsPtr
383  ///< [OUT] UTC Milliseconds into the second [range 0..999].
384 );
385 
386 //--------------------------------------------------------------------------------------------------
387 /**
388  * Get the date of the last updated location
389  *
390  * @return LE_FAULT Function failed to get the date.
391  * @return LE_OUT_OF_RANGE The retrieved date is invalid (all fields are set to 0).
392  * @return LE_OK Function succeeded.
393  *
394  */
395 //--------------------------------------------------------------------------------------------------
397 (
398  uint16_t* yearPtr,
399  ///< [OUT] UTC Year A.D. [e.g. 2014].
400  uint16_t* monthPtr,
401  ///< [OUT] UTC Month into the year [range 1...12].
402  uint16_t* dayPtr
403  ///< [OUT] UTC Days into the month [range 1...31].
404 );
405 
406 //--------------------------------------------------------------------------------------------------
407 /**
408  * Get the motion's data (Horizontal Speed, Horizontal Speed's
409  * accuracy, Vertical Speed, Vertical Speed's accuracy).
410  *
411  * @return LE_FAULT Function failed to get the motion's data.
412  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX,
413  * UINT32_MAX).
414  * @return LE_OK Function succeeded.
415  *
416  * @note hSpeedPtr, hSpeedAccuracyPtr, vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not
417  * needed.
418  */
419 //--------------------------------------------------------------------------------------------------
421 (
422  uint32_t* hSpeedPtr,
423  ///< [OUT] Horizontal Speed in m/sec.
424  uint32_t* hSpeedAccuracyPtr,
425  ///< [OUT] Horizontal Speed's accuracy in m/sec.
426  int32_t* vSpeedPtr,
427  ///< [OUT] Vertical Speed in m/sec, positive up.
428  int32_t* vSpeedAccuracyPtr
429  ///< [OUT] Vertical Speed's accuracy in m/sec.
430 );
431 
432 //--------------------------------------------------------------------------------------------------
433 /**
434  * Get the heading indication.
435  *
436  * @return LE_FAULT Function failed to get the heading indication.
437  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
438  * @return LE_OK Function succeeded.
439  *
440  * @note Heading is given in degrees.
441  * Heading ranges from 0 to 359 degrees, where 0 is True North.
442  *
443  * @note headingPtr, headingAccuracyPtr can be set to NULL if not needed.
444  */
445 //--------------------------------------------------------------------------------------------------
447 (
448  uint32_t* headingPtr,
449  ///< [OUT] Heading in degrees.
450  ///< Range: 0 to 359, where 0 is True North.
451  uint32_t* headingAccuracyPtr
452  ///< [OUT] Heading's accuracy in degrees.
453 );
454 
455 //--------------------------------------------------------------------------------------------------
456 /**
457  * Get the direction indication. Direction of movement is the direction that the vehicle or person
458  * is actually moving.
459  *
460  * @return LE_FAULT Function failed to get the direction indication.
461  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
462  * @return LE_OK Function succeeded.
463  *
464  * @note Direction is given in degrees.
465  * Direction ranges from 0 to 359 degrees, where 0 is True North.
466  *
467  * @note directionPtr, directionAccuracyPtr can be set to NULL if not needed.
468  */
469 //--------------------------------------------------------------------------------------------------
471 (
472  uint32_t* directionPtr,
473  ///< [OUT] Direction indication in degrees.
474  ///< Range: 0 to 359, where 0 is True North.
475  uint32_t* directionAccuracyPtr
476  ///< [OUT] Direction's accuracy estimate in degrees.
477 );
478 
479 //--------------------------------------------------------------------------------------------------
480 /**
481  * Get the position fix state
482  *
483  * @return LE_FAULT Function failed to get the position fix state.
484  * @return LE_OK Function succeeded.
485  *
486  * @note In case the function fails to get the position fix state, a fatal error occurs,
487  * the function will not return.
488  */
489 //--------------------------------------------------------------------------------------------------
491 (
492  le_pos_FixState_t* statePtr
493  ///< [OUT] Position fix state.
494 );
495 
496 //--------------------------------------------------------------------------------------------------
497 /**
498  * Get the position sample's 2D location (latitude, longitude,
499  * horizontal accuracy).
500  *
501  * @return LE_FAULT Function failed to find the positionSample.
502  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
503  * @return LE_OK Function succeeded.
504  *
505  * @note If the caller is passing an invalid Position reference into this function,
506  * it is a fatal error, the function will not return.
507  *
508  * @note latitudePtr, longitudePtr, horizontalAccuracyPtr can be set to NULL if not needed.
509  */
510 //--------------------------------------------------------------------------------------------------
512 (
513  le_pos_SampleRef_t positionSampleRef,
514  ///< [IN] Position sample's reference.
515  int32_t* latitudePtr,
516  ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
517  int32_t* longitudePtr,
518  ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
519  int32_t* horizontalAccuracyPtr
520  ///< [OUT] Horizontal position's accuracy in meters by default.
521 );
522 
523 //--------------------------------------------------------------------------------------------------
524 /**
525  * Get the position sample's time.
526  *
527  * @return LE_FAULT Function failed to get the time.
528  * @return LE_OUT_OF_RANGE The retrieved time is invalid (all fields are set to 0).
529  * @return LE_OK Function succeeded.
530  *
531  */
532 //--------------------------------------------------------------------------------------------------
534 (
535  le_pos_SampleRef_t positionSampleRef,
536  ///< [IN] Position sample's reference.
537  uint16_t* hoursPtr,
538  ///< [OUT] UTC Hours into the day [range 0..23].
539  uint16_t* minutesPtr,
540  ///< [OUT] UTC Minutes into the hour [range 0..59].
541  uint16_t* secondsPtr,
542  ///< [OUT] UTC Seconds into the minute [range 0..59].
543  uint16_t* millisecondsPtr
544  ///< [OUT] UTC Milliseconds into the second [range 0..999].
545 );
546 
547 //--------------------------------------------------------------------------------------------------
548 /**
549  * Get the position sample's date.
550  *
551  * @return LE_FAULT Function failed to get the date.
552  * @return LE_OUT_OF_RANGE The retrieved date is invalid (all fields are set to 0).
553  * @return LE_OK Function succeeded.
554  *
555  */
556 //--------------------------------------------------------------------------------------------------
558 (
559  le_pos_SampleRef_t positionSampleRef,
560  ///< [IN] Position sample's reference.
561  uint16_t* yearPtr,
562  ///< [OUT] UTC Year A.D. [e.g. 2014].
563  uint16_t* monthPtr,
564  ///< [OUT] UTC Month into the year [range 1...12].
565  uint16_t* dayPtr
566  ///< [OUT] UTC Days into the month [range 1...31].
567 );
568 
569 //--------------------------------------------------------------------------------------------------
570 /**
571  * Get the position sample's altitude.
572  *
573  * @return LE_FAULT Function failed to find the positionSample.
574  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX).
575  * @return LE_OK Function succeeded.
576  *
577  * @note If the caller is passing an invalid Position reference into this function,
578  * it is a fatal error, the function will not return.
579  *
580  * @note altitudePtr, altitudeAccuracyPtr can be set to NULL if not needed.
581  */
582 //--------------------------------------------------------------------------------------------------
584 (
585  le_pos_SampleRef_t positionSampleRef,
586  ///< [IN] Position sample's reference.
587  int32_t* altitudePtr,
588  ///< [OUT] Altitude above Mean Sea Level in meters by default.
589  int32_t* altitudeAccuracyPtr
590  ///< [OUT] Vertical position's accuracy in meters by default.
591 );
592 
593 //--------------------------------------------------------------------------------------------------
594 /**
595  * Get the position sample's horizontal speed.
596  *
597  * @return LE_FAULT Function failed to find the positionSample.
598  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to INT32_MAX,
599  * UINT32_MAX).
600  * @return LE_OK Function succeeded.
601  *
602  * @note If the caller is passing an invalid Position reference into this function,
603  * it is a fatal error, the function will not return.
604  *
605  * @note hSpeedPtr, hSpeedAccuracyPtr can be set to NULL if not needed.
606  */
607 //--------------------------------------------------------------------------------------------------
609 (
610  le_pos_SampleRef_t positionSampleRef,
611  ///< [IN] Position sample's reference.
612  uint32_t* hSpeedPtr,
613  ///< [OUT] The Horizontal Speed in m/sec.
614  uint32_t* hSpeedAccuracyPtr
615  ///< [OUT] The Horizontal Speed's accuracy in m/sec.
616 );
617 
618 //--------------------------------------------------------------------------------------------------
619 /**
620  * Get the position sample's vertical speed.
621  *
622  * @return LE_FAULT The function failed to find the positionSample.
623  * @return LE_OUT_OF_RANGE One of the retrieved parameter is not valid (set to INT32_MAX).
624  * @return LE_OK The function succeeded.
625  *
626  * @note If the caller is passing an invalid Position reference into this function,
627  * it is a fatal error, the function will not return.
628  *
629  * @note vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.
630  */
631 //--------------------------------------------------------------------------------------------------
633 (
634  le_pos_SampleRef_t positionSampleRef,
635  ///< [IN] Position sample's reference.
636  int32_t* vspeedPtr,
637  ///< [OUT] The Vertical Speed in m/sec, positive up.
638  int32_t* vspeedAccuracyPtr
639  ///< [OUT] The Vertical Speed's accuracy in m/sec.
640 );
641 
642 //--------------------------------------------------------------------------------------------------
643 /**
644  * Get the position sample's heading. Heading is the direction that the vehicle or person is facing.
645  *
646  * @return LE_FAULT Function failed to find the positionSample.
647  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
648  * @return LE_OK TFunction succeeded.
649  *
650  * @note Heading is given in degrees.
651  * Heading ranges from 0 to 359 degrees, where 0 is True North.
652  *
653  * @note If the caller is passing an invalid Position reference into this function,
654  * it is a fatal error, the function will not return.
655  *
656  * @note headingPtr, headingAccuracyPtr can be set to NULL if not needed.
657  */
658 //--------------------------------------------------------------------------------------------------
660 (
661  le_pos_SampleRef_t positionSampleRef,
662  ///< [IN] Position sample's reference.
663  uint32_t* headingPtr,
664  ///< [OUT] Heading in degrees.
665  ///< Range: 0 to 359, where 0 is True North.
666  uint32_t* headingAccuracyPtr
667  ///< [OUT] Heading's accuracy estimate in degrees.
668 );
669 
670 //--------------------------------------------------------------------------------------------------
671 /**
672  * Get the position sample's direction. Direction of movement is the direction that the vehicle or
673  * person is actually moving.
674  *
675  * @return LE_FAULT Function failed to find the positionSample.
676  * @return LE_OUT_OF_RANGE One of the retrieved parameter is invalid (set to UINT32_MAX).
677  * @return LE_OK Function succeeded.
678  *
679  * @note Direction is given in degrees.
680  * Direction ranges from 0 to 359 degrees, where 0 is True North.
681  *
682  * @note If the caller is passing an invalid Position reference into this function,
683  * it is a fatal error, the function will not return.
684  *
685  * @note directionPtr, directionAccuracyPtr can be set to NULL if not needed.
686  */
687 //--------------------------------------------------------------------------------------------------
689 (
690  le_pos_SampleRef_t positionSampleRef,
691  ///< [IN] Position sample's reference.
692  uint32_t* directionPtr,
693  ///< [OUT] Direction indication in degrees.
694  ///< Range: 0 to 359, where 0 is True North.
695  uint32_t* directionAccuracyPtr
696  ///< [OUT] Direction's accuracy estimate in degrees.
697 );
698 
699 //--------------------------------------------------------------------------------------------------
700 /**
701  * Get the position sample's fix state.
702  *
703  * @return LE_FAULT Function failed to get the position sample's fix state.
704  * @return LE_OK Function succeeded.
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 //--------------------------------------------------------------------------------------------------
711 (
712  le_pos_SampleRef_t positionSampleRef,
713  ///< [IN] Position sample's reference.
714  le_pos_FixState_t* statePtr
715  ///< [OUT] Position fix state.
716 );
717 
718 //--------------------------------------------------------------------------------------------------
719 /**
720  * Release the position sample.
721  *
722  * @note If the caller is passing an invalid Position reference into this function,
723  * it is a fatal error, the function will not return.
724  */
725 //--------------------------------------------------------------------------------------------------
727 (
728  le_pos_SampleRef_t positionSampleRef
729  ///< [IN] Position sample's reference.
730 );
731 
732 //--------------------------------------------------------------------------------------------------
733 /**
734  * Set the acquisition rate.
735  *
736  * @return
737  * LE_OUT_OF_RANGE Invalid acquisition rate.
738  * LE_OK The function succeeded.
739  */
740 //--------------------------------------------------------------------------------------------------
742 (
743  uint32_t acquisitionRate
744  ///< [IN] Acquisition rate in milliseconds.
745 );
746 
747 //--------------------------------------------------------------------------------------------------
748 /**
749  * Retrieve the acquisition rate.
750  *
751  * @return
752  * Acquisition rate in milliseconds.
753  */
754 //--------------------------------------------------------------------------------------------------
756 (
757  void
758 );
759 
760 //--------------------------------------------------------------------------------------------------
761 /**
762  * Set the resolution for the positioning distance values.
763  *
764  * @return LE_OK Function succeeded.
765  * @return LE_BAD_PARAMETER Invalid parameter provided.
766  *
767  * @note The positioning distance values are: the altitude above sea level, the horizontal
768  * position accuracy and the vertical position accuracy. The API sets the same resolution to
769  * all distance values. The resolution change request takes effect immediately.
770  *
771  * @warning The positioning distance values resolutions are platform dependent. Please refer to
772  * @ref platformConstraintsPositioning_SettingResolution section for full details.
773  */
774 //--------------------------------------------------------------------------------------------------
776 (
777  le_pos_Resolution_t resolution
778  ///< [IN] Resolution.
779 );
780 
781 #endif // LE_POS_INTERFACE_H_INCLUDE_GUARD
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:45
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_result_t le_pos_sample_GetDate(le_pos_SampleRef_t positionSampleRef, uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
le_result_t le_pos_GetHeading(uint32_t *headingPtr, uint32_t *headingAccuracyPtr)
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)
le_result_t le_pos_sample_GetHorizontalSpeed(le_pos_SampleRef_t positionSampleRef, uint32_t *hSpeedPtr, uint32_t *hSpeedAccuracyPtr)
uint32_t le_pos_GetAcquisitionRate(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
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)
le_result_t le_pos_SetDistanceResolution(le_pos_Resolution_t resolution)
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)
void le_pos_RemoveMovementHandler(le_pos_MovementHandlerRef_t handlerRef)
LE_FULL_API void le_pos_SetServerDisconnectHandler(le_pos_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_pos_sample_GetFixState(le_pos_SampleRef_t positionSampleRef, le_pos_FixState_t *statePtr)
void(* le_pos_DisconnectHandler_t)(void *)
Definition: le_pos_interface.h:167
le_result_t le_pos_GetFixState(le_pos_FixState_t *statePtr)
void le_pos_sample_Release(le_pos_SampleRef_t positionSampleRef)