le_pos_interface.h

    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 //--------------------------------------------------------------------------------------------------
  164 void le_pos_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  188 le_result_t le_pos_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  205 void le_pos_DisconnectService
  206 (
  207     void
  208 );
  209 
  210 
  211 //--------------------------------------------------------------------------------------------------
  212 /**
  213  *  Fix position states.
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 typedef enum
  217 {
  218     LE_POS_STATE_NO_FIX = 0,
  219         ///< The position is not fixed.
  220 
  221     LE_POS_STATE_FIX_2D = 1,
  222         ///< 2-Dimensional position fix.
  223 
  224     LE_POS_STATE_FIX_3D = 2,
  225         ///< 3-Dimensional position fix.
  226 
  227     LE_POS_STATE_FIX_ESTIMATED = 3,
  228         ///< Estimated (i.e. forward predicted) position fix.
  229 
  230     LE_POS_STATE_UNKNOWN = 4
  231         ///< Unknow state.
  232 }
  233 le_pos_FixState_t;
  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 //--------------------------------------------------------------------------------------------------
  275 le_pos_MovementHandlerRef_t le_pos_AddMovementHandler
  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 //--------------------------------------------------------------------------------------------------
  299 void le_pos_RemoveMovementHandler
  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 //--------------------------------------------------------------------------------------------------
  317 le_result_t le_pos_Get2DLocation
  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 //--------------------------------------------------------------------------------------------------
  342 le_result_t le_pos_Get3DLocation
  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 //--------------------------------------------------------------------------------------------------
  370 le_result_t le_pos_GetTime
  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 //--------------------------------------------------------------------------------------------------
  395 le_result_t le_pos_GetDate
  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 //--------------------------------------------------------------------------------------------------
  421 le_result_t le_pos_GetMotion
  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 //--------------------------------------------------------------------------------------------------
  450 le_result_t le_pos_GetHeading
  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 //--------------------------------------------------------------------------------------------------
  475 le_result_t le_pos_GetDirection
  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 //--------------------------------------------------------------------------------------------------
  496 le_result_t le_pos_GetFixState
  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 //--------------------------------------------------------------------------------------------------
  517 le_result_t le_pos_sample_Get2DLocation
  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 //--------------------------------------------------------------------------------------------------
  542 le_result_t le_pos_sample_GetTime
  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 //--------------------------------------------------------------------------------------------------
  570 le_result_t le_pos_sample_GetDate
  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 //--------------------------------------------------------------------------------------------------
  599 le_result_t le_pos_sample_GetAltitude
  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 //--------------------------------------------------------------------------------------------------
  626 le_result_t le_pos_sample_GetHorizontalSpeed
  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 //--------------------------------------------------------------------------------------------------
  652 le_result_t le_pos_sample_GetVerticalSpeed
  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 //--------------------------------------------------------------------------------------------------
  681 le_result_t le_pos_sample_GetHeading
  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 //--------------------------------------------------------------------------------------------------
  712 le_result_t le_pos_sample_GetDirection
  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 //--------------------------------------------------------------------------------------------------
  736 le_result_t le_pos_sample_GetFixState
  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 //--------------------------------------------------------------------------------------------------
  753 void le_pos_sample_Release
  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 //--------------------------------------------------------------------------------------------------
  768 le_result_t le_pos_SetAcquisitionRate
  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 //--------------------------------------------------------------------------------------------------
  782 uint32_t le_pos_GetAcquisitionRate
  783 (
  784     void
  785 );
  786 
  787 
  788 #endif // LE_POS_INTERFACE_H_INCLUDE_GUARD
  789 
le_pos_sample_GetDirection
le_result_t le_pos_sample_GetDirection(le_pos_SampleRef_t positionSampleRef, uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
le_pos_sample_Get2DLocation
le_result_t le_pos_sample_Get2DLocation(le_pos_SampleRef_t positionSampleRef, int32_t *latitudePtr, int32_t *longitudePtr, int32_t *horizontalAccuracyPtr)
le_pos_GetDate
le_result_t le_pos_GetDate(uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
le_result_t
le_result_t
Definition: le_basics.h:35
le_pos_AddMovementHandler
le_pos_MovementHandlerRef_t le_pos_AddMovementHandler(uint32_t horizontalMagnitude, uint32_t verticalMagnitude, le_pos_MovementHandlerFunc_t handlerPtr, void *contextPtr)
le_pos_TryConnectService
le_result_t le_pos_TryConnectService(void)
le_pos_sample_GetTime
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
le_pos_FixState_t
Definition: le_pos_interface.h:216
le_pos_sample_GetDate
le_result_t le_pos_sample_GetDate(le_pos_SampleRef_t positionSampleRef, uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
LE_POS_STATE_NO_FIX
The position is not fixed. 
Definition: le_pos_interface.h:218
le_pos_GetHeading
le_result_t le_pos_GetHeading(uint32_t *headingPtr, uint32_t *headingAccuracyPtr)
LE_POS_STATE_FIX_2D
2-Dimensional position fix. 
Definition: le_pos_interface.h:221
le_pos_sample_GetAltitude
le_result_t le_pos_sample_GetAltitude(le_pos_SampleRef_t positionSampleRef, int32_t *altitudePtr, int32_t *altitudeAccuracyPtr)
le_pos_DisconnectService
void le_pos_DisconnectService(void)
le_pos_GetMotion
le_result_t le_pos_GetMotion(uint32_t *hSpeedPtr, uint32_t *hSpeedAccuracyPtr, int32_t *vSpeedPtr, int32_t *vSpeedAccuracyPtr)
le_pos_ConnectService
void le_pos_ConnectService(void)
le_pos_Get3DLocation
le_result_t le_pos_Get3DLocation(int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr, int32_t *altitudePtr, int32_t *vAccuracyPtr)
le_pos_SampleRef_t
struct le_pos_Sample * le_pos_SampleRef_t
Definition: le_pos_interface.h:241
le_pos_sample_GetHorizontalSpeed
le_result_t le_pos_sample_GetHorizontalSpeed(le_pos_SampleRef_t positionSampleRef, uint32_t *hSpeedPtr, uint32_t *hSpeedAccuracyPtr)
le_pos_GetAcquisitionRate
uint32_t le_pos_GetAcquisitionRate(void)
le_pos_MovementHandlerFunc_t
void(* le_pos_MovementHandlerFunc_t)(le_pos_SampleRef_t positionSampleRef, void *contextPtr)
Definition: le_pos_interface.h:263
legato.h
le_pos_Get2DLocation
le_result_t le_pos_Get2DLocation(int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr)
le_pos_sample_GetHeading
le_result_t le_pos_sample_GetHeading(le_pos_SampleRef_t positionSampleRef, uint32_t *headingPtr, uint32_t *headingAccuracyPtr)
le_pos_sample_GetVerticalSpeed
le_result_t le_pos_sample_GetVerticalSpeed(le_pos_SampleRef_t positionSampleRef, int32_t *vspeedPtr, int32_t *vspeedAccuracyPtr)
LE_POS_STATE_UNKNOWN
Unknow state. 
Definition: le_pos_interface.h:230
le_pos_RemoveMovementHandler
void le_pos_RemoveMovementHandler(le_pos_MovementHandlerRef_t addHandlerRef)
LE_POS_STATE_FIX_3D
3-Dimensional position fix. 
Definition: le_pos_interface.h:224
le_pos_GetDirection
le_result_t le_pos_GetDirection(uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
le_pos_GetTime
le_result_t le_pos_GetTime(uint16_t *hoursPtr, uint16_t *minutesPtr, uint16_t *secondsPtr, uint16_t *millisecondsPtr)
le_pos_SetAcquisitionRate
le_result_t le_pos_SetAcquisitionRate(uint32_t acquisitionRate)
le_pos_sample_GetFixState
le_result_t le_pos_sample_GetFixState(le_pos_SampleRef_t positionSampleRef, le_pos_FixState_t *statePtr)
le_pos_MovementHandlerRef_t
struct le_pos_MovementHandler * le_pos_MovementHandlerRef_t
Definition: le_pos_interface.h:249
le_pos_GetFixState
le_result_t le_pos_GetFixState(le_pos_FixState_t *statePtr)
le_pos_sample_Release
void le_pos_sample_Release(le_pos_SampleRef_t positionSampleRef)
LE_POS_STATE_FIX_ESTIMATED
Estimated (i.e. forward predicted) position fix. 
Definition: le_pos_interface.h:227