le_gnss_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_gnss GNSS
   14  *
   15  * @ref le_gnss_interface.h "API Reference" <br>
   16  * @ref platformConstraintsGnss <br>
   17  * @ref howToGNSS "How To Use GNSS" <br>
   18  * @ref toolsTarget_gnss "GNSS target tool" <br>
   19  *
   20  * <HR>
   21  *
   22  * This API provides access to the GNSS device.
   23  *
   24  * GNSS or Global Navigation Satellite System is a satellite navigation system with global coverage.
   25  *
   26  * This API provides function to configure the GNSS device and retrieve position information.
   27  *
   28  * @section le_gnss_binding IPC interfaces binding
   29  *
   30  * All the functions of this API are provided by the @b positioningService application service.
   31  *
   32  * Here's a code sample binding to Positioning services:
   33  * @verbatim
   34    bindings:
   35    {
   36       clientExe.clientComponent.le_gnss -> positioningService.le_gnss
   37    }
   38    @endverbatim
   39  *
   40  * @section le_gnss_ControlApi GNSS Control API
   41  *
   42  * @subsection le_gnss_EnableDisable Enable/Disable GNSS device
   43  *
   44  * The application can enable/disable the GNSS device with the le_gnss_Enable()
   45  * / le_gnss_Disable() functions.
   46  * By default the GNSS device is enabled for the positioningService application service.
   47  * Also see @ref howToGNSS.
   48  *
   49  * A sample code can be seen in the following page:
   50  * - @subpage c_gnssSampleCodeEnableDisable
   51  *
   52  * @subsection le_gnss_StartStop Start/Stop GNSS device
   53  *
   54  * The application can start/stop the GNSS device with the le_gnss_Start() / le_gnss_Stop()
   55  * functions.
   56  * The default "HOT" start condition is applied and all assistance data are used.
   57  * Also see @ref howToGNSS.
   58  *
   59  * A sample code can be seen in the following page:
   60  * - @subpage c_gnssSampleCodeStartStop
   61  *
   62  * @subsubsection le_gnss_StartingMode Starting mode
   63  *
   64  * Starting modes are used only for test purposes and allow start performance measurement.
   65  * @note For more information about start performances, please refer to your specific
   66  * platform documentation.
   67  *
   68  * @subsubsection le_gnss_Data GNSS data
   69  * The following table describes the <b>minimum</b> required data for those starting modes:
   70  *
   71  * | GNSS Data / Starting mode  | HOT  | WARM  | COLD  | FACTORY |
   72  *| -----------------------| -----| ------| ----- | ------- |
   73  *| Broadcasted Ephemeris  | Used |  |  |  |
   74  *| Extended Ephemeris     | Used(1) | Used(2) | Used(2) | Removed (3) |
   75  *| Approximate Time and Position  | Used | Used |  |  |
   76  *| Almanac   | Used | Used | Used | Used (Factory) |
   77  *
   78  * For example, a requested HOT start without valid broadcasted ephemeris will be treated
   79  * as a WARM start.
   80  *
   81  * @note (1) Extended Ephemeris can be used if Broadcasted Ephemeris are not valid.
   82  * The Extended Ephemeris could be loaded using the le_gnss_LoadExtendedEphemerisFile()
   83  * function.
   84  * @note (2) Extended Ephemeris is used if the Extended Ephemeris file is loaded and valid.
   85  * @note (3) Extended Ephemeris are removed when a FACTORY start is requested.
   86  * The Extended Ephemeris could be loaded again using the le_gnss_LoadExtendedEphemerisFile()
   87  * function.
   88  *
   89  * @subsubsection le_gnss_TTFF Time To First Fix (TTFF)
   90  * The le_gnss_GetTtff() function provides the TTFF (first between 2-Dimensional or 3-Dimensional
   91  * position fix) of the last position fix.
   92  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
   93  *
   94  * A sample code can be seen in the following page:
   95  * - @subpage c_gnssSampleCodeReStart
   96  *
   97  * @subsubsection le_gnss_InjectUtcTime Inject UTC time
   98  * The le_gnss_InjectUtcTime() function injects the UTC time into the location engine. Providing an
   99  * accurate UTC time reduces the time to find the first fix.
  100  *
  101  * @subsubsection le_gnss_ForceHotRestart Force HOT restart
  102  * The le_gnss_ForceHotRestart() function performs a "HOT" restart of the GNSS device. The current
  103  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
  104  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
  105  *
  106  * @subsubsection le_gnss_ForceWarmRestart Force WARM restart
  107  * The le_gnss_ForceWarmRestart() function performs a "WARM" restart of the GNSS device. The current
  108  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
  109  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
  110  *
  111  * @subsubsection le_gnss_ForceColdRestart Force COLD restart
  112  * The le_gnss_ForceColdRestart() function performs a "COLD" restart of the GNSS device. The current
  113  * GNSS session is stopped, then started using the available @ref le_gnss_Data.
  114  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
  115  *
  116  * @subsubsection le_gnss_ForceFactoryRestart Force FACTORY restart
  117  * The le_gnss_ForceFactoryRestart() function performs a "FACTORY" restart of the GNSS device.
  118  * The current GNSS session is stopped, then started using the available @ref le_gnss_Data.
  119  * Please refer to @ref le_gnss_APIcallsRequirements. Also see @ref howToGNSS.
  120  *
  121  * @subsection le_gnss_AcquisitionRate Acquisition rate
  122  * The GNSS position is computed and delivered each acquisition rate. The acquisition rate defines
  123  * the time interval that must elapse between two final GPS positions calculation and reports.
  124  * Its default value is 1 second.
  125  * The application can configure/retreive the GNSS device acquisition rate with the
  126  * le_gnss_SetAcquisitionRate() / le_gnss_GetAcquisitionRate() functions.
  127  *
  128  * Please refer to @ref le_gnss_APIcallsRequirements.
  129  *
  130  * A sample code can be seen in the following page:
  131  * - @subpage c_gnssSampleCodeAcquisitionRate
  132  *
  133  * @subsection le_gnss_SetGetConstellation GNSS constellation selection
  134  *
  135  * The le_gnss_SetConstellation() function selects the GNSS constellation(s) used in solution.
  136  * If all GNSS constellations are disabled, the GNSS engine is disabled.
  137  *
  138  * @warning Your platform may require a reboot to take into account this change. Please refer to
  139  * your platform documentation for further details.
  140  *
  141  * Combinations of constellation for GPS, GLONASS, BDS, GALILEO and QZSS satellites are currently
  142  * supported. Constellation for SBAS satellites is not supported.
  143  *
  144  * All supported GNSS constellations are enabled by default.
  145  * The le_gnss_GetConstellation() function gets the GNSS constellation(s) enabled to be used
  146  * in solution.
  147  *
  148  * A sample code can be seen in the following page:
  149  * - @subpage c_gnssSampleCodeConstellation
  150  *
  151  * @subsection le_gnss_SetGetMinElevation GNSS minimum elevation selection
  152  *
  153  * The le_gnss_SetMinElevation() function sets the GNSS minimum elevation.
  154  * Satellites with elevation lower than the minimum elevation will be ignored.
  155  *
  156  * The le_gnss_GetMinElevation() function gets the GNSS minimum elevation.
  157  *
  158  * A sample code can be seen in the following page:
  159  * - @subpage c_gnssSampleCodeMinElevation
  160  *
  161  * @subsection le_gnss_NmeaSentences NMEA sentences selection
  162  *
  163  * The le_gnss_SetNmeaSentences() function selects the enabled NMEA sentences in the
  164  * @ref le_gnss_NMEA with a bit mask. The supported values are listed in @ref le_gnss_NmeaBitMask_t.
  165  *
  166  * @warning Your GNSS device may require a restart to take into account this change.
  167  * Please refer to your platform documentation for further details.
  168  *
  169  * @note All supported NMEA sentences are enabled by default.
  170  *
  171  * The le_gnss_GetNmeaSentences() function gets the bit mask of the enabled NMEA sentences in the
  172  * @ref le_gnss_NMEA.
  173  *
  174  * Please refer to @ref le_gnss_APIcallsRequirements.
  175  *
  176  * A sample code can be seen in the following page:
  177  * - @subpage c_gnssSampleCodeNmeaSentences
  178  *
  179  * @subsection le_gnss_APIcallsRequirements API calls Requirements
  180  * The following table shows the pre-requisites when using the GNSS service API function set.
  181  * ''LE_OK or error code'' means the function is authorized in the corresponding state, the request
  182  * is performed and the result is returned; otherwise the returned error is indicated for each state
  183  *.
  184  * | Function / GNSS state  | UNINITIALIZED  | READY  | ACTIVE  | DISABLED |
  185  *| ----------------------------- | --------------------------- | -----------------------------| --------------------------- | --------------------------- |
  186  *| le_gnss_Start() | LE_NOT_PERMITTED | LE_OK or error code | LE_DUPLICATE | LE_NOT_PERMITTED |
  187  *| le_gnss_Stop() | LE_NOT_PERMITTED | LE_DUPLICATE | LE_OK or error code | LE_NOT_PERMITTED |
  188  *| le_gnss_ForceHotRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
  189  *| le_gnss_ForceWarmRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
  190  *| le_gnss_ForceColdRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
  191  *| le_gnss_ForceFactoryRestart() | LE_NOT_PERMITTED | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED |
  192  *| le_gnss_Disable() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_DUPLICATE |
  193  *| le_gnss_Enable() | LE_NOT_PERMITTED | LE_DUPLICATE | LE_DUPLICATE | LE_OK or error code |
  194  *| le_gnss_SetConstellation() | LE_NOT_PERMITTED |  LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
  195  *| le_gnss_GetConstellation() | LE_NOT_PERMITTED |  LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
  196  *| le_gnss_GetTtff() | LE_NOT_PERMITTED |  LE_OK or error code | LE_OK or error code | LE_NOT_PERMITTED |
  197  *| le_gnss_SetAcquisitionRate() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
  198  *| le_gnss_GetAcquisitionRate() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
  199  *| le_gnss_SetNmeaSentences() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
  200  *| le_gnss_GetNmeaSentences() | LE_NOT_PERMITTED | LE_OK or error code | LE_NOT_PERMITTED | LE_NOT_PERMITTED |
  201  *
  202  * Also see @ref howToGNSS.
  203  *
  204  * @section le_gnss_Information GNSS position information
  205  * @ref le_gnss_NMEA
  206  *
  207  * @ref le_gnss_GetInfo
  208  *
  209  * @subsection le_gnss_NMEA NMEA Flow
  210  * The National Marine Electronics Association (NMEA) standard defines an electrical interface
  211  * and data protocol for communications between marine instrumentation.
  212  *
  213  * The NMEA-0183, scope of this document, defines a set of frame prefixed by
  214  * $GP (concerning Global Positioning System),
  215  * $GL (concerning GLONASS)
  216  * and $GN (concerning combination of navigation systems).
  217  * For more details about NMEA standards, please refer to http://www.nmea.org/.
  218  *
  219  * That NMEA frames flow can be retrieved from the "/dev/nmea" device folder, using for example
  220  * the shell command $<EM> cat /dev/nmea | grep '$G'</EM>
  221  *
  222  * @subsection le_gnss_GetInfo Get position information
  223  * The position information is referenced to a position sample object.
  224  *
  225  * An application can register a handler to be notified of the
  226  * updated position each @ref le_gnss_AcquisitionRate, returning a position sample object.
  227  *
  228  * The GNSS information commonly used such as
  229  * device state, position, time and date, satellites information and accuracy
  230  * can be queried using the following functions:
  231  * - le_gnss_GetState()
  232  * - le_gnss_GetPositionState()
  233  * - le_gnss_GetLocation()
  234  * - le_gnss_GetAltitude()
  235  * - le_gnss_GetDate()
  236  * - le_gnss_GetTime()
  237  * - le_gnss_GetGpsTime()
  238  * - le_gnss_GetGpsLeapSeconds()
  239  * - le_gnss_GetEpochTime()
  240  * - le_gnss_GetTimeAccuracy()
  241  * - le_gnss_GetHorizontalSpeed()
  242  * - le_gnss_GetVerticalSpeed()
  243  * - le_gnss_GetDirection()
  244  * - le_gnss_GetSatellitesInfo()
  245  * - le_gnss_GetSbasConstellationCategory()
  246  * - le_gnss_GetSatellitesStatus()
  247  * - le_gnss_GetDop()
  248  * - le_gnss_GetAltitudeOnWgs84()
  249  * - le_gnss_GetMagneticDeviation()
  250  *
  251  * The handler can be managed using le_gnss_AddPositionHandler()
  252  * and le_gnss_RemovePositionHandler().
  253  * When a position is computed, the handler is called.
  254  *
  255  * The application has to release each position sample object received by the handler,
  256  * using the le_gnss_ReleaseSampleRef().
  257  *
  258  * A sample code can be seen in the following page:
  259  * - @subpage c_gnssSampleCodePosition
  260  *
  261  * @section le_gnss_Assisted_GNSS Assisted GNSS
  262  *
  263  * @ref le_gnss_Assisted_GNSS_EE
  264  * @ref le_gnss_Assisted_GNSS_UP
  265  *
  266  * @subsection le_gnss_Assisted_GNSS_EE Server based Extended Ephemeris
  267  *
  268  * @todo Add detailed documentation.
  269  *
  270  * With le_gnss_LoadExtendedEphemerisFile() , you can load an 'Extended Ephemeris' file into
  271  * the GNSS device from the filesystem.
  272  * You have to download the file before loading it.
  273  * @warning Ensure to check that the downloaded file is supported for your specific platform.
  274  *
  275  * With le_gnss_GetExtendedEphemerisValidity(), you will to get the validity of the last injected
  276  * Extended Ephemeris.
  277  *
  278  * You can enable/disable the use of the 'Extended Ephemeris' file into the GNSS device with
  279  * le_gnss_EnableExtendedEphemerisFile() / le_gnss_DisableExtendedEphemerisFile() functions.
  280  * @warning Ensure to check configuration capabilities for your specific platform.
  281  * A reboot must be required if your platform doesn't allow run-time configuration.
  282  *
  283  * A sample code can be seen in the following page:
  284  * - @subpage c_gnssSampleCodeXtra
  285  *
  286  * @subsection le_gnss_Assisted_GNSS_UP 3GPP User Plane (OMA SUPL)
  287  *
  288  * That 3GPP User Plane A-GNSS (Assisted GNSS) protocol is defined by two different standardization
  289  * bodies, 3GPP and Open Mobile Alliance (OMA). For more information, please refer to the standard.
  290  *
  291  * Both MS-Assisted and MS-Based position determination methods are supported in the User Plane.
  292  *
  293  * In MS-Assisted mode, the MS (Mobile Station) measures the signals from the GNSS satellites
  294  *, then returns the retrieved GNSS data to the SUPL (Secure User Plan Location) server, where the
  295  * position calculation is performed.
  296  *
  297  * In MS-Based mode, the MS gets the assistance data from the SUPL (Secure User Plan Location)
  298  * server. The MS measures the signals from the GNSS satellites and makes the position calculation.
  299  *
  300  * The data transport over User Plan is done using the TCP/IP protocol.
  301  *
  302  * The Assisted-GNSS mode can be configured thru the le_gnss_SetSuplAssistedMode() function.
  303  *
  304  * The supported modes are the following:
  305  * - Standalone mode: That 3GPP User Plane A-GNSS feature is deactivated.
  306  * - MS-Based mode
  307  * - MS-Assisted mode
  308  *
  309  * Moreover, the le_gnss_GetSuplAssistedMode() function reads the configured Assisted-GNSS mode.
  310  *
  311  * The SUPL server is configured using the le_gnss_SetSuplServerUrl() function. That function sets
  312  * the SUPL server URL and optionally the port number.
  313  *
  314  * The SUPL certificate to be used in A-GNSS sessions is injected through the
  315  * le_gnss_InjectSuplCertificate() function and deleted through the le_gnss_DeleteSuplCertificate()
  316  * function.
  317  * The SUPL certificate lenght given as parameter to le_gnss_InjectSuplCertificate() must be less
  318  * than LE_GNSS_SUPL_CERTIFICATE_MAX_LEN.
  319  *
  320  * <HR>
  321  *
  322  * Copyright (C) Sierra Wireless Inc.
  323  */
  324 /**
  325  * @page c_gnssSampleCode Sample code for GNSS device
  326  *
  327  * @include "apps/test/positioning/gnssTest/gnssTest/gnssTest.c"
  328  */
  329 /**
  330  * @page c_gnssSampleCodeEnableDisable Sample code for Enable/Disable GNSS device
  331  *
  332  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssEnable
  333  */
  334 /**
  335  * @page c_gnssSampleCodeStartStop Sample code for Start/Stop GNSS device
  336  *
  337  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
  338  */
  339 /**
  340  * @page c_gnssSampleCodeReStart Sample code for restart GNSS device and get TTFF
  341  *
  342  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssReStart
  343  */
  344 /**
  345  * @page c_gnssSampleCodeAcquisitionRate Sample code for GNSS acquisition rate configuration
  346  *
  347  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
  348  */
  349 /**
  350  * @page c_gnssSampleCodeConstellation Sample code for GNSS constellation selection
  351  *
  352  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
  353  */
  354 /**
  355  * @page c_gnssSampleCodeMinElevation Sample code for GNSS minimum elevation
  356  *
  357  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
  358  */
  359 /**
  360  * @page c_gnssSampleCodeNmeaSentences Sample code for GNSS NMEA sentences selection
  361  *
  362  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssControl
  363  */
  364 /**
  365  * @page c_gnssSampleCodePosition Sample code for GNSS position information
  366  *
  367  * @snippet "apps/test/positioning/gnssTest/gnssTest/gnssTest.c" GnssPosition
  368  */
  369 /**
  370  * @page c_gnssSampleCodeXtra Sample code for GNSS Server based Extended Ephemeris
  371  *
  372  * @include "apps/test/positioning/gnssXtraTest/gnssXtraTest/xtraTest.c"
  373  */
  374 /**
  375  * @file le_gnss_interface.h
  376  *
  377  * Legato @ref c_gnss include file.
  378  *
  379  * Copyright (C) Sierra Wireless Inc.
  380  */
  381 
  382 #ifndef LE_GNSS_INTERFACE_H_INCLUDE_GUARD
  383 #define LE_GNSS_INTERFACE_H_INCLUDE_GUARD
  384 
  385 
  386 #include "legato.h"
  387 
  388 
  389 //--------------------------------------------------------------------------------------------------
  390 /**
  391  * Type for handler called when a server disconnects.
  392  */
  393 //--------------------------------------------------------------------------------------------------
  394 typedef void (*le_gnss_DisconnectHandler_t)(void *);
  395 
  396 //--------------------------------------------------------------------------------------------------
  397 /**
  398  *
  399  * Connect the current client thread to the service providing this API. Block until the service is
  400  * available.
  401  *
  402  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  403  * called before any other functions in this API.  Normally, ConnectService is automatically called
  404  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  405  *
  406  * This function is created automatically.
  407  */
  408 //--------------------------------------------------------------------------------------------------
  409 void le_gnss_ConnectService
  410 (
  411     void
  412 );
  413 
  414 //--------------------------------------------------------------------------------------------------
  415 /**
  416  *
  417  * Try to connect the current client thread to the service providing this API. Return with an error
  418  * if the service is not available.
  419  *
  420  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  421  * called before any other functions in this API.  Normally, ConnectService is automatically called
  422  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  423  *
  424  * This function is created automatically.
  425  *
  426  * @return
  427  *  - LE_OK if the client connected successfully to the service.
  428  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  429  *    bound.
  430  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  431  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  432  */
  433 //--------------------------------------------------------------------------------------------------
  434 le_result_t le_gnss_TryConnectService
  435 (
  436     void
  437 );
  438 
  439 //--------------------------------------------------------------------------------------------------
  440 /**
  441  * Set handler called when server disconnection is detected.
  442  *
  443  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  444  * to continue without exiting, it should call longjmp() from inside the handler.
  445  */
  446 //--------------------------------------------------------------------------------------------------
  447 void le_gnss_SetServerDisconnectHandler
  448 (
  449     le_gnss_DisconnectHandler_t disconnectHandler,
  450     void *contextPtr
  451 );
  452 
  453 //--------------------------------------------------------------------------------------------------
  454 /**
  455  *
  456  * Disconnect the current client thread from the service providing this API.
  457  *
  458  * Normally, this function doesn't need to be called. After this function is called, there's no
  459  * longer a connection to the service, and the functions in this API can't be used. For details, see
  460  * @ref apiFilesC_client.
  461  *
  462  * This function is created automatically.
  463  */
  464 //--------------------------------------------------------------------------------------------------
  465 void le_gnss_DisconnectService
  466 (
  467     void
  468 );
  469 
  470 
  471 //--------------------------------------------------------------------------------------------------
  472 /**
  473  * Maximum length of the SUP Server URL string.
  474  */
  475 //--------------------------------------------------------------------------------------------------
  476 #define LE_GNSS_SUPL_SERVER_URL_MAX_LEN 256
  477 
  478 //--------------------------------------------------------------------------------------------------
  479 /**
  480  * Maximum length of the SUP Server URL string.
  481  * One extra byte is added for the null character.
  482  */
  483 //--------------------------------------------------------------------------------------------------
  484 #define LE_GNSS_SUPL_SERVER_URL_MAX_BYTES 257
  485 
  486 //--------------------------------------------------------------------------------------------------
  487 /**
  488  * Maximum SUPL certificate size.
  489  */
  490 //--------------------------------------------------------------------------------------------------
  491 #define LE_GNSS_SUPL_CERTIFICATE_MAX_LEN 2000
  492 
  493 //--------------------------------------------------------------------------------------------------
  494 /**
  495  * Maximum SUPL certificate string size.
  496  * One extra byte is added for the null character.
  497  */
  498 //--------------------------------------------------------------------------------------------------
  499 #define LE_GNSS_SUPL_CERTIFICATE_MAX_BYTES 2001
  500 
  501 //--------------------------------------------------------------------------------------------------
  502 /**
  503  * Define the maximum length of the Satellites Vehicle information list
  504  */
  505 //--------------------------------------------------------------------------------------------------
  506 #define LE_GNSS_SV_INFO_MAX_LEN 80
  507 
  508 //--------------------------------------------------------------------------------------------------
  509 /**
  510  * Define the maximal bit mask for enabled NMEA sentences
  511  *
  512  * @note This maximal value should be coherent with @ref le_gnss_NmeaBitMask_t
  513  */
  514 //--------------------------------------------------------------------------------------------------
  515 #define LE_GNSS_NMEA_SENTENCES_MAX 32767
  516 
  517 //--------------------------------------------------------------------------------------------------
  518 /**
  519  * Define the maximal degree for the minimal elevation
  520  */
  521 //--------------------------------------------------------------------------------------------------
  522 #define LE_GNSS_MIN_ELEVATION_MAX_DEGREE 90
  523 
  524 //--------------------------------------------------------------------------------------------------
  525 /**
  526  *  Reference type for dealing with GNSS position samples.
  527  */
  528 //--------------------------------------------------------------------------------------------------
  529 typedef struct le_gnss_Sample* le_gnss_SampleRef_t;
  530 
  531 
  532 //--------------------------------------------------------------------------------------------------
  533 /**
  534  * Enumeration for GNSS device state
  535  */
  536 //--------------------------------------------------------------------------------------------------
  537 typedef enum
  538 {
  539     LE_GNSS_STATE_UNINITIALIZED = 0,
  540         ///< The GNSS device is not initialized
  541     LE_GNSS_STATE_READY = 1,
  542         ///< The GNSS device is ready
  543     LE_GNSS_STATE_ACTIVE = 2,
  544         ///< The GNSS device is active
  545     LE_GNSS_STATE_DISABLED = 3,
  546         ///< The GNSS device is disabled
  547     LE_GNSS_STATE_MAX = 4
  548         ///< Do not use
  549 }
  550 le_gnss_State_t;
  551 
  552 
  553 //--------------------------------------------------------------------------------------------------
  554 /**
  555  *  GNSS fix position states.
  556  */
  557 //--------------------------------------------------------------------------------------------------
  558 typedef enum
  559 {
  560     LE_GNSS_STATE_FIX_NO_POS = 0,
  561         ///< The GNSS fix position is not fixed.
  562     LE_GNSS_STATE_FIX_2D = 1,
  563         ///< 2-Dimensional position fix.
  564     LE_GNSS_STATE_FIX_3D = 2,
  565         ///< 3-Dimensional position fix.
  566     LE_GNSS_STATE_FIX_ESTIMATED = 3
  567         ///< Estimated (i.e. forward predicted) position fix.
  568 }
  569 le_gnss_FixState_t;
  570 
  571 
  572 //--------------------------------------------------------------------------------------------------
  573 /**
  574  *  SBAS constellation category
  575  */
  576 //--------------------------------------------------------------------------------------------------
  577 typedef enum
  578 {
  579     LE_GNSS_SBAS_EGNOS = 0,
  580         ///< Satellite Vehicle of Satellite-based augmentation system
  581         ///< (SBAS) EGNOS constellation.
  582     LE_GNSS_SBAS_WAAS = 1,
  583         ///< Satellite Vehicle of Satellite-based augmentation system
  584         ///< (SBAS) WAAS constellation.
  585     LE_GNSS_SBAS_GAGAN = 2,
  586         ///< Satellite Vehicle of Satellite-based augmentation system
  587         ///< (SBAS) GAGAN constellation.
  588     LE_GNSS_SBAS_MSAS = 3,
  589         ///< Satellite Vehicle of Satellite-based augmentation system
  590         ///< (SBAS) MSAS constellation.
  591     LE_GNSS_SBAS_UNKNOWN = 4
  592         ///< Satellite Vehicle of Satellite-based augmentation system
  593         ///< (SBAS) unknown constellation.
  594 }
  595 le_gnss_SbasConstellationCategory_t;
  596 
  597 
  598 //--------------------------------------------------------------------------------------------------
  599 /**
  600  *  GNSS constellation type.
  601  */
  602 //--------------------------------------------------------------------------------------------------
  603 typedef enum
  604 {
  605     LE_GNSS_SV_CONSTELLATION_UNDEFINED = 0,
  606         ///< GNSS constellation field not defined.
  607     LE_GNSS_SV_CONSTELLATION_GPS = 1,
  608         ///< Satellite Vehicle of GPS constellation.
  609         ///< North American satellite navigation system
  610     LE_GNSS_SV_CONSTELLATION_SBAS = 2,
  611         ///< Satellite Vehicle of SBAS constellation.
  612         ///< Satellite-based augmentation system
  613     LE_GNSS_SV_CONSTELLATION_GLONASS = 3,
  614         ///< Satellite Vehicle of Glonass constellation.
  615         ///< Russian satellite navigation system
  616     LE_GNSS_SV_CONSTELLATION_GALILEO = 4,
  617         ///< Satellite Vehicle of Galileo constellation.
  618         ///< European Union satellite navigation system
  619     LE_GNSS_SV_CONSTELLATION_BEIDOU = 5,
  620         ///< Satellite Vehicle of Beidou constellation.
  621         ///< Chinese satellite navigation system
  622     LE_GNSS_SV_CONSTELLATION_QZSS = 6,
  623         ///< Satellite Vehicle of QZSS constellation.
  624         ///< Japanese satellite navigation system
  625     LE_GNSS_SV_CONSTELLATION_MAX = 7
  626         ///< Maximum value.
  627 }
  628 le_gnss_Constellation_t;
  629 
  630 
  631 //--------------------------------------------------------------------------------------------------
  632 /**
  633  * Assisted-GNSS mode
  634  */
  635 //--------------------------------------------------------------------------------------------------
  636 typedef enum
  637 {
  638     LE_GNSS_STANDALONE_MODE = 0,
  639         ///< Standalone mode
  640     LE_GNSS_MS_BASED_MODE = 1,
  641         ///< MS-Based mode.
  642     LE_GNSS_MS_ASSISTED_MODE = 2
  643         ///< MS-Assisted mode.
  644 }
  645 le_gnss_AssistedMode_t;
  646 
  647 
  648 //--------------------------------------------------------------------------------------------------
  649 /**
  650  * GNSS constellation Bit Mask (8 bits) indicating the GNSS constellation(s)
  651  * used in solution.
  652  *
  653  */
  654 //--------------------------------------------------------------------------------------------------
  655 typedef enum
  656 {
  657     LE_GNSS_CONSTELLATION_GPS = 0x1,        ///< GPS constellation used in solution.
  658         ///< North American satellite navigation system
  659     LE_GNSS_CONSTELLATION_GLONASS = 0x2,        ///< GLONASS constellation used in solution.
  660         ///< Russian satellite navigation system
  661     LE_GNSS_CONSTELLATION_BEIDOU = 0x4,        ///< BEIDOU constellation used in solution.
  662         ///< Chinese satellite navigation system
  663     LE_GNSS_CONSTELLATION_GALILEO = 0x8,        ///< GALILEO constellation used in solution.
  664         ///< European Union satellite navigation system
  665     LE_GNSS_CONSTELLATION_SBAS = 0x10,        ///< SBAS constellation used in solution.
  666     LE_GNSS_CONSTELLATION_QZSS = 0x20        ///< QZSS constellation used in solution.
  667         ///< Japanese satellite navigation system
  668 }
  669 le_gnss_ConstellationBitMask_t;
  670 
  671 
  672 //--------------------------------------------------------------------------------------------------
  673 /**
  674  * NMEA sentences Bit Mask indicating the NMEA sentences enabled in the NMEA flow.
  675  *
  676  * @warning The supported NMEA sentences depend on the platform. Please refer to your platform
  677  * documentation for further details.
  678  *
  679  * @note The bit mask values should be coherent with @ref LE_GNSS_NMEA_SENTENCES_MAX
  680  */
  681 //--------------------------------------------------------------------------------------------------
  682 typedef enum
  683 {
  684     LE_GNSS_NMEA_MASK_GPGGA = 0x1,        ///< GPGGA type enabled: GPS fix data.
  685     LE_GNSS_NMEA_MASK_GPGSA = 0x2,        ///< GPGSA type enabled: GPS DOP and active satellites.
  686     LE_GNSS_NMEA_MASK_GPGSV = 0x4,        ///< GPGSV type enabled: GPS satellites in view.
  687     LE_GNSS_NMEA_MASK_GPRMC = 0x8,        ///< GPRMC type enabled: GPS recommended minimum data.
  688     LE_GNSS_NMEA_MASK_GPVTG = 0x10,        ///< GPVTG type enabled: GPS vector track and speed over the ground.
  689     LE_GNSS_NMEA_MASK_GLGSV = 0x20,        ///< GLGSV type enabled: GLONASS satellites in view.
  690     LE_GNSS_NMEA_MASK_GNGNS = 0x40,        ///< GNGNS type enabled: GNSS fix data.
  691     LE_GNSS_NMEA_MASK_GNGSA = 0x80,        ///< GNGSA type enabled: GNSS DOP and active satellites.
  692     LE_GNSS_NMEA_MASK_GAGGA = 0x100,        ///< GAGGA type enabled: Galileo fix data.
  693     LE_GNSS_NMEA_MASK_GAGSA = 0x200,        ///< GAGSA type enabled: Galileo DOP and active satellites.
  694     LE_GNSS_NMEA_MASK_GAGSV = 0x400,        ///< GAGSV type enabled: Galileo satellites in view.
  695     LE_GNSS_NMEA_MASK_GARMC = 0x800,        ///< GARMC type enabled: Galileo recommended minimum data.
  696     LE_GNSS_NMEA_MASK_GAVTG = 0x1000,        ///< GAVTG type enabled: Galileo vector track and speed over the ground.
  697     LE_GNSS_NMEA_MASK_PSTIS = 0x2000,        ///< PSTIS type enabled: GPS session start indication.
  698     LE_GNSS_NMEA_MASK_PQXFI = 0x4000        ///< PQXFI type enabled: Proprietary Qualcomm eXtended Fix Information.
  699 }
  700 le_gnss_NmeaBitMask_t;
  701 
  702 
  703 //--------------------------------------------------------------------------------------------------
  704 /**
  705  * Reference type used by Add/Remove functions for EVENT 'le_gnss_Position'
  706  */
  707 //--------------------------------------------------------------------------------------------------
  708 typedef struct le_gnss_PositionHandler* le_gnss_PositionHandlerRef_t;
  709 
  710 
  711 //--------------------------------------------------------------------------------------------------
  712 /**
  713  * Handler for position information.
  714  *
  715  */
  716 //--------------------------------------------------------------------------------------------------
  717 typedef void (*le_gnss_PositionHandlerFunc_t)
  718 (
  719     le_gnss_SampleRef_t positionSampleRef,
  720         ///< Position's sample reference
  721     void* contextPtr
  722         ///<
  723 );
  724 
  725 //--------------------------------------------------------------------------------------------------
  726 /**
  727  * Set the GNSS constellation bit mask
  728  *
  729  * @return
  730  *  - LE_FAULT         The function failed.
  731  *  - LE_UNSUPPORTED   If the request is not supported.
  732  *  - LE_NOT_PERMITTED If the GNSS device is not initialized, disabled or active.
  733  *  - LE_OK            The function succeeded.
  734  */
  735 //--------------------------------------------------------------------------------------------------
  736 le_result_t le_gnss_SetConstellation
  737 (
  738     le_gnss_ConstellationBitMask_t constellationMask
  739         ///< [IN] GNSS constellation used in solution.
  740 );
  741 
  742 //--------------------------------------------------------------------------------------------------
  743 /**
  744  * Get the GNSS constellation bit mask
  745  *
  746  * @return
  747  *  - LE_OK on success
  748  *  - LE_FAULT on failure
  749  */
  750 //--------------------------------------------------------------------------------------------------
  751 le_result_t le_gnss_GetConstellation
  752 (
  753     le_gnss_ConstellationBitMask_t* constellationMaskPtr
  754         ///< [OUT] GNSS constellation used in solution.
  755 );
  756 
  757 //--------------------------------------------------------------------------------------------------
  758 /**
  759  * This function enables the use of the 'Extended Ephemeris' file into the GNSS device.
  760  *
  761  * @return
  762  *  - LE_FAULT         The function failed.
  763  *  - LE_OK            The function succeeded.
  764  *
  765  */
  766 //--------------------------------------------------------------------------------------------------
  767 le_result_t le_gnss_EnableExtendedEphemerisFile
  768 (
  769     void
  770 );
  771 
  772 //--------------------------------------------------------------------------------------------------
  773 /**
  774  * This function disables the use of the 'Extended Ephemeris' file into the GNSS device.
  775  *
  776  * @return
  777  *  - LE_FAULT         The function failed.
  778  *  - LE_OK            The function succeeded.
  779  *
  780  */
  781 //--------------------------------------------------------------------------------------------------
  782 le_result_t le_gnss_DisableExtendedEphemerisFile
  783 (
  784     void
  785 );
  786 
  787 //--------------------------------------------------------------------------------------------------
  788 /**
  789  * This function must be called to load an 'Extended Ephemeris' file into the GNSS device.
  790  *
  791  * @return
  792  *  - LE_FAULT         The function failed to inject the 'Extended Ephemeris' file.
  793  *  - LE_TIMEOUT       A time-out occurred.
  794  *  - LE_FORMAT_ERROR  'Extended Ephemeris' file format error.
  795  *  - LE_OK            The function succeeded.
  796  *
  797  */
  798 //--------------------------------------------------------------------------------------------------
  799 le_result_t le_gnss_LoadExtendedEphemerisFile
  800 (
  801     int fd
  802         ///< [IN] Extended ephemeris file descriptor
  803 );
  804 
  805 //--------------------------------------------------------------------------------------------------
  806 /**
  807  * This function must be called to get the validity of the last injected Extended Ephemeris.
  808  *
  809  * @return
  810  *  - LE_FAULT         The function failed to get the validity
  811  *  - LE_OK            The function succeeded.
  812  *
  813  */
  814 //--------------------------------------------------------------------------------------------------
  815 le_result_t le_gnss_GetExtendedEphemerisValidity
  816 (
  817     uint64_t* startTimePtr,
  818         ///< [OUT] Start time in seconds (since Jan. 1, 1970)
  819     uint64_t* stopTimePtr
  820         ///< [OUT] Stop time in seconds (since Jan. 1, 1970)
  821 );
  822 
  823 //--------------------------------------------------------------------------------------------------
  824 /**
  825  * This function must be called to inject the UTC time into the GNSS device.
  826  *
  827  * @return
  828  *  - LE_OK            The function succeeded.
  829  *  - LE_FAULT         The function failed to inject the UTC time.
  830  *  - LE_TIMEOUT       A time-out occurred.
  831  *
  832  */
  833 //--------------------------------------------------------------------------------------------------
  834 le_result_t le_gnss_InjectUtcTime
  835 (
  836     uint64_t timeUtc,
  837         ///< [IN] [IN] UTC time since Jan. 1, 1970 in milliseconds
  838     uint32_t timeUnc
  839         ///< [IN] [IN] Time uncertainty in milliseconds
  840 );
  841 
  842 //--------------------------------------------------------------------------------------------------
  843 /**
  844  * This function starts the GNSS device.
  845  *
  846  * @return
  847  *  - LE_FAULT         The function failed.
  848  *  - LE_DUPLICATE     If the GNSS device is already started.
  849  *  - LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
  850  *  - LE_OK            The function succeeded.
  851  *
  852  */
  853 //--------------------------------------------------------------------------------------------------
  854 le_result_t le_gnss_Start
  855 (
  856     void
  857 );
  858 
  859 //--------------------------------------------------------------------------------------------------
  860 /**
  861  * This function stops the GNSS device.
  862  *
  863  * @return
  864  *  - LE_FAULT         The function failed.
  865  *  - LE_DUPLICATE     If the GNSS device is already stopped.
  866  *  - LE_NOT_PERMITTED If the GNSS device is not initialized or disabled.
  867  *  - LE_OK            The function succeeded.
  868  *
  869  */
  870 //--------------------------------------------------------------------------------------------------
  871 le_result_t le_gnss_Stop
  872 (
  873     void
  874 );
  875 
  876 //--------------------------------------------------------------------------------------------------
  877 /**
  878  * This function performs a "HOT" restart of the GNSS device.
  879  *
  880  * @return
  881  *  - LE_FAULT         The function failed.
  882  *  - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
  883  *  - LE_OK            The function succeeded.
  884  *
  885  */
  886 //--------------------------------------------------------------------------------------------------
  887 le_result_t le_gnss_ForceHotRestart
  888 (
  889     void
  890 );
  891 
  892 //--------------------------------------------------------------------------------------------------
  893 /**
  894  * This function performs a "WARM" restart of the GNSS device.
  895  *
  896  * @return
  897  *  - LE_FAULT         The function failed.
  898  *  - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
  899  *  - LE_OK            The function succeeded.
  900  *
  901  */
  902 //--------------------------------------------------------------------------------------------------
  903 le_result_t le_gnss_ForceWarmRestart
  904 (
  905     void
  906 );
  907 
  908 //--------------------------------------------------------------------------------------------------
  909 /**
  910  * This function performs a "COLD" restart of the GNSS device.
  911  *
  912  * @return
  913  *  - LE_FAULT         The function failed.
  914  *  - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
  915  *  - LE_OK            The function succeeded.
  916  *
  917  */
  918 //--------------------------------------------------------------------------------------------------
  919 le_result_t le_gnss_ForceColdRestart
  920 (
  921     void
  922 );
  923 
  924 //--------------------------------------------------------------------------------------------------
  925 /**
  926  * This function performs a "FACTORY" restart of the GNSS device.
  927  *
  928  * @return
  929  *  - LE_FAULT         The function failed.
  930  *  - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
  931  *  - LE_OK            The function succeeded.
  932  *
  933  */
  934 //--------------------------------------------------------------------------------------------------
  935 le_result_t le_gnss_ForceFactoryRestart
  936 (
  937     void
  938 );
  939 
  940 //--------------------------------------------------------------------------------------------------
  941 /**
  942  * Get the TTFF in milliseconds
  943  *
  944  * @return
  945  *  - LE_BUSY          The position is not fixed and TTFF can't be measured.
  946  *  - LE_NOT_PERMITTED If the GNSS device is not enabled or not started.
  947  *  - LE_OK            Function succeeded.
  948  *
  949  */
  950 //--------------------------------------------------------------------------------------------------
  951 le_result_t le_gnss_GetTtff
  952 (
  953     uint32_t* ttffPtr
  954         ///< [OUT] TTFF in milliseconds
  955 );
  956 
  957 //--------------------------------------------------------------------------------------------------
  958 /**
  959  * This function enables the GNSS device.
  960  *
  961  * @return
  962  *  - LE_FAULT         The function failed.
  963  *  - LE_DUPLICATE     If the GNSS device is already enabled.
  964  *  - LE_NOT_PERMITTED If the GNSS device is not initialized.
  965  *  - LE_OK            The function succeeded.
  966  *
  967  */
  968 //--------------------------------------------------------------------------------------------------
  969 le_result_t le_gnss_Enable
  970 (
  971     void
  972 );
  973 
  974 //--------------------------------------------------------------------------------------------------
  975 /**
  976  * This function disables the GNSS device.
  977  *
  978  * @return
  979  *  - LE_FAULT         The function failed.
  980  *  - LE_DUPLICATE     If the GNSS device is already disabled.
  981  *  - LE_NOT_PERMITTED If the GNSS device is not initialized or started.
  982  *  - LE_OK            The function succeeded.
  983  *
  984  */
  985 //--------------------------------------------------------------------------------------------------
  986 le_result_t le_gnss_Disable
  987 (
  988     void
  989 );
  990 
  991 //--------------------------------------------------------------------------------------------------
  992 /**
  993  * This function sets the GNSS device acquisition rate.
  994  *
  995  * @return
  996  *  - LE_OK on success
  997  *  - LE_FAULT on failure
  998  *  - LE_UNSUPPORTED request not supported
  999  *  - LE_TIMEOUT a time-out occurred
 1000  *  - LE_NOT_PERMITTED If the GNSS device is not in "ready" state.
 1001  *  - LE_OUT_OF_RANGE  if acquisition rate value is equal to zero
 1002  *
 1003  * @warning This function may be subject to limitations depending on the platform. Please refer to
 1004  *          the @ref platformConstraintsGnss page.
 1005  */
 1006 //--------------------------------------------------------------------------------------------------
 1007 le_result_t le_gnss_SetAcquisitionRate
 1008 (
 1009     uint32_t rate
 1010         ///< [IN] Acquisition rate in milliseconds.
 1011 );
 1012 
 1013 //--------------------------------------------------------------------------------------------------
 1014 /**
 1015  * This function gets the GNSS device acquisition rate.
 1016  *
 1017  * @return
 1018  *  - LE_OK on success
 1019  *  - LE_FAULT on failure
 1020  *  - LE_NOT_PERMITTED If the GNSS device is not in "ready" state.
 1021  */
 1022 //--------------------------------------------------------------------------------------------------
 1023 le_result_t le_gnss_GetAcquisitionRate
 1024 (
 1025     uint32_t* ratePtr
 1026         ///< [OUT] Acquisition rate in milliseconds.
 1027 );
 1028 
 1029 //--------------------------------------------------------------------------------------------------
 1030 /**
 1031  * Add handler function for EVENT 'le_gnss_Position'
 1032  *
 1033  * This event provides information on position.
 1034  *
 1035  *  - A handler reference, which is only needed for later removal of the handler.
 1036  *
 1037  * @note Doesn't return on failure, so there's no need to check the return value for errors.
 1038  */
 1039 //--------------------------------------------------------------------------------------------------
 1040 le_gnss_PositionHandlerRef_t le_gnss_AddPositionHandler
 1041 (
 1042     le_gnss_PositionHandlerFunc_t handlerPtr,
 1043         ///< [IN]
 1044     void* contextPtr
 1045         ///< [IN]
 1046 );
 1047 
 1048 //--------------------------------------------------------------------------------------------------
 1049 /**
 1050  * Remove handler function for EVENT 'le_gnss_Position'
 1051  */
 1052 //--------------------------------------------------------------------------------------------------
 1053 void le_gnss_RemovePositionHandler
 1054 (
 1055     le_gnss_PositionHandlerRef_t handlerRef
 1056         ///< [IN]
 1057 );
 1058 
 1059 //--------------------------------------------------------------------------------------------------
 1060 /**
 1061  * This function gets the position sample's fix state
 1062  *
 1063  *  - LE_OK on success
 1064  *  - LE_FAULT on failure
 1065  *
 1066  * @note If the caller is passing an invalid Position sample reference into this function,
 1067  *       it is a fatal error, the function will not return.
 1068  */
 1069 //--------------------------------------------------------------------------------------------------
 1070 le_result_t le_gnss_GetPositionState
 1071 (
 1072     le_gnss_SampleRef_t positionSampleRef,
 1073         ///< [IN] Position sample's reference.
 1074     le_gnss_FixState_t* statePtr
 1075         ///< [OUT] Position fix state.
 1076 );
 1077 
 1078 //--------------------------------------------------------------------------------------------------
 1079 /**
 1080  * Get the location's data (Latitude, Longitude, Horizontal accuracy).
 1081  *
 1082  * @return
 1083  *  - LE_FAULT         Function failed to get the location's data
 1084  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid (set to INT32_MAX).
 1085  *  - LE_OK            Function succeeded.
 1086  *
 1087  * @note latitudePtr, longitudePtr, hAccuracyPtr, altitudePtr, vAccuracyPtr can be set to NULL
 1088  *       if not needed.
 1089  *
 1090  * @note: The latitude and longitude values are based on the WGS84 standard coordinate system.
 1091  *
 1092  * @note The latitude and longitude are given in degrees with 6 decimal places like:
 1093  *    Latitude +48858300 = 48.858300 degrees North
 1094  *    Longitude +2294400 = 2.294400 degrees East
 1095  *
 1096  * @note If the caller is passing an invalid Position sample reference into this function,
 1097  *       it is a fatal error, the function will not return.
 1098  */
 1099 //--------------------------------------------------------------------------------------------------
 1100 le_result_t le_gnss_GetLocation
 1101 (
 1102     le_gnss_SampleRef_t positionSampleRef,
 1103         ///< [IN] Position sample's reference.
 1104     int32_t* latitudePtr,
 1105         ///< [OUT] WGS84 Latitude in degrees, positive North [resolution 1e-6].
 1106     int32_t* longitudePtr,
 1107         ///< [OUT] WGS84 Longitude in degrees, positive East [resolution 1e-6].
 1108     int32_t* hAccuracyPtr
 1109         ///< [OUT] Horizontal position's accuracy in meters [resolution 1e-2].
 1110 );
 1111 
 1112 //--------------------------------------------------------------------------------------------------
 1113 /**
 1114  * Get the position sample's altitude.
 1115  *
 1116  * @return
 1117  *  - LE_FAULT         Function failed to get the altitude. Invalid Position reference provided.
 1118  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid (set to INT32_MAX).
 1119  *  - LE_OK            Function succeeded.
 1120  *
 1121  * @note Altitude is in meters, above Mean Sea Level, with 3 decimal places (3047 = 3.047 meters).
 1122  *
 1123  * @note For a 2D position fix, the altitude will be indicated as invalid and set to INT32_MAX
 1124  *
 1125  * @note If the caller is passing an invalid Position reference into this function,
 1126  *       it is a fatal error, the function will not return.
 1127  *
 1128  * @note altitudePtr, altitudeAccuracyPtr can be set to NULL if not needed.
 1129  */
 1130 //--------------------------------------------------------------------------------------------------
 1131 le_result_t le_gnss_GetAltitude
 1132 (
 1133     le_gnss_SampleRef_t positionSampleRef,
 1134         ///< [IN] Position sample's reference.
 1135     int32_t* altitudePtr,
 1136         ///< [OUT] Altitude in meters, above Mean Sea Level [resolution 1e-3].
 1137     int32_t* vAccuracyPtr
 1138         ///< [OUT] Vertical position's accuracy in meters [resolution 1e-1].
 1139 );
 1140 
 1141 //--------------------------------------------------------------------------------------------------
 1142 /**
 1143  * Get the position sample's time.
 1144  *
 1145  * @return
 1146  *  - LE_FAULT         Function failed to get the time.
 1147  *  - LE_OUT_OF_RANGE  The retrieved time is invalid (all fields are set to 0).
 1148  *  - LE_OK            Function succeeded.
 1149  *
 1150  * @note If the caller is passing an invalid Position sample reference into this function,
 1151  *       it is a fatal error, the function will not return.
 1152  */
 1153 //--------------------------------------------------------------------------------------------------
 1154 le_result_t le_gnss_GetTime
 1155 (
 1156     le_gnss_SampleRef_t positionSampleRef,
 1157         ///< [IN] Position sample's reference.
 1158     uint16_t* hoursPtr,
 1159         ///< [OUT] UTC Hours into the day [range 0..23].
 1160     uint16_t* minutesPtr,
 1161         ///< [OUT] UTC Minutes into the hour [range 0..59].
 1162     uint16_t* secondsPtr,
 1163         ///< [OUT] UTC Seconds into the minute [range 0..59].
 1164     uint16_t* millisecondsPtr
 1165         ///< [OUT] UTC Milliseconds into the second [range 0..999].
 1166 );
 1167 
 1168 //--------------------------------------------------------------------------------------------------
 1169 /**
 1170  * Get the position sample's GPS time.
 1171  *
 1172  * @return
 1173  *  - LE_FAULT         Function failed to get the time.
 1174  *  - LE_OUT_OF_RANGE  The retrieved time is invalid (all fields are set to 0).
 1175  *  - LE_OK            Function succeeded.
 1176  *
 1177  * @note If the caller is passing an invalid Position sample reference into this function,
 1178  *       it is a fatal error, the function will not return.
 1179  */
 1180 //--------------------------------------------------------------------------------------------------
 1181 le_result_t le_gnss_GetGpsTime
 1182 (
 1183     le_gnss_SampleRef_t positionSampleRef,
 1184         ///< [IN] Position sample's reference.
 1185     uint32_t* gpsWeekPtr,
 1186         ///< [OUT] GPS week number from midnight, Jan. 6, 1980.
 1187     uint32_t* gpsTimeOfWeekPtr
 1188         ///< [OUT] Amount of time in milliseconds into the GPS week.
 1189 );
 1190 
 1191 //--------------------------------------------------------------------------------------------------
 1192 /**
 1193  *  Get the position sample's epoch time.
 1194  *
 1195  * @return
 1196  *  - LE_FAULT         Function failed to acquire the epoch time.
 1197  *  - LE_OK            Function succeeded.
 1198  *  - LE_OUT_OF_RANGE  The retrieved time is invalid (all fields are set to 0).
 1199  *
 1200  * @note The epoch time is the number of seconds elapsed since January 1, 1970
 1201  *       (midnight UTC/GMT), not counting leaps seconds.
 1202  *
 1203  * @note If the caller is passing an invalid position sample reference into this function,
 1204  *       it is a fatal error, the function will not return.
 1205  */
 1206 //--------------------------------------------------------------------------------------------------
 1207 le_result_t le_gnss_GetEpochTime
 1208 (
 1209     le_gnss_SampleRef_t positionSampleRef,
 1210         ///< [IN] Position sample's reference.
 1211     uint64_t* millisecondsPtr
 1212         ///< [OUT] Milliseconds since Jan. 1, 1970.
 1213 );
 1214 
 1215 //--------------------------------------------------------------------------------------------------
 1216 /**
 1217  * Get the position sample's time accurary.
 1218  *
 1219  * @return
 1220  *  - LE_FAULT         Function failed to get the time.
 1221  *  - LE_OUT_OF_RANGE  The retrieved time accuracy is invalid (set to UINT16_MAX).
 1222  *  - LE_OK            Function succeeded.
 1223  *
 1224  * @note If the caller is passing an invalid Position sample reference into this function,
 1225  *       it is a fatal error, the function will not return.
 1226  */
 1227 //--------------------------------------------------------------------------------------------------
 1228 le_result_t le_gnss_GetTimeAccuracy
 1229 (
 1230     le_gnss_SampleRef_t positionSampleRef,
 1231         ///< [IN] Position sample's reference.
 1232     uint32_t* timeAccuracyPtr
 1233         ///< [OUT] Estimated time accuracy in milliseconds
 1234 );
 1235 
 1236 //--------------------------------------------------------------------------------------------------
 1237 /**
 1238  * Get the position sample's UTC leap seconds in advance
 1239  *
 1240  * @return
 1241  *  - LE_FAULT         Function failed to get the leap seconds.
 1242  *  - LE_OUT_OF_RANGE  The retrieved time accuracy is invalid (set to UINT8_MAX).
 1243  *  - LE_OK            Function succeeded.
 1244  *
 1245  * @note The leap seconds in advance is the accumulated time in seconds since the start of GPS Epoch
 1246  * time (Jan 6, 1980). This value has to be added to the UTC time (since Jan. 1, 1970)
 1247  *
 1248  * @note Insertion of each UTC leap second is usually decided about six months in advance by the
 1249  * International Earth Rotation and Reference Systems Service (IERS).
 1250  *
 1251  * @note If the caller is passing an invalid position sample reference or a null pointer into this
 1252  *       function, it is a fatal error, the function will not return.
 1253  */
 1254 //--------------------------------------------------------------------------------------------------
 1255 le_result_t le_gnss_GetGpsLeapSeconds
 1256 (
 1257     le_gnss_SampleRef_t positionSampleRef,
 1258         ///< [IN] Position sample's reference.
 1259     uint8_t* leapSecondsPtr
 1260         ///< [OUT] UTC leap seconds in advance in seconds
 1261 );
 1262 
 1263 //--------------------------------------------------------------------------------------------------
 1264 /**
 1265  * Get the position sample's date.
 1266  *
 1267  * @return
 1268  *  - LE_FAULT         Function failed to get the date.
 1269  *  - LE_OUT_OF_RANGE  The retrieved date is invalid (all fields are set to 0).
 1270  *  - LE_OK            Function succeeded.
 1271  *
 1272  * @note If the caller is passing an invalid Position sample reference into this function,
 1273  *       it is a fatal error, the function will not return.
 1274  */
 1275 //--------------------------------------------------------------------------------------------------
 1276 le_result_t le_gnss_GetDate
 1277 (
 1278     le_gnss_SampleRef_t positionSampleRef,
 1279         ///< [IN] Position sample's reference.
 1280     uint16_t* yearPtr,
 1281         ///< [OUT] UTC Year A.D. [e.g. 2014].
 1282     uint16_t* monthPtr,
 1283         ///< [OUT] UTC Month into the year [range 1...12].
 1284     uint16_t* dayPtr
 1285         ///< [OUT] UTC Days into the month [range 1...31].
 1286 );
 1287 
 1288 //--------------------------------------------------------------------------------------------------
 1289 /**
 1290  * Get the position sample's horizontal speed.
 1291  *
 1292  *  - LE_FAULT         Function failed to find the positionSample.
 1293  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid (set to UINT32_MAX).
 1294  *  - LE_OK            Function succeeded.
 1295  *
 1296  * @note hSpeedPtr, hSpeedAccuracyPtr can be set to NULL if not needed.
 1297  *
 1298  * @note If the caller is passing an invalid Position sample reference into this function,
 1299  *       it is a fatal error, the function will not return.
 1300  */
 1301 //--------------------------------------------------------------------------------------------------
 1302 le_result_t le_gnss_GetHorizontalSpeed
 1303 (
 1304     le_gnss_SampleRef_t positionSampleRef,
 1305         ///< [IN] Position sample's reference.
 1306     uint32_t* hspeedPtr,
 1307         ///< [OUT] Horizontal speed in meters/second [resolution 1e-2].
 1308     uint32_t* hspeedAccuracyPtr
 1309         ///< [OUT] Horizontal speed's accuracy estimate
 1310         ///< in meters/second [resolution 1e-1].
 1311 );
 1312 
 1313 //--------------------------------------------------------------------------------------------------
 1314 /**
 1315  * Get the position sample's vertical speed.
 1316  *
 1317  * @return
 1318  *  - LE_FAULT         The function failed to find the positionSample.
 1319  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is not valid (set to INT32_MAX).
 1320  *  - LE_OK            The function succeeded.
 1321  *
 1322  * @note vSpeedPtr, vSpeedAccuracyPtr can be set to NULL if not needed.
 1323  *
 1324  * @note For a 2D position Fix, the vertical speed will be indicated as invalid
 1325  * and set to INT32_MAX.
 1326  *
 1327  * @note If the caller is passing an invalid Position sample reference into this function,
 1328  *       it is a fatal error, the function will not return.
 1329  */
 1330 //--------------------------------------------------------------------------------------------------
 1331 le_result_t le_gnss_GetVerticalSpeed
 1332 (
 1333     le_gnss_SampleRef_t positionSampleRef,
 1334         ///< [IN] Position sample's reference.
 1335     int32_t* vspeedPtr,
 1336         ///< [OUT] Vertical speed in meters/second [resolution 1e-2],
 1337         ///< positive up.
 1338     int32_t* vspeedAccuracyPtr
 1339         ///< [OUT] Vertical speed's accuracy estimate
 1340         ///< in meters/second [resolution 1e-1].
 1341 );
 1342 
 1343 //--------------------------------------------------------------------------------------------------
 1344 /**
 1345  * Get the position sample's direction. Direction of movement is the direction that the vehicle or
 1346  * person is actually moving.
 1347  *
 1348  * @return
 1349  *  - LE_FAULT         Function failed to find the positionSample.
 1350  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid (set to UINT32_MAX).
 1351  *  - LE_OK            Function succeeded.
 1352  *
 1353  * @note Direction is given in degrees with 1 decimal place: 1755 = 175,5 degrees.
 1354  *       Direction ranges from 0 to 359.9 degrees, where 0 is True North.
 1355  *
 1356  * @note directionPtr, directionAccuracyPtr can be set to NULL if not needed.
 1357  *
 1358  * @note If the caller is passing an invalid Position sample reference into this function,
 1359  *       it is a fatal error, the function will not return.
 1360  */
 1361 //--------------------------------------------------------------------------------------------------
 1362 le_result_t le_gnss_GetDirection
 1363 (
 1364     le_gnss_SampleRef_t positionSampleRef,
 1365         ///< [IN] Position sample's reference.
 1366     uint32_t* directionPtr,
 1367         ///< [OUT] Direction in degrees [resolution 1e-1].
 1368         ///< Range: 0 to 359.9, where 0 is True North
 1369     uint32_t* directionAccuracyPtr
 1370         ///< [OUT] Direction's accuracy estimate
 1371         ///< in degrees [resolution 1e-1].
 1372 );
 1373 
 1374 //--------------------------------------------------------------------------------------------------
 1375 /**
 1376  * Get the Satellites Vehicle information.
 1377  *
 1378  * @return
 1379  *  - LE_FAULT         Function failed to find the positionSample.
 1380  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid.
 1381  *  - LE_OK            Function succeeded.
 1382  *
 1383  * @note satId[] can be set to 0 if that information list index is not configured, so
 1384  * all satellite parameters (satConst[], satSnr[],satAzim[], satElev[]) are fixed to 0.
 1385  *
 1386  * @note For LE_OUT_OF_RANGE returned code, invalid value depends on field type:
 1387  * UINT16_MAX for satId, LE_GNSS_SV_CONSTELLATION_UNDEFINED for satConst, false for satUsed,
 1388  * UINT8_MAX for satSnr, UINT16_MAX for satAzim, UINT8_MAX for satElev.
 1389  *
 1390  * @note If the caller is passing an invalid Position sample reference into this function,
 1391  *       it is a fatal error, the function will not return.
 1392  */
 1393 //--------------------------------------------------------------------------------------------------
 1394 le_result_t le_gnss_GetSatellitesInfo
 1395 (
 1396     le_gnss_SampleRef_t positionSampleRef,
 1397         ///< [IN] Position sample's reference.
 1398     uint16_t* satIdPtr,
 1399         ///< [OUT] Satellites in View ID number, referring
 1400         ///< to NMEA standard.
 1401     size_t* satIdSizePtr,
 1402         ///< [INOUT]
 1403     le_gnss_Constellation_t* satConstPtr,
 1404         ///< [OUT] GNSS constellation type.
 1405     size_t* satConstSizePtr,
 1406         ///< [INOUT]
 1407     bool* satUsedPtr,
 1408         ///< [OUT] TRUE if satellite in View Used
 1409         ///< for Navigation.
 1410     size_t* satUsedSizePtr,
 1411         ///< [INOUT]
 1412     uint8_t* satSnrPtr,
 1413         ///< [OUT] Satellites in View Signal To
 1414         ///< Noise Ratio [dBHz].
 1415     size_t* satSnrSizePtr,
 1416         ///< [INOUT]
 1417     uint16_t* satAzimPtr,
 1418         ///< [OUT] Satellites in View Azimuth [degrees].
 1419         ///< Range: 0 to 360
 1420         ///< If Azimuth angle is currently unknown,
 1421         ///< the value is set to UINT16_MAX.
 1422     size_t* satAzimSizePtr,
 1423         ///< [INOUT]
 1424     uint8_t* satElevPtr,
 1425         ///< [OUT] Satellites in View Elevation [degrees].
 1426         ///< Range: 0 to 90
 1427         ///< If Elevation angle is currently unknown,
 1428         ///< the value is set to UINT8_MAX.
 1429     size_t* satElevSizePtr
 1430         ///< [INOUT]
 1431 );
 1432 
 1433 //--------------------------------------------------------------------------------------------------
 1434 /**
 1435  * Get the SBAS constellation category
 1436  *
 1437  */
 1438 //--------------------------------------------------------------------------------------------------
 1439 le_gnss_SbasConstellationCategory_t le_gnss_GetSbasConstellationCategory
 1440 (
 1441     uint16_t satId
 1442         ///< [IN] Satellites in View ID number, referring
 1443         ///< to NMEA standard.
 1444 );
 1445 
 1446 //--------------------------------------------------------------------------------------------------
 1447 /**
 1448  * Get the Satellites Vehicle status.
 1449  *
 1450  * @return
 1451  *  - LE_FAULT         Function failed to find the positionSample.
 1452  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid.
 1453  *  - LE_OK            Function succeeded.
 1454  *
 1455  * @note If the caller is passing an invalid Position sample reference into this function,
 1456  *       it is a fatal error, the function will not return.
 1457  */
 1458 //--------------------------------------------------------------------------------------------------
 1459 le_result_t le_gnss_GetSatellitesStatus
 1460 (
 1461     le_gnss_SampleRef_t positionSampleRef,
 1462         ///< [IN] Position sample's reference.
 1463     uint8_t* satsInViewCountPtr,
 1464         ///< [OUT] Number of satellites expected to be in view.
 1465     uint8_t* satsTrackingCountPtr,
 1466         ///< [OUT] Number of satellites in view, when tracking.
 1467     uint8_t* satsUsedCountPtr
 1468         ///< [OUT] Number of satellites in view used for Navigation.
 1469 );
 1470 
 1471 //--------------------------------------------------------------------------------------------------
 1472 /**
 1473  * Get the DOP parameters (Dilution Of Precision) for the fixed position.
 1474  *
 1475  * @return
 1476  *  - LE_FAULT         Function failed to find the positionSample.
 1477  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid (set to INT16_MAX).
 1478  *  - LE_OK            Function succeeded.
 1479  *
 1480  * @note The DOP values are given with 3 decimal places like: DOP value 2200 = 2.200
 1481  *
 1482  * @note If the caller is passing an invalid Position sample reference into this function,
 1483  *       it is a fatal error, the function will not return.
 1484  */
 1485 //--------------------------------------------------------------------------------------------------
 1486 le_result_t le_gnss_GetDop
 1487 (
 1488     le_gnss_SampleRef_t positionSampleRef,
 1489         ///< [IN] Position sample's reference.
 1490     uint16_t* hdopPtr,
 1491         ///< [OUT] Horizontal Dilution of Precision [resolution 1e-3].
 1492     uint16_t* vdopPtr,
 1493         ///< [OUT] Vertical Dilution of Precision [resolution 1e-3].
 1494     uint16_t* pdopPtr
 1495         ///< [OUT] Position Dilution of Precision [resolution 1e-3].
 1496 );
 1497 
 1498 //--------------------------------------------------------------------------------------------------
 1499 /**
 1500  * Get the position sample's altitude with respect to the WGS-84 ellipsoid
 1501  *
 1502  * @return
 1503  *  - LE_FAULT         Function failed to get the altitude.
 1504  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid (set to INT32_MAX).
 1505  *  - LE_OK            Function succeeded.
 1506  *
 1507  * @note altitudeOnWgs84 is in meters, between WGS-84 earth ellipsoid and mean sea level
 1508  *       with 3 decimal places (3047 = 3.047 meters).
 1509  *
 1510  * @note For a 2D position fix, the altitude with respect to the WGS-84 ellipsoid will be indicated
 1511  *       as invalid and set to INT32_MAX.
 1512  *
 1513  * @note If the caller is passing an invalid Position reference into this function,
 1514  *       it is a fatal error, the function will not return.
 1515  */
 1516 //--------------------------------------------------------------------------------------------------
 1517 le_result_t le_gnss_GetAltitudeOnWgs84
 1518 (
 1519     le_gnss_SampleRef_t positionSampleRef,
 1520         ///< [IN] Position sample's reference.
 1521     int32_t* altitudeOnWgs84Ptr
 1522         ///< [OUT] Altitude in meters, between WGS-84 earth ellipsoid
 1523         ///< and mean sea level [resolution 1e-3].
 1524 );
 1525 
 1526 //--------------------------------------------------------------------------------------------------
 1527 /**
 1528  * Get the position sample's magnetic deviation. It is the difference between the bearing to
 1529  * true north and the bearing shown on a magnetic compass. The deviation is positive when the
 1530  * magnetic north is east of true north.
 1531  *
 1532  * @return
 1533  *  - LE_FAULT         Function failed to find the positionSample.
 1534  *  - LE_OUT_OF_RANGE  One of the retrieved parameter is invalid (set to INT32_MAX).
 1535  *  - LE_OK            Function succeeded.
 1536  *
 1537  * @note magneticDeviation is in degrees, with 1 decimal places (47 = 4.7 degree).
 1538  *
 1539  * @note If the caller is passing an invalid Position sample reference into this function,
 1540  *       it is a fatal error, the function will not return.
 1541  */
 1542 //--------------------------------------------------------------------------------------------------
 1543 le_result_t le_gnss_GetMagneticDeviation
 1544 (
 1545     le_gnss_SampleRef_t positionSampleRef,
 1546         ///< [IN] Position sample's reference.
 1547     int32_t* magneticDeviationPtr
 1548         ///< [OUT] MagneticDeviation in degrees [resolution 1e-1].
 1549 );
 1550 
 1551 //--------------------------------------------------------------------------------------------------
 1552 /**
 1553  * This function gets the last updated position sample object reference.
 1554  *
 1555  * @return A reference to last Position's sample.
 1556  *
 1557  * @note
 1558  *      On failure, the process exits, so you don't have to worry about checking the returned
 1559  *      reference for validity.
 1560  */
 1561 //--------------------------------------------------------------------------------------------------
 1562 le_gnss_SampleRef_t le_gnss_GetLastSampleRef
 1563 (
 1564     void
 1565 );
 1566 
 1567 //--------------------------------------------------------------------------------------------------
 1568 /**
 1569  * This function must be called to release the position sample.
 1570  *
 1571  * @note If the caller is passing an invalid Position sample reference into this function,
 1572  *       it is a fatal error, the function will not return.
 1573  */
 1574 //--------------------------------------------------------------------------------------------------
 1575 void le_gnss_ReleaseSampleRef
 1576 (
 1577     le_gnss_SampleRef_t positionSampleRef
 1578         ///< [IN] Position sample's reference.
 1579 );
 1580 
 1581 //--------------------------------------------------------------------------------------------------
 1582 /**
 1583  * This function sets the SUPL Assisted-GNSS mode.
 1584  *
 1585  * @return
 1586  *  - LE_OK on success
 1587  *  - LE_FAULT on failure
 1588  *  - LE_UNSUPPORTED request not supported
 1589  *  - LE_TIMEOUT a time-out occurred
 1590  */
 1591 //--------------------------------------------------------------------------------------------------
 1592 le_result_t le_gnss_SetSuplAssistedMode
 1593 (
 1594     le_gnss_AssistedMode_t assistedMode
 1595         ///< [IN] Assisted-GNSS mode.
 1596 );
 1597 
 1598 //--------------------------------------------------------------------------------------------------
 1599 /**
 1600  * This function gets the SUPL Assisted-GNSS mode.
 1601  *
 1602  * @return
 1603  *  - LE_OK on success
 1604  *  - LE_FAULT on failure
 1605  */
 1606 //--------------------------------------------------------------------------------------------------
 1607 le_result_t le_gnss_GetSuplAssistedMode
 1608 (
 1609     le_gnss_AssistedMode_t* assistedModePtr
 1610         ///< [OUT] Assisted-GNSS mode.
 1611 );
 1612 
 1613 //--------------------------------------------------------------------------------------------------
 1614 /**
 1615  * This function sets the SUPL server URL.
 1616  * That server URL is a NULL-terminated string with a maximum string length (including NULL
 1617  * terminator) equal to 256. Optionally the port number is specified after a colon.
 1618  *
 1619  * @return
 1620  *  - LE_OK on success
 1621  *  - LE_FAULT on failure
 1622  *  - LE_BUSY service is busy
 1623  *  - LE_TIMEOUT a time-out occurred
 1624  *
 1625  * @note If the SUPL server URL size is bigger than the maximum string length (including NULL
 1626  * terminator) size, it is a fatal error, the function will not return.
 1627  */
 1628 //--------------------------------------------------------------------------------------------------
 1629 le_result_t le_gnss_SetSuplServerUrl
 1630 (
 1631     const char* suplServerUrl
 1632         ///< [IN] SUPL server URL.
 1633 )
 1634 __attribute__(( nonnull(1) ));
 1635 
 1636 //--------------------------------------------------------------------------------------------------
 1637 /**
 1638  * This function injects the SUPL certificate to be used in A-GNSS sessions. Certificates must
 1639  * be encoded in DER. Other certificate encryptions (e.g., PEM, CER and CRT)
 1640  * aren't supported.
 1641  *
 1642  * @return
 1643  *  - LE_OK on success
 1644  *  - LE_BAD_PARAMETER on invalid parameter
 1645  *  - LE_FAULT on failure
 1646  *  - LE_BUSY service is busy
 1647  *  - LE_TIMEOUT a time-out occurred
 1648  *
 1649  * @note If the SUPL certificate size is bigger than the Maximum SUPL certificate size,
 1650  * it is a fatal error, the function will not return.
 1651  */
 1652 //--------------------------------------------------------------------------------------------------
 1653 le_result_t le_gnss_InjectSuplCertificate
 1654 (
 1655     uint8_t suplCertificateId,
 1656         ///< [IN] ID of the SUPL certificate.
 1657         ///< Certificate ID range is 0 to 9
 1658     uint16_t suplCertificateLen,
 1659         ///< [IN] SUPL certificate size in Bytes.
 1660     const char* suplCertificate
 1661         ///< [IN] SUPL certificate contents.
 1662 )
 1663 __attribute__(( nonnull(3) ));
 1664 
 1665 //--------------------------------------------------------------------------------------------------
 1666 /**
 1667  * This function deletes the SUPL certificate.
 1668  *
 1669  * @return
 1670  *  - LE_OK on success
 1671  *  - LE_BAD_PARAMETER on invalid parameter
 1672  *  - LE_FAULT on failure
 1673  *  - LE_BUSY service is busy
 1674  *  - LE_TIMEOUT a time-out occurred
 1675  */
 1676 //--------------------------------------------------------------------------------------------------
 1677 le_result_t le_gnss_DeleteSuplCertificate
 1678 (
 1679     uint8_t suplCertificateId
 1680         ///< [IN] ID of the SUPL certificate.
 1681         ///< Certificate ID range is 0 to 9
 1682 );
 1683 
 1684 //--------------------------------------------------------------------------------------------------
 1685 /**
 1686  * This function sets the enabled NMEA sentences using a bit mask.
 1687  *
 1688  * @return
 1689  *  - LE_OK             Success
 1690  *  - LE_BAD_PARAMETER  Bit mask exceeds the maximal value
 1691  *  - LE_FAULT          Failure
 1692  *  - LE_BUSY           Service is busy
 1693  *  - LE_TIMEOUT        Timeout occurred
 1694  *  - LE_NOT_PERMITTED  GNSS device is not in "ready" state
 1695  *
 1696  * @warning This function may be subject to limitations depending on the platform. Please refer to
 1697  *          the @ref platformConstraintsGnss page.
 1698  */
 1699 //--------------------------------------------------------------------------------------------------
 1700 le_result_t le_gnss_SetNmeaSentences
 1701 (
 1702     le_gnss_NmeaBitMask_t nmeaMask
 1703         ///< [IN] Bit mask for enabled NMEA sentences.
 1704 );
 1705 
 1706 //--------------------------------------------------------------------------------------------------
 1707 /**
 1708  * This function gets the bit mask for the enabled NMEA sentences.
 1709  *
 1710  * @return
 1711  *  - LE_OK             Success
 1712  *  - LE_FAULT          Failure
 1713  *  - LE_BUSY           Service is busy
 1714  *  - LE_TIMEOUT        Timeout occurred
 1715  *  - LE_NOT_PERMITTED  GNSS device is not in "ready" state
 1716  *
 1717  * @note If the caller is passing an null pointer to this function, it is a fatal error
 1718  *       and the function will not return.
 1719  */
 1720 //--------------------------------------------------------------------------------------------------
 1721 le_result_t le_gnss_GetNmeaSentences
 1722 (
 1723     le_gnss_NmeaBitMask_t* nmeaMaskPtrPtr
 1724         ///< [OUT] Bit mask for enabled NMEA sentences.
 1725 );
 1726 
 1727 //--------------------------------------------------------------------------------------------------
 1728 /**
 1729  * This function returns the status of the GNSS device.
 1730  *
 1731  */
 1732 //--------------------------------------------------------------------------------------------------
 1733 le_gnss_State_t le_gnss_GetState
 1734 (
 1735     void
 1736 );
 1737 
 1738 //--------------------------------------------------------------------------------------------------
 1739 /**
 1740  * This function sets the GNSS minimum elevation.
 1741  *
 1742  * @return
 1743  *  - LE_OK on success
 1744  *  - LE_FAULT on failure
 1745  *  - LE_OUT_OF_RANGE if the minimum elevation is above range
 1746  *  - LE_UNSUPPORTED request not supported
 1747  */
 1748 //--------------------------------------------------------------------------------------------------
 1749 le_result_t le_gnss_SetMinElevation
 1750 (
 1751     uint8_t minElevation
 1752         ///< [IN] Minimum elevation in degrees [range 0..90].
 1753 );
 1754 
 1755 //--------------------------------------------------------------------------------------------------
 1756 /**
 1757  * This function gets the GNSS minimum elevation.
 1758  *
 1759  * @return
 1760  *  - LE_OK on success
 1761  *  - LE_FAULT on failure
 1762  *  - LE_UNSUPPORTED request not supported
 1763  *
 1764  * @note If the caller is passing an null pointer to this function, it is a fatal error
 1765  *       and the function will not return.
 1766  */
 1767 //--------------------------------------------------------------------------------------------------
 1768 le_result_t le_gnss_GetMinElevation
 1769 (
 1770     uint8_t* minElevationPtrPtr
 1771         ///< [OUT] Minimum elevation in degrees [range 0..90].
 1772 );
 1773 
 1774 #endif // LE_GNSS_INTERFACE_H_INCLUDE_GUARD
LE_GNSS_SBAS_EGNOS
Definition: le_gnss_interface.h:579
le_gnss_AssistedMode_t
le_gnss_AssistedMode_t
Definition: le_gnss_interface.h:636
le_gnss_InjectSuplCertificate
le_result_t le_gnss_InjectSuplCertificate(uint8_t suplCertificateId, uint16_t suplCertificateLen, const char *suplCertificate)
le_gnss_GetDirection
le_result_t le_gnss_GetDirection(le_gnss_SampleRef_t positionSampleRef, uint32_t *directionPtr, uint32_t *directionAccuracyPtr)
le_gnss_GetAltitude
le_result_t le_gnss_GetAltitude(le_gnss_SampleRef_t positionSampleRef, int32_t *altitudePtr, int32_t *vAccuracyPtr)
LE_GNSS_STATE_UNINITIALIZED
The GNSS device is not initialized. 
Definition: le_gnss_interface.h:539
le_gnss_SetSuplServerUrl
le_result_t le_gnss_SetSuplServerUrl(const char *suplServerUrl)
le_gnss_GetSbasConstellationCategory
le_gnss_SbasConstellationCategory_t le_gnss_GetSbasConstellationCategory(uint16_t satId)
LE_GNSS_STATE_MAX
Do not use. 
Definition: le_gnss_interface.h:547
le_gnss_GetSatellitesInfo
le_result_t le_gnss_GetSatellitesInfo(le_gnss_SampleRef_t positionSampleRef, uint16_t *satIdPtr, size_t *satIdSizePtr, le_gnss_Constellation_t *satConstPtr, size_t *satConstSizePtr, bool *satUsedPtr, size_t *satUsedSizePtr, uint8_t *satSnrPtr, size_t *satSnrSizePtr, uint16_t *satAzimPtr, size_t *satAzimSizePtr, uint8_t *satElevPtr, size_t *satElevSizePtr)
LE_GNSS_SV_CONSTELLATION_GALILEO
Definition: le_gnss_interface.h:616
le_gnss_GetExtendedEphemerisValidity
le_result_t le_gnss_GetExtendedEphemerisValidity(uint64_t *startTimePtr, uint64_t *stopTimePtr)
LE_GNSS_NMEA_MASK_GNGSA
GNGSA type enabled: GNSS DOP and active satellites. 
Definition: le_gnss_interface.h:691
le_result_t
le_result_t
Definition: le_basics.h:35
le_gnss_Start
le_result_t le_gnss_Start(void)
LE_GNSS_STANDALONE_MODE
Standalone mode. 
Definition: le_gnss_interface.h:638
le_gnss_AddPositionHandler
le_gnss_PositionHandlerRef_t le_gnss_AddPositionHandler(le_gnss_PositionHandlerFunc_t handlerPtr, void *contextPtr)
LE_GNSS_CONSTELLATION_GLONASS
Russian satellite navigation system. 
Definition: le_gnss_interface.h:659
le_gnss_GetEpochTime
le_result_t le_gnss_GetEpochTime(le_gnss_SampleRef_t positionSampleRef, uint64_t *millisecondsPtr)
le_gnss_ForceFactoryRestart
le_result_t le_gnss_ForceFactoryRestart(void)
le_gnss_SampleRef_t
struct le_gnss_Sample * le_gnss_SampleRef_t
Definition: le_gnss_interface.h:529
le_gnss_LoadExtendedEphemerisFile
le_result_t le_gnss_LoadExtendedEphemerisFile(int fd)
LE_GNSS_NMEA_MASK_PSTIS
PSTIS type enabled: GPS session start indication. 
Definition: le_gnss_interface.h:697
le_gnss_GetAcquisitionRate
le_result_t le_gnss_GetAcquisitionRate(uint32_t *ratePtr)
le_gnss_DisconnectService
void le_gnss_DisconnectService(void)
LE_GNSS_SBAS_MSAS
Definition: le_gnss_interface.h:588
LE_GNSS_SV_CONSTELLATION_GPS
Definition: le_gnss_interface.h:607
LE_GNSS_SV_CONSTELLATION_BEIDOU
Definition: le_gnss_interface.h:619
LE_GNSS_CONSTELLATION_BEIDOU
Chinese satellite navigation system. 
Definition: le_gnss_interface.h:661
LE_GNSS_NMEA_MASK_GNGNS
GNGNS type enabled: GNSS fix data. 
Definition: le_gnss_interface.h:690
LE_GNSS_NMEA_MASK_GAGGA
GAGGA type enabled: Galileo fix data. 
Definition: le_gnss_interface.h:692
le_gnss_ForceColdRestart
le_result_t le_gnss_ForceColdRestart(void)
LE_GNSS_NMEA_MASK_GAGSA
GAGSA type enabled: Galileo DOP and active satellites. 
Definition: le_gnss_interface.h:693
LE_GNSS_STATE_FIX_ESTIMATED
Estimated (i.e. forward predicted) position fix. 
Definition: le_gnss_interface.h:566
le_gnss_ForceWarmRestart
le_result_t le_gnss_ForceWarmRestart(void)
le_gnss_State_t
le_gnss_State_t
Definition: le_gnss_interface.h:537
le_gnss_InjectUtcTime
le_result_t le_gnss_InjectUtcTime(uint64_t timeUtc, uint32_t timeUnc)
LE_GNSS_NMEA_MASK_GPGSV
GPGSV type enabled: GPS satellites in view. 
Definition: le_gnss_interface.h:686
LE_GNSS_SV_CONSTELLATION_GLONASS
Definition: le_gnss_interface.h:613
LE_GNSS_CONSTELLATION_QZSS
Japanese satellite navigation system. 
Definition: le_gnss_interface.h:666
le_gnss_GetTtff
le_result_t le_gnss_GetTtff(uint32_t *ttffPtr)
le_gnss_GetConstellation
le_result_t le_gnss_GetConstellation(le_gnss_ConstellationBitMask_t *constellationMaskPtr)
LE_GNSS_STATE_ACTIVE
The GNSS device is active. 
Definition: le_gnss_interface.h:543
le_gnss_RemovePositionHandler
void le_gnss_RemovePositionHandler(le_gnss_PositionHandlerRef_t handlerRef)
LE_GNSS_SV_CONSTELLATION_MAX
Maximum value. 
Definition: le_gnss_interface.h:625
le_gnss_EnableExtendedEphemerisFile
le_result_t le_gnss_EnableExtendedEphemerisFile(void)
LE_GNSS_STATE_FIX_3D
3-Dimensional position fix. 
Definition: le_gnss_interface.h:564
le_gnss_GetAltitudeOnWgs84
le_result_t le_gnss_GetAltitudeOnWgs84(le_gnss_SampleRef_t positionSampleRef, int32_t *altitudeOnWgs84Ptr)
le_gnss_GetTime
le_result_t le_gnss_GetTime(le_gnss_SampleRef_t positionSampleRef, uint16_t *hoursPtr, uint16_t *minutesPtr, uint16_t *secondsPtr, uint16_t *millisecondsPtr)
le_gnss_GetSuplAssistedMode
le_result_t le_gnss_GetSuplAssistedMode(le_gnss_AssistedMode_t *assistedModePtr)
le_gnss_GetLocation
le_result_t le_gnss_GetLocation(le_gnss_SampleRef_t positionSampleRef, int32_t *latitudePtr, int32_t *longitudePtr, int32_t *hAccuracyPtr)
le_gnss_DisableExtendedEphemerisFile
le_result_t le_gnss_DisableExtendedEphemerisFile(void)
LE_GNSS_NMEA_MASK_GAVTG
GAVTG type enabled: Galileo vector track and speed over the ground. 
Definition: le_gnss_interface.h:696
le_gnss_TryConnectService
le_result_t le_gnss_TryConnectService(void)
le_gnss_SetAcquisitionRate
le_result_t le_gnss_SetAcquisitionRate(uint32_t rate)
le_gnss_SetMinElevation
le_result_t le_gnss_SetMinElevation(uint8_t minElevation)
LE_GNSS_SBAS_WAAS
Definition: le_gnss_interface.h:582
le_gnss_NmeaBitMask_t
le_gnss_NmeaBitMask_t
Definition: le_gnss_interface.h:682
le_gnss_DeleteSuplCertificate
le_result_t le_gnss_DeleteSuplCertificate(uint8_t suplCertificateId)
LE_GNSS_CONSTELLATION_GPS
North American satellite navigation system. 
Definition: le_gnss_interface.h:657
le_gnss_FixState_t
le_gnss_FixState_t
Definition: le_gnss_interface.h:558
LE_GNSS_STATE_FIX_2D
2-Dimensional position fix. 
Definition: le_gnss_interface.h:562
le_gnss_GetMagneticDeviation
le_result_t le_gnss_GetMagneticDeviation(le_gnss_SampleRef_t positionSampleRef, int32_t *magneticDeviationPtr)
LE_GNSS_SV_CONSTELLATION_QZSS
Definition: le_gnss_interface.h:622
le_gnss_ReleaseSampleRef
void le_gnss_ReleaseSampleRef(le_gnss_SampleRef_t positionSampleRef)
LE_GNSS_SV_CONSTELLATION_SBAS
Definition: le_gnss_interface.h:610
le_gnss_GetNmeaSentences
le_result_t le_gnss_GetNmeaSentences(le_gnss_NmeaBitMask_t *nmeaMaskPtrPtr)
LE_GNSS_STATE_DISABLED
The GNSS device is disabled. 
Definition: le_gnss_interface.h:545
le_gnss_GetVerticalSpeed
le_result_t le_gnss_GetVerticalSpeed(le_gnss_SampleRef_t positionSampleRef, int32_t *vspeedPtr, int32_t *vspeedAccuracyPtr)
LE_GNSS_MS_ASSISTED_MODE
MS-Assisted mode. 
Definition: le_gnss_interface.h:642
le_gnss_SetSuplAssistedMode
le_result_t le_gnss_SetSuplAssistedMode(le_gnss_AssistedMode_t assistedMode)
le_gnss_GetDate
le_result_t le_gnss_GetDate(le_gnss_SampleRef_t positionSampleRef, uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
le_gnss_ConstellationBitMask_t
le_gnss_ConstellationBitMask_t
Definition: le_gnss_interface.h:655
LE_GNSS_NMEA_MASK_GPVTG
GPVTG type enabled: GPS vector track and speed over the ground. 
Definition: le_gnss_interface.h:688
le_gnss_ConnectService
void le_gnss_ConnectService(void)
LE_GNSS_NMEA_MASK_GPRMC
GPRMC type enabled: GPS recommended minimum data. 
Definition: le_gnss_interface.h:687
le_gnss_GetSatellitesStatus
le_result_t le_gnss_GetSatellitesStatus(le_gnss_SampleRef_t positionSampleRef, uint8_t *satsInViewCountPtr, uint8_t *satsTrackingCountPtr, uint8_t *satsUsedCountPtr)
LE_GNSS_NMEA_MASK_PQXFI
PQXFI type enabled: Proprietary Qualcomm eXtended Fix Information. 
Definition: le_gnss_interface.h:698
LE_GNSS_CONSTELLATION_GALILEO
European Union satellite navigation system. 
Definition: le_gnss_interface.h:663
le_gnss_Stop
le_result_t le_gnss_Stop(void)
legato.h
LE_GNSS_SBAS_UNKNOWN
Definition: le_gnss_interface.h:591
le_gnss_GetState
le_gnss_State_t le_gnss_GetState(void)
le_gnss_SetNmeaSentences
le_result_t le_gnss_SetNmeaSentences(le_gnss_NmeaBitMask_t nmeaMask)
le_gnss_GetPositionState
le_result_t le_gnss_GetPositionState(le_gnss_SampleRef_t positionSampleRef, le_gnss_FixState_t *statePtr)
le_gnss_GetMinElevation
le_result_t le_gnss_GetMinElevation(uint8_t *minElevationPtrPtr)
le_gnss_Disable
le_result_t le_gnss_Disable(void)
LE_GNSS_NMEA_MASK_GPGGA
GPGGA type enabled: GPS fix data. 
Definition: le_gnss_interface.h:684
le_gnss_SetServerDisconnectHandler
void le_gnss_SetServerDisconnectHandler(le_gnss_DisconnectHandler_t disconnectHandler, void *contextPtr)
LE_GNSS_SBAS_GAGAN
Definition: le_gnss_interface.h:585
le_gnss_GetHorizontalSpeed
le_result_t le_gnss_GetHorizontalSpeed(le_gnss_SampleRef_t positionSampleRef, uint32_t *hspeedPtr, uint32_t *hspeedAccuracyPtr)
le_gnss_PositionHandlerFunc_t
void(* le_gnss_PositionHandlerFunc_t)(le_gnss_SampleRef_t positionSampleRef, void *contextPtr)
Definition: le_gnss_interface.h:718
le_gnss_GetLastSampleRef
le_gnss_SampleRef_t le_gnss_GetLastSampleRef(void)
le_gnss_SetConstellation
le_result_t le_gnss_SetConstellation(le_gnss_ConstellationBitMask_t constellationMask)
LE_GNSS_SV_CONSTELLATION_UNDEFINED
GNSS constellation field not defined. 
Definition: le_gnss_interface.h:605
le_gnss_ForceHotRestart
le_result_t le_gnss_ForceHotRestart(void)
LE_GNSS_CONSTELLATION_SBAS
SBAS constellation used in solution. 
Definition: le_gnss_interface.h:665
LE_GNSS_MS_BASED_MODE
MS-Based mode. 
Definition: le_gnss_interface.h:640
le_gnss_Enable
le_result_t le_gnss_Enable(void)
le_gnss_DisconnectHandler_t
void(* le_gnss_DisconnectHandler_t)(void *)
Definition: le_gnss_interface.h:394
le_gnss_GetGpsTime
le_result_t le_gnss_GetGpsTime(le_gnss_SampleRef_t positionSampleRef, uint32_t *gpsWeekPtr, uint32_t *gpsTimeOfWeekPtr)
LE_GNSS_NMEA_MASK_GPGSA
GPGSA type enabled: GPS DOP and active satellites. 
Definition: le_gnss_interface.h:685
le_gnss_SbasConstellationCategory_t
le_gnss_SbasConstellationCategory_t
Definition: le_gnss_interface.h:577
le_gnss_GetGpsLeapSeconds
le_result_t le_gnss_GetGpsLeapSeconds(le_gnss_SampleRef_t positionSampleRef, uint8_t *leapSecondsPtr)
LE_GNSS_STATE_READY
The GNSS device is ready. 
Definition: le_gnss_interface.h:541
LE_GNSS_STATE_FIX_NO_POS
The GNSS fix position is not fixed. 
Definition: le_gnss_interface.h:560
LE_GNSS_NMEA_MASK_GLGSV
GLGSV type enabled: GLONASS satellites in view. 
Definition: le_gnss_interface.h:689
LE_GNSS_NMEA_MASK_GAGSV
GAGSV type enabled: Galileo satellites in view. 
Definition: le_gnss_interface.h:694
le_gnss_GetTimeAccuracy
le_result_t le_gnss_GetTimeAccuracy(le_gnss_SampleRef_t positionSampleRef, uint32_t *timeAccuracyPtr)
le_gnss_PositionHandlerRef_t
struct le_gnss_PositionHandler * le_gnss_PositionHandlerRef_t
Definition: le_gnss_interface.h:708
LE_GNSS_NMEA_MASK_GARMC
GARMC type enabled: Galileo recommended minimum data. 
Definition: le_gnss_interface.h:695
le_gnss_Constellation_t
le_gnss_Constellation_t
Definition: le_gnss_interface.h:603
le_gnss_GetDop
le_result_t le_gnss_GetDop(le_gnss_SampleRef_t positionSampleRef, uint16_t *hdopPtr, uint16_t *vdopPtr, uint16_t *pdopPtr)