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