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