le_cellnet_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_le_cellnet Cellular Network
   14  *
   15  * @ref le_cellnet_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * The Cellular Network service ensures that the modem is registered on the network when an user
   20  * application makes a request for network access. This includes:
   21  * - ensuring that the radio is turned on.
   22  * - ensuring that there is a valid SIM, and it is unlocked.
   23  * - ensuring that the modem is registered on the network.
   24  *
   25  * If all of the above conditions are met, then the service indicates that the network is available.
   26  *
   27  * @section le_cellnet_binding IPC interfaces binding
   28  *
   29  * All the functions of this API are provided by the @b cellNetService application service.
   30  *
   31  * Here's a code sample binding to Cellular Network services:
   32  * @verbatim
   33    bindings:
   34    {
   35       clientExe.clientComponent.le_cellnet -> cellNetService.le_cellnet
   36    }
   37    @endverbatim
   38  *
   39  * @section c_le_cellnet_requesting Requesting the Cellular Network
   40  *
   41  * The Cellular Network can be requested using le_cellnet_Request(). This function will turn on the
   42  * radio if it is switched off and it will unlock the SIM if a PIN code is required (the necessary
   43  * information will be retrieved from the secure storage, cf. @ref c_le_cellnet_config).
   44  *
   45  * Before the cellular network is requested, an application should register a network state
   46  * handler using le_cellnet_AddStateEventHandler(). Once the cellular network becomes available,
   47  * the handler will be called to indicate that the modem is now registered on the network.
   48  *
   49  * If the state of the network changes, then the handler will be called with the new state.
   50  * The current cellular network state can also be retrieved with le_cellnet_GetNetworkState().
   51  * @note There might be a discrepancy between the state notified by the handler and the state
   52  * retrieved through le_cellnet_GetNetworkState(): the state can have changed between the event
   53  * notification and its treatment by the application.
   54  *
   55  * To release the cellular network, an application can use le_cellnet_Release(). Once all user
   56  * applications release the cellular network access, then the service will turn off the radio.
   57  *
   58  * The application can release the network state handler by calling
   59  * le_cellnet_RemoveStateEventHandler() when it is not needed anymore.
   60  *
   61  * All configuration data required for a network registration, such as the PIN code of the SIM,
   62  * will be stored in the secure storage by the use of the le_cellnet_SetSimPinCode() function.
   63  *
   64  *
   65  * @section c_le_cellnet_config Cellular Network configuration
   66  *
   67  * Setting the SIM PIN code in the secure storage and retrieving it is performed by two functions:
   68  * le_cellnet_SetSimPinCode() and le_cellnet_GetSimPinCode().
   69  *
   70  * The le_cellnet_SetSimPinCode() function stores the PIN code in the secure storage and takes two
   71  * parameters: the SIM identifier and the SIM card PIN code.
   72  *
   73  * @note The function erases the previously stored SIM card PIN code.
   74  * @note It is possible to set and retry a void entry ("") corresponding to an unlocked SIM.
   75  *
   76  * The le_cellnet_GetSimPinCode() function retrieves the SIM card PIN code from the secure storage
   77  * and takes one parameter: the SIM identifier.
   78  *
   79  * @note The action carried out by the Cellular Network Service when a new SIM is inserted depends
   80  * on the SIM state:
   81  *   - if the SIM is locked, it will automatically read the secure storage in order to try to enter
   82  *     the PIN code for the SIM card. If the PIN code is not set or too long (max 8 digits), an
   83  *     error will be logged and the SIM will not be unlocked.
   84  *   - is the SIM is blocked, it just logs an error and does not try to enter the PUK code.
   85  *
   86  * Copyright (C) Sierra Wireless Inc.
   87  */
   88 /**
   89  * @file le_cellnet_interface.h
   90  *
   91  * Legato @ref c_le_cellnet include file.
   92  *
   93  * Copyright (C) Sierra Wireless Inc.
   94  */
   95 
   96 #ifndef LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
   97 #define LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
   98 
   99 
  100 #include "legato.h"
  101 
  102 // Interface specific includes
  103 #include "le_sim_interface.h"
  104 
  105 // Internal includes for this interface
  106 #include "le_cellnet_common.h"
  107 /** @addtogroup le_cellnet le_cellnet API Reference
  108  * @{
  109  * @file le_cellnet_common.h
  110  * @file le_cellnet_interface.h **/
  111 //--------------------------------------------------------------------------------------------------
  112 /**
  113  * Type for handler called when a server disconnects.
  114  */
  115 //--------------------------------------------------------------------------------------------------
  116 typedef void (*le_cellnet_DisconnectHandler_t)(void *);
  117 
  118 //--------------------------------------------------------------------------------------------------
  119 /**
  120  *
  121  * Connect the current client thread to the service providing this API. Block until the service is
  122  * available.
  123  *
  124  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  125  * called before any other functions in this API.  Normally, ConnectService is automatically called
  126  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  127  *
  128  * This function is created automatically.
  129  */
  130 //--------------------------------------------------------------------------------------------------
  131 void le_cellnet_ConnectService
  132 (
  133     void
  134 );
  135 
  136 //--------------------------------------------------------------------------------------------------
  137 /**
  138  *
  139  * Try to connect the current client thread to the service providing this API. Return with an error
  140  * if the service is not available.
  141  *
  142  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  143  * called before any other functions in this API.  Normally, ConnectService is automatically called
  144  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  145  *
  146  * This function is created automatically.
  147  *
  148  * @return
  149  *  - LE_OK if the client connected successfully to the service.
  150  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  151  *    bound.
  152  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  153  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  154  */
  155 //--------------------------------------------------------------------------------------------------
  156 le_result_t le_cellnet_TryConnectService
  157 (
  158     void
  159 );
  160 
  161 //--------------------------------------------------------------------------------------------------
  162 /**
  163  * Set handler called when server disconnection is detected.
  164  *
  165  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  166  * to continue without exiting, it should call longjmp() from inside the handler.
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 LE_FULL_API void le_cellnet_SetServerDisconnectHandler
  170 (
  171     le_cellnet_DisconnectHandler_t disconnectHandler,
  172     void *contextPtr
  173 );
  174 
  175 //--------------------------------------------------------------------------------------------------
  176 /**
  177  *
  178  * Disconnect the current client thread from the service providing this API.
  179  *
  180  * Normally, this function doesn't need to be called. After this function is called, there's no
  181  * longer a connection to the service, and the functions in this API can't be used. For details, see
  182  * @ref apiFilesC_client.
  183  *
  184  * This function is created automatically.
  185  */
  186 //--------------------------------------------------------------------------------------------------
  187 void le_cellnet_DisconnectService
  188 (
  189     void
  190 );
  191 
  192 
  193 //--------------------------------------------------------------------------------------------------
  194 /**
  195  * Reference returned by Request function and used by Release function
  196  */
  197 //--------------------------------------------------------------------------------------------------
  198 
  199 
  200 //--------------------------------------------------------------------------------------------------
  201 /**
  202  * Cellular Network states.
  203  *
  204  */
  205 //--------------------------------------------------------------------------------------------------
  206 
  207 
  208 //--------------------------------------------------------------------------------------------------
  209 /**
  210  * Handler for network state changes
  211  */
  212 //--------------------------------------------------------------------------------------------------
  213 
  214 
  215 //--------------------------------------------------------------------------------------------------
  216 /**
  217  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
  218  */
  219 //--------------------------------------------------------------------------------------------------
  220 
  221 
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Add handler function for EVENT 'le_cellnet_StateEvent'
  225  *
  226  * This event provides information on network state changes
  227  */
  228 //--------------------------------------------------------------------------------------------------
  229 le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler
  230 (
  231     le_cellnet_StateHandlerFunc_t handlerPtr,
  232         ///< [IN]
  233     void* contextPtr
  234         ///< [IN]
  235 );
  236 
  237 //--------------------------------------------------------------------------------------------------
  238 /**
  239  * Remove handler function for EVENT 'le_cellnet_StateEvent'
  240  */
  241 //--------------------------------------------------------------------------------------------------
  242 void le_cellnet_RemoveStateEventHandler
  243 (
  244     le_cellnet_StateEventHandlerRef_t handlerRef
  245         ///< [IN]
  246 );
  247 
  248 //--------------------------------------------------------------------------------------------------
  249 /**
  250  * Request a cellular network
  251  *
  252  * @return
  253  *      - A reference to the cellular network
  254  *      - 0 (zero) if the network requested could not be processed
  255  */
  256 //--------------------------------------------------------------------------------------------------
  257 le_cellnet_RequestObjRef_t le_cellnet_Request
  258 (
  259     void
  260 );
  261 
  262 //--------------------------------------------------------------------------------------------------
  263 /**
  264  * Release a cellular network
  265  */
  266 //--------------------------------------------------------------------------------------------------
  267 void le_cellnet_Release
  268 (
  269     le_cellnet_RequestObjRef_t cellNetRef
  270         ///< [IN] Reference to a cellular network request.
  271 );
  272 
  273 //--------------------------------------------------------------------------------------------------
  274 /**
  275  * Set the PIN code in the secure storage.
  276  *
  277  * @return
  278  *  - LE_OUT_OF_RANGE    Invalid simId
  279  *  - LE_FORMAT_ERROR    PIN code is not in string format.
  280  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  281  *  - LE_OK              The function succeeded.
  282  *  - LE_FAULT           The function failed on any other errors
  283  *
  284  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  285  *       function will not return.
  286  *
  287  */
  288 //--------------------------------------------------------------------------------------------------
  289 le_result_t le_cellnet_SetSimPinCode
  290 (
  291     le_sim_Id_t simId,
  292         ///< [IN] SIM identifier.
  293     const char* LE_NONNULL pinCode
  294         ///< [IN] PIN code to insert in the secure storage.
  295 );
  296 
  297 //--------------------------------------------------------------------------------------------------
  298 /**
  299  * Retrieve the PIN code from the secure storage.
  300  *
  301  * @return
  302  *  - LE_OUT_OF_RANGE    Invalid simId
  303  *  - LE_NOT_FOUND       PIN code is not found in the secure storage.
  304  *  - LE_OVERFLOW        PIN code exceeds the maximum length of 8 digits.
  305  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  306  *  - LE_OK              The function succeeded.
  307  *  - LE_FAULT           If there are some other errors.
  308  */
  309 //--------------------------------------------------------------------------------------------------
  310 le_result_t le_cellnet_GetSimPinCode
  311 (
  312     le_sim_Id_t simId,
  313         ///< [IN] SIM identifier.
  314     char* pinCode,
  315         ///< [OUT] Read the PIN code from the secure storage.
  316     size_t pinCodeSize
  317         ///< [IN]
  318 );
  319 
  320 //--------------------------------------------------------------------------------------------------
  321 /**
  322  * Retrieve the current cellular network state.
  323  *
  324  * @return
  325  *  - LE_OK             The function succeeded.
  326  *  - LE_FAILED         The function failed
  327  *  - LE_BAD_PARAMETER  A bad parameter was passed.
  328  *
  329  * @note If the caller passes a null pointer to this function, this is a fatal error and the
  330  *       function will not return.
  331  */
  332 //--------------------------------------------------------------------------------------------------
  333 le_result_t le_cellnet_GetNetworkState
  334 (
  335     le_cellnet_State_t* statePtr
  336         ///< [OUT] Cellular network state.
  337 );
  338 
  339 /** @} **/
  340 
  341 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
le_cellnet_RequestObjRef_t
struct le_cellnet_RequestObj * le_cellnet_RequestObjRef_t
Definition: le_cellnet_common.h:36


le_cellnet_StateEventHandlerRef_t
struct le_cellnet_StateEventHandler * le_cellnet_StateEventHandlerRef_t
Definition: le_cellnet_common.h:68


le_result_t
le_result_t
Definition: le_basics.h:46


le_cellnet_Request
le_cellnet_RequestObjRef_t le_cellnet_Request(void)


le_cellnet_AddStateEventHandler
le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler(le_cellnet_StateHandlerFunc_t handlerPtr, void *contextPtr)


le_cellnet_common.h


le_cellnet_State_t
le_cellnet_State_t
Definition: le_cellnet_common.h:45


le_cellnet_TryConnectService
le_result_t le_cellnet_TryConnectService(void)


le_sim_interface.h


le_cellnet_RemoveStateEventHandler
void le_cellnet_RemoveStateEventHandler(le_cellnet_StateEventHandlerRef_t handlerRef)


le_cellnet_DisconnectHandler_t
void(* le_cellnet_DisconnectHandler_t)(void *)
Definition: le_cellnet_interface.h:116


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


le_cellnet_GetSimPinCode
le_result_t le_cellnet_GetSimPinCode(le_sim_Id_t simId, char *pinCode, size_t pinCodeSize)


le_cellnet_DisconnectService
void le_cellnet_DisconnectService(void)



le_cellnet_SetServerDisconnectHandler
LE_FULL_API void le_cellnet_SetServerDisconnectHandler(le_cellnet_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_cellnet_StateHandlerFunc_t
void(* le_cellnet_StateHandlerFunc_t)(le_cellnet_State_t state, void *contextPtr)
Definition: le_cellnet_common.h:77


le_cellnet_ConnectService
void le_cellnet_ConnectService(void)


le_cellnet_SetSimPinCode
le_result_t le_cellnet_SetSimPinCode(le_sim_Id_t simId, const char *LE_NONNULL pinCode)


le_sim_Id_t
le_sim_Id_t
Definition: le_sim_common.h:228


le_cellnet_Release
void le_cellnet_Release(le_cellnet_RequestObjRef_t cellNetRef)


le_cellnet_GetNetworkState
le_result_t le_cellnet_GetNetworkState(le_cellnet_State_t *statePtr)