le_pos_interface.h

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