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