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 // Internal includes for this interface
   96 #include "le_lpt_common.h"
   97 /** @addtogroup le_lpt le_lpt API Reference
   98  * @{
   99  * @file le_lpt_common.h
  100  * @file le_lpt_interface.h **/
  101 //--------------------------------------------------------------------------------------------------
  102 /**
  103  * Type for handler called when a server disconnects.
  104  */
  105 //--------------------------------------------------------------------------------------------------
  106 typedef void (*le_lpt_DisconnectHandler_t)(void *);
  107 
  108 //--------------------------------------------------------------------------------------------------
  109 /**
  110  *
  111  * Connect the current client thread to the service providing this API. Block until the service is
  112  * available.
  113  *
  114  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  115  * called before any other functions in this API.  Normally, ConnectService is automatically called
  116  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  117  *
  118  * This function is created automatically.
  119  */
  120 //--------------------------------------------------------------------------------------------------
  121 void le_lpt_ConnectService
  122 (
  123     void
  124 );
  125 
  126 //--------------------------------------------------------------------------------------------------
  127 /**
  128  *
  129  * Try to connect the current client thread to the service providing this API. Return with an error
  130  * if the service is not available.
  131  *
  132  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  133  * called before any other functions in this API.  Normally, ConnectService is automatically called
  134  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  135  *
  136  * This function is created automatically.
  137  *
  138  * @return
  139  *  - LE_OK if the client connected successfully to the service.
  140  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  141  *    bound.
  142  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  143  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  144  */
  145 //--------------------------------------------------------------------------------------------------
  146 le_result_t le_lpt_TryConnectService
  147 (
  148     void
  149 );
  150 
  151 //--------------------------------------------------------------------------------------------------
  152 /**
  153  * Set handler called when server disconnection is detected.
  154  *
  155  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  156  * to continue without exiting, it should call longjmp() from inside the handler.
  157  */
  158 //--------------------------------------------------------------------------------------------------
  159 LE_FULL_API void le_lpt_SetServerDisconnectHandler
  160 (
  161     le_lpt_DisconnectHandler_t disconnectHandler,
  162     void *contextPtr
  163 );
  164 
  165 //--------------------------------------------------------------------------------------------------
  166 /**
  167  *
  168  * Disconnect the current client thread from the service providing this API.
  169  *
  170  * Normally, this function doesn't need to be called. After this function is called, there's no
  171  * longer a connection to the service, and the functions in this API can't be used. For details, see
  172  * @ref apiFilesC_client.
  173  *
  174  * This function is created automatically.
  175  */
  176 //--------------------------------------------------------------------------------------------------
  177 void le_lpt_DisconnectService
  178 (
  179     void
  180 );
  181 
  182 
  183 //--------------------------------------------------------------------------------------------------
  184 /**
  185  * eDRX Radio Access Technology enum
  186  */
  187 //--------------------------------------------------------------------------------------------------
  188 
  189 
  190 //--------------------------------------------------------------------------------------------------
  191 /**
  192  * Handler to report a change in the network-provided eDRX parameters.
  193  */
  194 //--------------------------------------------------------------------------------------------------
  195 
  196 
  197 //--------------------------------------------------------------------------------------------------
  198 /**
  199  * Reference type used by Add/Remove functions for EVENT 'le_lpt_EDrxParamsChange'
  200  */
  201 //--------------------------------------------------------------------------------------------------
  202 
  203 
  204 //--------------------------------------------------------------------------------------------------
  205 /**
  206  * Set the eDRX activation state for the given Radio Access Technology.
  207  *
  208  * @return
  209  *  - LE_OK             The function succeeded.
  210  *  - LE_BAD_PARAMETER  A parameter is invalid.
  211  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  212  *  - LE_FAULT          The function failed.
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 le_result_t le_lpt_SetEDrxState
  216 (
  217     le_lpt_EDrxRat_t rat,
  218         ///< [IN] Radio Access Technology.
  219     le_onoff_t activation
  220         ///< [IN] eDRX activation state.
  221 );
  222 
  223 //--------------------------------------------------------------------------------------------------
  224 /**
  225  * Set the requested eDRX cycle value for the given Radio Access Technology.
  226  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  227  *
  228  * @return
  229  *  - LE_OK             The function succeeded.
  230  *  - LE_BAD_PARAMETER  A parameter is invalid.
  231  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  232  *  - LE_FAULT          The function failed.
  233  */
  234 //--------------------------------------------------------------------------------------------------
  235 le_result_t le_lpt_SetRequestedEDrxValue
  236 (
  237     le_lpt_EDrxRat_t rat,
  238         ///< [IN] Radio Access Technology.
  239     uint8_t eDrxValue
  240         ///< [IN] Requested eDRX cycle value, defined in 3GPP
  241         ///< TS 24.008 Rel-13 section 10.5.5.32.
  242 );
  243 
  244 //--------------------------------------------------------------------------------------------------
  245 /**
  246  * Get the requested eDRX cycle value for the given Radio Access Technology.
  247  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  248  *
  249  * @return
  250  *  - LE_OK             The function succeeded.
  251  *  - LE_BAD_PARAMETER  A parameter is invalid.
  252  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  253  *  - LE_UNAVAILABLE    No requested eDRX cycle value.
  254  *  - LE_FAULT          The function failed.
  255  */
  256 //--------------------------------------------------------------------------------------------------
  257 le_result_t le_lpt_GetRequestedEDrxValue
  258 (
  259     le_lpt_EDrxRat_t rat,
  260         ///< [IN] Radio Access Technology.
  261     uint8_t* eDrxValuePtr
  262         ///< [OUT] Requested eDRX cycle value, defined in 3GPP
  263         ///< TS 24.008 Rel-13 section 10.5.5.32.
  264 );
  265 
  266 //--------------------------------------------------------------------------------------------------
  267 /**
  268  * Get the network-provided eDRX cycle value for the given Radio Access Technology.
  269  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  270  *
  271  * @return
  272  *  - LE_OK             The function succeeded.
  273  *  - LE_BAD_PARAMETER  A parameter is invalid.
  274  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  275  *  - LE_UNAVAILABLE    No network-provided eDRX cycle value.
  276  *  - LE_FAULT          The function failed.
  277  */
  278 //--------------------------------------------------------------------------------------------------
  279 le_result_t le_lpt_GetNetworkProvidedEDrxValue
  280 (
  281     le_lpt_EDrxRat_t rat,
  282         ///< [IN] Radio Access Technology.
  283     uint8_t* eDrxValuePtr
  284         ///< [OUT] Network-provided eDRX cycle value, defined in
  285         ///< 3GPP TS 24.008 Rel-13 section 10.5.5.32.
  286 );
  287 
  288 //--------------------------------------------------------------------------------------------------
  289 /**
  290  * Get the network-provided Paging Time Window for the given Radio Access Technology.
  291  * The Paging Time Window is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  292  *
  293  * @return
  294  *  - LE_OK             The function succeeded.
  295  *  - LE_BAD_PARAMETER  A parameter is invalid.
  296  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  297  *  - LE_UNAVAILABLE    No defined Paging Time Window.
  298  *  - LE_FAULT          The function failed.
  299  */
  300 //--------------------------------------------------------------------------------------------------
  301 le_result_t le_lpt_GetNetworkProvidedPagingTimeWindow
  302 (
  303     le_lpt_EDrxRat_t rat,
  304         ///< [IN] Radio Access Technology.
  305     uint8_t* pagingTimeWindowPtr
  306         ///< [OUT] Network-provided Paging Time Window, defined
  307         ///< in 3GPP TS 24.008 Rel-13 section 10.5.5.32.
  308 );
  309 
  310 //--------------------------------------------------------------------------------------------------
  311 /**
  312  * Add handler function for EVENT 'le_lpt_EDrxParamsChange'
  313  *
  314  * Event to report a change in the network-provided eDRX parameters.
  315  */
  316 //--------------------------------------------------------------------------------------------------
  317 le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler
  318 (
  319     le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr,
  320         ///< [IN]
  321     void* contextPtr
  322         ///< [IN]
  323 );
  324 
  325 //--------------------------------------------------------------------------------------------------
  326 /**
  327  * Remove handler function for EVENT 'le_lpt_EDrxParamsChange'
  328  */
  329 //--------------------------------------------------------------------------------------------------
  330 void le_lpt_RemoveEDrxParamsChangeHandler
  331 (
  332     le_lpt_EDrxParamsChangeHandlerRef_t handlerRef
  333         ///< [IN]
  334 );
  335 
  336 /** @} **/
  337 
  338 #endif // LE_LPT_INTERFACE_H_INCLUDE_GUARD
le_lpt_SetServerDisconnectHandler
LE_FULL_API void le_lpt_SetServerDisconnectHandler(le_lpt_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_lpt_AddEDrxParamsChangeHandler
le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler(le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr, void *contextPtr)


le_lpt_GetNetworkProvidedEDrxValue
le_result_t le_lpt_GetNetworkProvidedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)


le_result_t
le_result_t
Definition: le_basics.h:46


le_lpt_SetEDrxState
le_result_t le_lpt_SetEDrxState(le_lpt_EDrxRat_t rat, le_onoff_t activation)


le_lpt_common.h


le_lpt_EDrxParamsChangeHandlerRef_t
struct le_lpt_EDrxParamsChangeHandler * le_lpt_EDrxParamsChangeHandlerRef_t
Definition: le_lpt_common.h:58


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


le_lpt_TryConnectService
le_result_t le_lpt_TryConnectService(void)


le_lpt_GetNetworkProvidedPagingTimeWindow
le_result_t le_lpt_GetNetworkProvidedPagingTimeWindow(le_lpt_EDrxRat_t rat, uint8_t *pagingTimeWindowPtr)


le_lpt_RemoveEDrxParamsChangeHandler
void le_lpt_RemoveEDrxParamsChangeHandler(le_lpt_EDrxParamsChangeHandlerRef_t handlerRef)


le_lpt_DisconnectService
void le_lpt_DisconnectService(void)


le_lpt_EDrxRat_t
le_lpt_EDrxRat_t
Definition: le_lpt_common.h:33


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_common.h:67


le_lpt_GetRequestedEDrxValue
le_result_t le_lpt_GetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)


le_lpt_SetRequestedEDrxValue
le_result_t le_lpt_SetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t eDrxValue)


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40



le_lpt_ConnectService
void le_lpt_ConnectService(void)


le_onoff_t
le_onoff_t
Definition: le_basics.h:98