le_lpt_interface.h

Go to the documentation of this file.
    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_lpt Low Power Technologies
   14  *
   15  * @ref le_lpt_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * The Low Power Technologies (LPT) APIs are used to control the low power features of the modem.
   20  *
   21  * @section le_lpt_binding IPC interfaces binding
   22  *
   23  * All the functions of this API are provided by the @b modemService service.
   24  *
   25  * Here's a code sample binding to modem services:
   26  * @verbatim
   27    bindings:
   28    {
   29       clientExe.clientComponent.le_lpt -> modemService.le_lpt
   30    }
   31    @endverbatim
   32  *
   33  * @section le_lpt_eDRX eDRX
   34  *
   35  * The extended idle-mode discontinuous reception (eDRX) is a mechanism that reduces power
   36  * consumption by extending the sleeping cycle in idle mode. It allows the device to turn part of
   37  * its circuitry off during the extended DRX period to save power. During the extended DRX period,
   38  * the device is not listening for paging or downlink control channels, so the network should not
   39  * try to contact the device.
   40  *
   41  * @warning Enabling eDRX introduces a longer latency in reaching the device and should therefore
   42  * not be used by systems that cannot handle it, e.g. systems supporting mobile-terminated voice.
   43  *
   44  * The use of eDRX for a given radio access technology (@ref le_lpt_EDrxRat_t) can be enabled and
   45  * disabled with le_lpt_SetEDrxState().
   46  *
   47  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" Set state
   48  *
   49  * The eDRX feature is controlled by two parameters, which are defined in the standard 3GPP
   50  * TS 24.008 Release 13 Section 10.5.5.32: the eDRX value, defining the eDRX cycle length, and
   51  * the Paging Time Window. These parameters are negotiated between the device and the network during
   52  * an attach or routing area updating procedure.
   53  *
   54  * The requested eDRX value can be set with le_lpt_SetRequestedEDrxValue() and retrieved with
   55  * le_lpt_GetRequestedEDrxValue().
   56  *
   57  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" eDRX value
   58  *
   59  * The eDRX value provided by the network can be retrieved with
   60  * le_lpt_GetNetworkProvidedEDrxValue().
   61  *
   62  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" NP eDRX value
   63  *
   64  * The requested Paging Time Window cannot be set, but the network-provided value can be retrieved
   65  * with le_lpt_GetNetworkProvidedPagingTimeWindow().
   66  *
   67  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" NP PTW
   68  *
   69  * A handler can also be registered with le_lpt_AddEDrxParamsChangeHandler() in order to be notified
   70  * of the changes in the network-provided eDRX parameters.
   71  *
   72  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" eDRX handler
   73  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" Add eDRX handler
   74  *
   75  * The handler can be removed with le_lpt_RemoveEDrxParamsChangeHandler().
   76  *
   77  * <HR>
   78  *
   79  * Copyright (C) Sierra Wireless Inc.
   80  */
   81 /**
   82  * @file le_lpt_interface.h
   83  *
   84  * Legato @ref c_lpt include file.
   85  *
   86  * Copyright (C) Sierra Wireless Inc.
   87  */
   88 
   89 #ifndef LE_LPT_INTERFACE_H_INCLUDE_GUARD
   90 #define LE_LPT_INTERFACE_H_INCLUDE_GUARD
   91 
   92 
   93 #include "legato.h"
   94 
   95 
   96 //--------------------------------------------------------------------------------------------------
   97 /**
   98  * Type for handler called when a server disconnects.
   99  */
  100 //--------------------------------------------------------------------------------------------------
  101 typedef void (*le_lpt_DisconnectHandler_t)(void *);
  102 
  103 //--------------------------------------------------------------------------------------------------
  104 /**
  105  *
  106  * Connect the current client thread to the service providing this API. Block until the service is
  107  * available.
  108  *
  109  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  110  * called before any other functions in this API.  Normally, ConnectService is automatically called
  111  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  112  *
  113  * This function is created automatically.
  114  */
  115 //--------------------------------------------------------------------------------------------------
  116 void le_lpt_ConnectService
  117 (
  118     void
  119 );
  120 
  121 //--------------------------------------------------------------------------------------------------
  122 /**
  123  *
  124  * Try to connect the current client thread to the service providing this API. Return with an error
  125  * if the service is not available.
  126  *
  127  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  128  * called before any other functions in this API.  Normally, ConnectService is automatically called
  129  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  130  *
  131  * This function is created automatically.
  132  *
  133  * @return
  134  *  - LE_OK if the client connected successfully to the service.
  135  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  136  *    bound.
  137  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  138  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 le_result_t le_lpt_TryConnectService
  142 (
  143     void
  144 );
  145 
  146 //--------------------------------------------------------------------------------------------------
  147 /**
  148  * Set handler called when server disconnection is detected.
  149  *
  150  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  151  * to continue without exiting, it should call longjmp() from inside the handler.
  152  */
  153 //--------------------------------------------------------------------------------------------------
  154 void le_lpt_SetServerDisconnectHandler
  155 (
  156     le_lpt_DisconnectHandler_t disconnectHandler,
  157     void *contextPtr
  158 );
  159 
  160 //--------------------------------------------------------------------------------------------------
  161 /**
  162  *
  163  * Disconnect the current client thread from the service providing this API.
  164  *
  165  * Normally, this function doesn't need to be called. After this function is called, there's no
  166  * longer a connection to the service, and the functions in this API can't be used. For details, see
  167  * @ref apiFilesC_client.
  168  *
  169  * This function is created automatically.
  170  */
  171 //--------------------------------------------------------------------------------------------------
  172 void le_lpt_DisconnectService
  173 (
  174     void
  175 );
  176 
  177 
  178 //--------------------------------------------------------------------------------------------------
  179 /**
  180  * eDRX Radio Access Technology enum
  181  */
  182 //--------------------------------------------------------------------------------------------------
  183 typedef enum
  184 {
  185     LE_LPT_EDRX_RAT_UNKNOWN = 0,
  186         ///< Unknown
  187     LE_LPT_EDRX_RAT_EC_GSM_IOT = 1,
  188         ///< EC-GSM-IoT (A/Gb mode)
  189     LE_LPT_EDRX_RAT_GSM = 2,
  190         ///< GSM (A/Gb mode)
  191     LE_LPT_EDRX_RAT_UTRAN = 3,
  192         ///< UTRAN (Iu mode)
  193     LE_LPT_EDRX_RAT_LTE_M1 = 4,
  194         ///< E-UTRAN (WB-S1 mode)
  195     LE_LPT_EDRX_RAT_LTE_NB1 = 5,
  196         ///< E-UTRAN (NB-S1 mode)
  197     LE_LPT_EDRX_RAT_MAX = 6
  198         ///< Invalid
  199 }
  200 le_lpt_EDrxRat_t;
  201 
  202 
  203 //--------------------------------------------------------------------------------------------------
  204 /**
  205  * Reference type used by Add/Remove functions for EVENT 'le_lpt_EDrxParamsChange'
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 typedef struct le_lpt_EDrxParamsChangeHandler* le_lpt_EDrxParamsChangeHandlerRef_t;
  209 
  210 
  211 //--------------------------------------------------------------------------------------------------
  212 /**
  213  * Handler to report a change in the network-provided eDRX parameters.
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 typedef void (*le_lpt_EDrxParamsChangeHandlerFunc_t)
  217 (
  218     le_lpt_EDrxRat_t rat,
  219         ///< Radio Access Technology.
  220     le_onoff_t activation,
  221         ///< eDRX activation state.
  222     uint8_t eDrxValue,
  223         ///< eDRX cycle value, defined in 3GPP
  224         ///< TS 24.008 Rel-13 section 10.5.5.32.
  225     uint8_t pagingTimeWindow,
  226         ///< Paging Time Window, defined in 3GPP
  227         ///< TS 24.008 Rel-13 section 10.5.5.32.
  228     void* contextPtr
  229         ///<
  230 );
  231 
  232 //--------------------------------------------------------------------------------------------------
  233 /**
  234  * Set the eDRX activation state for the given Radio Access Technology.
  235  *
  236  * @return
  237  *  - LE_OK             The function succeeded.
  238  *  - LE_BAD_PARAMETER  A parameter is invalid.
  239  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  240  *  - LE_FAULT          The function failed.
  241  */
  242 //--------------------------------------------------------------------------------------------------
  243 le_result_t le_lpt_SetEDrxState
  244 (
  245     le_lpt_EDrxRat_t rat,
  246         ///< [IN] Radio Access Technology.
  247     le_onoff_t activation
  248         ///< [IN] eDRX activation state.
  249 );
  250 
  251 //--------------------------------------------------------------------------------------------------
  252 /**
  253  * Set the requested eDRX cycle value for the given Radio Access Technology.
  254  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  255  *
  256  * @return
  257  *  - LE_OK             The function succeeded.
  258  *  - LE_BAD_PARAMETER  A parameter is invalid.
  259  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  260  *  - LE_FAULT          The function failed.
  261  */
  262 //--------------------------------------------------------------------------------------------------
  263 le_result_t le_lpt_SetRequestedEDrxValue
  264 (
  265     le_lpt_EDrxRat_t rat,
  266         ///< [IN] Radio Access Technology.
  267     uint8_t eDrxValue
  268         ///< [IN] Requested eDRX cycle value, defined in 3GPP
  269         ///< TS 24.008 Rel-13 section 10.5.5.32.
  270 );
  271 
  272 //--------------------------------------------------------------------------------------------------
  273 /**
  274  * Get the requested eDRX cycle value for the given Radio Access Technology.
  275  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  276  *
  277  * @return
  278  *  - LE_OK             The function succeeded.
  279  *  - LE_BAD_PARAMETER  A parameter is invalid.
  280  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  281  *  - LE_UNAVAILABLE    No requested eDRX cycle value.
  282  *  - LE_FAULT          The function failed.
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 le_result_t le_lpt_GetRequestedEDrxValue
  286 (
  287     le_lpt_EDrxRat_t rat,
  288         ///< [IN] Radio Access Technology.
  289     uint8_t* eDrxValuePtr
  290         ///< [OUT] Requested eDRX cycle value, defined in 3GPP
  291         ///< TS 24.008 Rel-13 section 10.5.5.32.
  292 );
  293 
  294 //--------------------------------------------------------------------------------------------------
  295 /**
  296  * Get the network-provided eDRX cycle value for the given Radio Access Technology.
  297  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  298  *
  299  * @return
  300  *  - LE_OK             The function succeeded.
  301  *  - LE_BAD_PARAMETER  A parameter is invalid.
  302  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  303  *  - LE_UNAVAILABLE    No network-provided eDRX cycle value.
  304  *  - LE_FAULT          The function failed.
  305  */
  306 //--------------------------------------------------------------------------------------------------
  307 le_result_t le_lpt_GetNetworkProvidedEDrxValue
  308 (
  309     le_lpt_EDrxRat_t rat,
  310         ///< [IN] Radio Access Technology.
  311     uint8_t* eDrxValuePtr
  312         ///< [OUT] Network-provided eDRX cycle value, defined in
  313         ///< 3GPP TS 24.008 Rel-13 section 10.5.5.32.
  314 );
  315 
  316 //--------------------------------------------------------------------------------------------------
  317 /**
  318  * Get the network-provided Paging Time Window for the given Radio Access Technology.
  319  * The Paging Time Window is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  320  *
  321  * @return
  322  *  - LE_OK             The function succeeded.
  323  *  - LE_BAD_PARAMETER  A parameter is invalid.
  324  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  325  *  - LE_UNAVAILABLE    No defined Paging Time Window.
  326  *  - LE_FAULT          The function failed.
  327  */
  328 //--------------------------------------------------------------------------------------------------
  329 le_result_t le_lpt_GetNetworkProvidedPagingTimeWindow
  330 (
  331     le_lpt_EDrxRat_t rat,
  332         ///< [IN] Radio Access Technology.
  333     uint8_t* pagingTimeWindowPtr
  334         ///< [OUT] Network-provided Paging Time Window, defined
  335         ///< in 3GPP TS 24.008 Rel-13 section 10.5.5.32.
  336 );
  337 
  338 //--------------------------------------------------------------------------------------------------
  339 /**
  340  * Add handler function for EVENT 'le_lpt_EDrxParamsChange'
  341  *
  342  * Event to report a change in the network-provided eDRX parameters.
  343  */
  344 //--------------------------------------------------------------------------------------------------
  345 le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler
  346 (
  347     le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr,
  348         ///< [IN]
  349     void* contextPtr
  350         ///< [IN]
  351 );
  352 
  353 //--------------------------------------------------------------------------------------------------
  354 /**
  355  * Remove handler function for EVENT 'le_lpt_EDrxParamsChange'
  356  */
  357 //--------------------------------------------------------------------------------------------------
  358 void le_lpt_RemoveEDrxParamsChangeHandler
  359 (
  360     le_lpt_EDrxParamsChangeHandlerRef_t handlerRef
  361         ///< [IN]
  362 );
  363 
  364 #endif // LE_LPT_INTERFACE_H_INCLUDE_GUARD
LE_LPT_EDRX_RAT_EC_GSM_IOT
EC-GSM-IoT (A/Gb mode) 
Definition: le_lpt_interface.h:187


le_lpt_AddEDrxParamsChangeHandler
le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler(le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr, void *contextPtr)


le_result_t
le_result_t
Definition: le_basics.h:35


le_lpt_EDrxParamsChangeHandlerRef_t
struct le_lpt_EDrxParamsChangeHandler * le_lpt_EDrxParamsChangeHandlerRef_t
Definition: le_lpt_interface.h:208


LE_LPT_EDRX_RAT_MAX
Invalid. 
Definition: le_lpt_interface.h:197


le_lpt_GetNetworkProvidedPagingTimeWindow
le_result_t le_lpt_GetNetworkProvidedPagingTimeWindow(le_lpt_EDrxRat_t rat, uint8_t *pagingTimeWindowPtr)


le_lpt_GetNetworkProvidedEDrxValue
le_result_t le_lpt_GetNetworkProvidedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)


LE_LPT_EDRX_RAT_UTRAN
UTRAN (Iu mode) 
Definition: le_lpt_interface.h:191


LE_LPT_EDRX_RAT_UNKNOWN
Unknown. 
Definition: le_lpt_interface.h:185


le_lpt_GetRequestedEDrxValue
le_result_t le_lpt_GetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)


LE_LPT_EDRX_RAT_GSM
GSM (A/Gb mode) 
Definition: le_lpt_interface.h:189


le_lpt_DisconnectHandler_t
void(* le_lpt_DisconnectHandler_t)(void *)
Definition: le_lpt_interface.h:101


le_lpt_DisconnectService
void le_lpt_DisconnectService(void)


LE_LPT_EDRX_RAT_LTE_NB1
E-UTRAN (NB-S1 mode) 
Definition: le_lpt_interface.h:195


le_lpt_EDrxRat_t
le_lpt_EDrxRat_t
Definition: le_lpt_interface.h:183


LE_LPT_EDRX_RAT_LTE_M1
E-UTRAN (WB-S1 mode) 
Definition: le_lpt_interface.h:193



le_lpt_SetEDrxState
le_result_t le_lpt_SetEDrxState(le_lpt_EDrxRat_t rat, le_onoff_t activation)


le_lpt_TryConnectService
le_result_t le_lpt_TryConnectService(void)


le_lpt_RemoveEDrxParamsChangeHandler
void le_lpt_RemoveEDrxParamsChangeHandler(le_lpt_EDrxParamsChangeHandlerRef_t handlerRef)


le_lpt_SetRequestedEDrxValue
le_result_t le_lpt_SetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t eDrxValue)


le_lpt_ConnectService
void le_lpt_ConnectService(void)


le_lpt_EDrxParamsChangeHandlerFunc_t
void(* le_lpt_EDrxParamsChangeHandlerFunc_t)(le_lpt_EDrxRat_t rat, le_onoff_t activation, uint8_t eDrxValue, uint8_t pagingTimeWindow, void *contextPtr)
Definition: le_lpt_interface.h:217


le_lpt_SetServerDisconnectHandler
void le_lpt_SetServerDisconnectHandler(le_lpt_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_onoff_t
le_onoff_t
Definition: le_basics.h:70