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


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


le_lpt_DisconnectService
void le_lpt_DisconnectService(void)


le_lpt_SetServerDisconnectHandler
LE_FULL_API void le_lpt_SetServerDisconnectHandler(le_lpt_DisconnectHandler_t disconnectHandler, void *contextPtr)


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


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_onoff_t
le_onoff_t
Definition: le_basics.h:71