le_lpt_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_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  * @section le_lpt_PSM PSM
   78  *
   79  * The power saving mode (PSM) allows user to control various PSM parameters such as the extended
   80  * periodic RAU value, the requested GPRS READY value, the requested extended periodic TAU value
   81  * and the requested Active Time value which are defined in 3GPP TS 27.007 version 12.7.0 Release 12.
   82  *
   83  * <HR>
   84  *
   85  * Copyright (C) Sierra Wireless Inc.
   86  */
   87 /**
   88  * @file le_lpt_interface.h
   89  *
   90  * Legato @ref c_lpt include file.
   91  *
   92  * Copyright (C) Sierra Wireless Inc.
   93  */
   94 
   95 #ifndef LE_LPT_INTERFACE_H_INCLUDE_GUARD
   96 #define LE_LPT_INTERFACE_H_INCLUDE_GUARD
   97 
   98 
   99 #include "legato.h"
  100 
  101 // Internal includes for this interface
  102 #include "le_lpt_common.h"
  103 /** @addtogroup le_lpt le_lpt API Reference
  104  * @{
  105  * @file le_lpt_common.h
  106  * @file le_lpt_interface.h **/
  107 //--------------------------------------------------------------------------------------------------
  108 /**
  109  * Type for handler called when a server disconnects.
  110  */
  111 //--------------------------------------------------------------------------------------------------
  112 typedef void (*le_lpt_DisconnectHandler_t)(void *);
  113 
  114 //--------------------------------------------------------------------------------------------------
  115 /**
  116  *
  117  * Connect the current client thread to the service providing this API. Block until the service is
  118  * available.
  119  *
  120  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  121  * called before any other functions in this API.  Normally, ConnectService is automatically called
  122  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  123  *
  124  * This function is created automatically.
  125  */
  126 //--------------------------------------------------------------------------------------------------
  127 void le_lpt_ConnectService
  128 (
  129     void
  130 );
  131 
  132 //--------------------------------------------------------------------------------------------------
  133 /**
  134  *
  135  * Try to connect the current client thread to the service providing this API. Return with an error
  136  * if the service is not available.
  137  *
  138  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  139  * called before any other functions in this API.  Normally, ConnectService is automatically called
  140  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  141  *
  142  * This function is created automatically.
  143  *
  144  * @return
  145  *  - LE_OK if the client connected successfully to the service.
  146  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  147  *    bound.
  148  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  149  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 le_result_t le_lpt_TryConnectService
  153 (
  154     void
  155 );
  156 
  157 //--------------------------------------------------------------------------------------------------
  158 /**
  159  * Set handler called when server disconnection is detected.
  160  *
  161  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  162  * to continue without exiting, it should call longjmp() from inside the handler.
  163  */
  164 //--------------------------------------------------------------------------------------------------
  165 LE_FULL_API void le_lpt_SetServerDisconnectHandler
  166 (
  167     le_lpt_DisconnectHandler_t disconnectHandler,
  168     void *contextPtr
  169 );
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  *
  174  * Disconnect the current client thread from the service providing this API.
  175  *
  176  * Normally, this function doesn't need to be called. After this function is called, there's no
  177  * longer a connection to the service, and the functions in this API can't be used. For details, see
  178  * @ref apiFilesC_client.
  179  *
  180  * This function is created automatically.
  181  */
  182 //--------------------------------------------------------------------------------------------------
  183 void le_lpt_DisconnectService
  184 (
  185     void
  186 );
  187 
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  * eDRX Radio Access Technology enum
  192  */
  193 //--------------------------------------------------------------------------------------------------
  194 
  195 
  196 //--------------------------------------------------------------------------------------------------
  197 /**
  198  * Power management mode enum
  199  */
  200 //--------------------------------------------------------------------------------------------------
  201 
  202 
  203 //--------------------------------------------------------------------------------------------------
  204 /**
  205  * Handler to report a change in the network-provided eDRX parameters.
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * Reference type used by Add/Remove functions for EVENT 'le_lpt_EDrxParamsChange'
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * Set the eDRX activation state for the given Radio Access Technology.
  220  *
  221  * @return
  222  *  - LE_OK             The function succeeded.
  223  *  - LE_BAD_PARAMETER  A parameter is invalid.
  224  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  225  *  - LE_FAULT          The function failed.
  226  */
  227 //--------------------------------------------------------------------------------------------------
  228 le_result_t le_lpt_SetEDrxState
  229 (
  230     le_lpt_EDrxRat_t rat,
  231         ///< [IN] Radio Access Technology.
  232     le_onoff_t activation
  233         ///< [IN] eDRX activation state.
  234 );
  235 
  236 //--------------------------------------------------------------------------------------------------
  237 /**
  238  * Set the requested eDRX cycle value for the given Radio Access Technology.
  239  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  240  *
  241  * @return
  242  *  - LE_OK             The function succeeded.
  243  *  - LE_BAD_PARAMETER  A parameter is invalid.
  244  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  245  *  - LE_FAULT          The function failed.
  246  */
  247 //--------------------------------------------------------------------------------------------------
  248 le_result_t le_lpt_SetRequestedEDrxValue
  249 (
  250     le_lpt_EDrxRat_t rat,
  251         ///< [IN] Radio Access Technology.
  252     uint8_t eDrxValue
  253         ///< [IN] Requested eDRX cycle value, defined in 3GPP
  254         ///< TS 24.008 Rel-13 section 10.5.5.32.
  255 );
  256 
  257 //--------------------------------------------------------------------------------------------------
  258 /**
  259  * Get the requested eDRX cycle value for the given Radio Access Technology.
  260  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  261  *
  262  * @return
  263  *  - LE_OK             The function succeeded.
  264  *  - LE_BAD_PARAMETER  A parameter is invalid.
  265  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  266  *  - LE_UNAVAILABLE    No requested eDRX cycle value.
  267  *  - LE_FAULT          The function failed.
  268  */
  269 //--------------------------------------------------------------------------------------------------
  270 le_result_t le_lpt_GetRequestedEDrxValue
  271 (
  272     le_lpt_EDrxRat_t rat,
  273         ///< [IN] Radio Access Technology.
  274     uint8_t* eDrxValuePtr
  275         ///< [OUT] Requested eDRX cycle value, defined in 3GPP
  276         ///< TS 24.008 Rel-13 section 10.5.5.32.
  277 );
  278 
  279 //--------------------------------------------------------------------------------------------------
  280 /**
  281  * Get the network-provided eDRX cycle value for the given Radio Access Technology.
  282  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  283  *
  284  * @return
  285  *  - LE_OK             The function succeeded.
  286  *  - LE_BAD_PARAMETER  A parameter is invalid.
  287  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  288  *  - LE_UNAVAILABLE    No network-provided eDRX cycle value.
  289  *  - LE_FAULT          The function failed.
  290  */
  291 //--------------------------------------------------------------------------------------------------
  292 le_result_t le_lpt_GetNetworkProvidedEDrxValue
  293 (
  294     le_lpt_EDrxRat_t rat,
  295         ///< [IN] Radio Access Technology.
  296     uint8_t* eDrxValuePtr
  297         ///< [OUT] Network-provided eDRX cycle value, defined in
  298         ///< 3GPP TS 24.008 Rel-13 section 10.5.5.32.
  299 );
  300 
  301 //--------------------------------------------------------------------------------------------------
  302 /**
  303  * Get the network-provided Paging Time Window for the given Radio Access Technology.
  304  * The Paging Time Window is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
  305  *
  306  * @return
  307  *  - LE_OK             The function succeeded.
  308  *  - LE_BAD_PARAMETER  A parameter is invalid.
  309  *  - LE_UNSUPPORTED    eDRX is not supported by the platform.
  310  *  - LE_UNAVAILABLE    No defined Paging Time Window.
  311  *  - LE_FAULT          The function failed.
  312  */
  313 //--------------------------------------------------------------------------------------------------
  314 le_result_t le_lpt_GetNetworkProvidedPagingTimeWindow
  315 (
  316     le_lpt_EDrxRat_t rat,
  317         ///< [IN] Radio Access Technology.
  318     uint8_t* pagingTimeWindowPtr
  319         ///< [OUT] Network-provided Paging Time Window, defined
  320         ///< in 3GPP TS 24.008 Rel-13 section 10.5.5.32.
  321 );
  322 
  323 //--------------------------------------------------------------------------------------------------
  324 /**
  325  * Add handler function for EVENT 'le_lpt_EDrxParamsChange'
  326  *
  327  * Event to report a change in the network-provided eDRX parameters.
  328  */
  329 //--------------------------------------------------------------------------------------------------
  330 le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler
  331 (
  332     le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr,
  333         ///< [IN]
  334     void* contextPtr
  335         ///< [IN]
  336 );
  337 
  338 //--------------------------------------------------------------------------------------------------
  339 /**
  340  * Remove handler function for EVENT 'le_lpt_EDrxParamsChange'
  341  */
  342 //--------------------------------------------------------------------------------------------------
  343 void le_lpt_RemoveEDrxParamsChangeHandler
  344 (
  345     le_lpt_EDrxParamsChangeHandlerRef_t handlerRef
  346         ///< [IN]
  347 );
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Set the lowest power management mode that the module can enter.
  352  *
  353  * @return
  354  *  - LE_OK             The function succeeded.
  355  *  - LE_BAD_PARAMETER  A parameter is invalid.
  356  *  - LE_UNSUPPORTED    Operation is not supported.
  357  *  - LE_FAULT          The function failed.
  358  */
  359 //--------------------------------------------------------------------------------------------------
  360 le_result_t le_lpt_SetPmMode
  361 (
  362     le_lpt_PMMode_t mode
  363         ///< [IN]
  364 );
  365 
  366 //--------------------------------------------------------------------------------------------------
  367 /**
  368  * Set the PSM activation state.
  369  *
  370  * @return
  371  *  - LE_OK             The function succeeded.
  372  *  - LE_BAD_PARAMETER  A parameter is invalid.
  373  *  - LE_UNSUPPORTED    PSM is not supported by the platform.
  374  *  - LE_FAULT          The function failed.
  375  */
  376 //--------------------------------------------------------------------------------------------------
  377 le_result_t le_lpt_SetPSMState
  378 (
  379     le_onoff_t activation
  380         ///< [IN] PSM activation state.
  381 );
  382 
  383 //--------------------------------------------------------------------------------------------------
  384 /**
  385  * Set the Power Saving Mode Setting.
  386  *
  387  * @return
  388  *  - LE_OK             The function succeeded.
  389  *  - LE_BAD_PARAMETER  A parameter is invalid.
  390  *  - LE_UNSUPPORTED    PSM is not supported by the platform.
  391  *  - LE_FAULT          The function failed.
  392  */
  393 //--------------------------------------------------------------------------------------------------
  394 le_result_t le_lpt_SetPSMValue
  395 (
  396     uint8_t rqstPeriodicRau,
  397         ///< [IN] Requested periodic RAU.
  398     uint8_t rqstGprsRdyTimer,
  399         ///< [IN] Requested GPRS Ready timer.
  400     uint8_t rqstPeriodicTau,
  401         ///< [IN] Requested periodic TAU.
  402     uint8_t rqstActiveTimer
  403         ///< [IN] Requested active timer.
  404 );
  405 
  406 //--------------------------------------------------------------------------------------------------
  407 /**
  408  * Set the Power Saving Mode Setting.
  409  *
  410  * @return
  411  *  - LE_OK             The function succeeded.
  412  *  - LE_BAD_PARAMETER  A parameter is invalid.
  413  *  - LE_UNSUPPORTED    PSM is not supported by the platform.
  414  *  - LE_FAULT          The function failed.
  415  */
  416 //--------------------------------------------------------------------------------------------------
  417 le_result_t le_lpt_GetPSMValue
  418 (
  419     uint8_t* rqstPeriodicRauPtr,
  420         ///< [OUT] Requested periodic RAU.
  421     uint8_t* rqstGprsRdyTimerPtr,
  422         ///< [OUT] Requested GPRS Ready timer.
  423     uint8_t* rqstPeriodicTauPtr,
  424         ///< [OUT] Requested periodic TAU.
  425     uint8_t* rqstActiveTimerPtr
  426         ///< [OUT] Requested active timer.
  427 );
  428 
  429 /** @} **/
  430 
  431 #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:77
le_lpt_DisconnectHandler_t
void(* le_lpt_DisconnectHandler_t)(void *)
Definition: le_lpt_interface.h:112
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:86
le_lpt_GetRequestedEDrxValue
le_result_t le_lpt_GetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)
le_lpt_SetPmMode
le_result_t le_lpt_SetPmMode(le_lpt_PMMode_t mode)
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
legato.h
le_lpt_ConnectService
void le_lpt_ConnectService(void)
le_lpt_PMMode_t
le_lpt_PMMode_t
Definition: le_lpt_common.h:58
le_lpt_GetPSMValue
le_result_t le_lpt_GetPSMValue(uint8_t *rqstPeriodicRauPtr, uint8_t *rqstGprsRdyTimerPtr, uint8_t *rqstPeriodicTauPtr, uint8_t *rqstActiveTimerPtr)
le_lpt_SetPSMValue
le_result_t le_lpt_SetPSMValue(uint8_t rqstPeriodicRau, uint8_t rqstGprsRdyTimer, uint8_t rqstPeriodicTau, uint8_t rqstActiveTimer)
le_lpt_SetPSMState
le_result_t le_lpt_SetPSMState(le_onoff_t activation)
le_onoff_t
le_onoff_t
Definition: le_basics.h:85