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