le_cellnet_interface.h

Go to the documentation of this file.
    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_le_cellnet Cellular Network
   12  *
   13  * @ref le_cellnet_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * The Cellular Network service ensures that the modem is registered on the network when an user
   18  * application makes a request for network access. This includes:
   19  * - ensuring that the radio is turned on.
   20  * - ensuring that there is a valid SIM, and it is unlocked.
   21  * - ensuring that the modem is registered on the network.
   22  *
   23  * If all of the above conditions are met, then the service indicates that the network is available.
   24  *
   25  * @section le_cellnet_binding IPC interfaces binding
   26  *
   27  * All the functions of this API are provided by the @b cellNetService application service.
   28  *
   29  * Here's a code sample binding to Cellular Network services:
   30  * @verbatim
   31    bindings:
   32    {
   33       clientExe.clientComponent.le_cellnet -> cellNetService.le_cellnet
   34    }
   35    @endverbatim
   36  *
   37  * @section c_le_cellnet_requesting Requesting the Cellular Network
   38  *
   39  * The Cellular Network can be requested using le_cellnet_Request(). This function will turn on the
   40  * radio if it is switched off and it will unlock the SIM if a PIN code is required (the necessary
   41  * information will be retrieved from the secure storage, cf. @ref c_le_cellnet_config).
   42  *
   43  * Before the cellular network is requested, an application should register a network state
   44  * handler using le_cellnet_AddStateEventHandler(). Once the cellular network becomes available,
   45  * the handler will be called to indicate that the modem is now registered on the network.
   46  *
   47  * If the state of the network changes, then the handler will be called with the new state.
   48  * The current cellular network state can also be retrieved with le_cellnet_GetNetworkState().
   49  * @note There might be a discrepancy between the state notified by the handler and the state
   50  * retrieved through le_cellnet_GetNetworkState(): the state can have changed between the event
   51  * notification and its treatment by the application.
   52  *
   53  * To release the cellular network, an application can use le_cellnet_Release(). Once all user
   54  * applications release the cellular network access, then the service will turn off the radio.
   55  *
   56  * The application can release the network state handler by calling
   57  * le_cellnet_RemoveStateEventHandler() when it is not needed anymore.
   58  *
   59  * All configuration data required for a network registration, such as the PIN code of the SIM,
   60  * will be stored in the secure storage by the use of the le_cellnet_SetSimPinCode() function.
   61  *
   62  *
   63  * @section c_le_cellnet_config Cellular Network configuration
   64  *
   65  * Setting the SIM PIN code in the secure storage and retrieving it is performed by two functions:
   66  * le_cellnet_SetSimPinCode() and le_cellnet_GetSimPinCode().
   67  *
   68  * The le_cellnet_SetSimPinCode() function stores the PIN code in the secure storage and takes two
   69  * parameters: the SIM identifier and the SIM card PIN code.
   70  *
   71  * @note The function erases the previously stored SIM card PIN code.
   72  * @note It is possible to set and retry a void entry ("") corresponding to an unlocked SIM.
   73  *
   74  * The le_cellnet_GetSimPinCode() function retrieves the SIM card PIN code from the secure storage
   75  * and takes one parameter: the SIM identifier.
   76  *
   77  * @note The action carried out by the Cellular Network Service when a new SIM is inserted depends
   78  * on the SIM state:
   79  *   - if the SIM is locked, it will automatically read the secure storage in order to try to enter
   80  *     the PIN code for the SIM card. If the PIN code is not set or too long (max 8 digits), an
   81  *     error will be logged and the SIM will not be unlocked.
   82  *   - is the SIM is blocked, it just logs an error and does not try to enter the PUK code.
   83  *
   84  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   85  */
   86 /**
   87  * @file le_cellnet_interface.h
   88  *
   89  * Legato @ref c_le_cellnet include file.
   90  *
   91  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   92  */
   93 
   94 #ifndef LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
   95 #define LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
   96 
   97 
   98 #include "legato.h"
   99 
  100 // Interface specific includes
  101 #include "le_sim_interface.h"
  102 
  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_cellnet_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 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_cellnet_TryConnectService
  142 (
  143     void
  144 );
  145 
  146 //--------------------------------------------------------------------------------------------------
  147 /**
  148  *
  149  * Disconnect the current client thread from the service providing this API.
  150  *
  151  * Normally, this function doesn't need to be called. After this function is called, there's no
  152  * longer a connection to the service, and the functions in this API can't be used. For details, see
  153  * @ref apiFilesC_client.
  154  *
  155  * This function is created automatically.
  156  */
  157 //--------------------------------------------------------------------------------------------------
  158 void le_cellnet_DisconnectService
  159 (
  160     void
  161 );
  162 
  163 
  164 //--------------------------------------------------------------------------------------------------
  165 /**
  166  * Reference returned by Request function and used by Release function
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 typedef struct le_cellnet_RequestObj* le_cellnet_RequestObjRef_t;
  170 
  171 
  172 //--------------------------------------------------------------------------------------------------
  173 /**
  174  * Cellular Network states.
  175  *
  176  */
  177 //--------------------------------------------------------------------------------------------------
  178 typedef enum
  179 {
  180     LE_CELLNET_RADIO_OFF = 0,
  181         ///< The radio is switched-off.
  182 
  183     LE_CELLNET_REG_EMERGENCY = 1,
  184         ///< Only emergency calls are allowed.
  185 
  186     LE_CELLNET_REG_HOME = 2,
  187         ///< Registered, home network.
  188 
  189     LE_CELLNET_REG_ROAMING = 3,
  190         ///< Registered to a roaming network.
  191 
  192     LE_CELLNET_REG_UNKNOWN = 4,
  193         ///< Unknown state.
  194 
  195     LE_CELLNET_SIM_ABSENT = 5
  196         ///< No SIM card available.
  197 }
  198 le_cellnet_State_t;
  199 
  200 
  201 //--------------------------------------------------------------------------------------------------
  202 /**
  203  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
  204  */
  205 //--------------------------------------------------------------------------------------------------
  206 typedef struct le_cellnet_StateEventHandler* le_cellnet_StateEventHandlerRef_t;
  207 
  208 
  209 //--------------------------------------------------------------------------------------------------
  210 /**
  211  * Handler for network state changes
  212  *
  213  * @param state
  214  *        The cellular network state
  215  * @param contextPtr
  216  */
  217 //--------------------------------------------------------------------------------------------------
  218 typedef void (*le_cellnet_StateHandlerFunc_t)
  219 (
  220     le_cellnet_State_t state,
  221     void* contextPtr
  222 );
  223 
  224 //--------------------------------------------------------------------------------------------------
  225 /**
  226  * Add handler function for EVENT 'le_cellnet_StateEvent'
  227  *
  228  * This event provides information on network state changes
  229  */
  230 //--------------------------------------------------------------------------------------------------
  231 le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler
  232 (
  233     le_cellnet_StateHandlerFunc_t handlerPtr,
  234         ///< [IN]
  235 
  236     void* contextPtr
  237         ///< [IN]
  238 );
  239 
  240 //--------------------------------------------------------------------------------------------------
  241 /**
  242  * Remove handler function for EVENT 'le_cellnet_StateEvent'
  243  */
  244 //--------------------------------------------------------------------------------------------------
  245 void le_cellnet_RemoveStateEventHandler
  246 (
  247     le_cellnet_StateEventHandlerRef_t addHandlerRef
  248         ///< [IN]
  249 );
  250 
  251 //--------------------------------------------------------------------------------------------------
  252 /**
  253  * Request a cellular network
  254  *
  255  * @return
  256  *      - A reference to the cellular network
  257  *      - 0 (zero) if the network requested could not be processed
  258  */
  259 //--------------------------------------------------------------------------------------------------
  260 le_cellnet_RequestObjRef_t le_cellnet_Request
  261 (
  262     void
  263 );
  264 
  265 //--------------------------------------------------------------------------------------------------
  266 /**
  267  * Release a cellular network
  268  */
  269 //--------------------------------------------------------------------------------------------------
  270 void le_cellnet_Release
  271 (
  272     le_cellnet_RequestObjRef_t cellNetRef
  273         ///< [IN] Reference to a cellular network request.
  274 );
  275 
  276 //--------------------------------------------------------------------------------------------------
  277 /**
  278  * Set the PIN code in the secure storage.
  279  *
  280  * @return
  281  *  - LE_OUT_OF_RANGE    Invalid simId
  282  *  - LE_FORMAT_ERROR    PIN code is not in string format.
  283  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  284  *  - LE_OK              The function succeeded.
  285  *  - LE_FAULT           The function failed on any other errors
  286  *
  287  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  288  *       function will not return.
  289  *
  290  */
  291 //--------------------------------------------------------------------------------------------------
  292 le_result_t le_cellnet_SetSimPinCode
  293 (
  294     le_sim_Id_t simId,
  295         ///< [IN] SIM identifier.
  296 
  297     const char* pinCode
  298         ///< [IN] PIN code to insert in the secure storage.
  299 );
  300 
  301 //--------------------------------------------------------------------------------------------------
  302 /**
  303  * Retrieve the PIN code from the secure storage.
  304  *
  305  * @return
  306  *  - LE_OUT_OF_RANGE    Invalid simId
  307  *  - LE_NOT_FOUND       PIN code is not found in the secure storage.
  308  *  - LE_OVERFLOW        PIN code exceeds the maximum length of 8 digits.
  309  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  310  *  - LE_OK              The function succeeded.
  311  */
  312 //--------------------------------------------------------------------------------------------------
  313 le_result_t le_cellnet_GetSimPinCode
  314 (
  315     le_sim_Id_t simId,
  316         ///< [IN] SIM identifier.
  317 
  318     char* pinCode,
  319         ///< [OUT] Read the PIN code from the secure storage.
  320 
  321     size_t pinCodeNumElements
  322         ///< [IN]
  323 );
  324 
  325 //--------------------------------------------------------------------------------------------------
  326 /**
  327  * Retrieve the current cellular network state.
  328  *
  329  * @return
  330  *  - LE_OK             The function succeeded.
  331  *  - LE_FAILED         The function failed
  332  *  - LE_BAD_PARAMETER  A bad parameter was passed.
  333  *
  334  * @note If the caller passes a null pointer to this function, this is a fatal error and the
  335  *       function will not return.
  336  */
  337 //--------------------------------------------------------------------------------------------------
  338 le_result_t le_cellnet_GetNetworkState
  339 (
  340     le_cellnet_State_t* statePtr
  341         ///< [OUT] Cellular network state.
  342 );
  343 
  344 
  345 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
  346 
le_sim_Id_t
le_sim_Id_t
Definition: le_sim_interface.h:550


le_cellnet_StateHandlerFunc_t
void(* le_cellnet_StateHandlerFunc_t)(le_cellnet_State_t state, void *contextPtr)
Definition: le_cellnet_interface.h:219


le_result_t
le_result_t
Definition: le_basics.h:35


LE_CELLNET_REG_UNKNOWN
Unknown state. 
Definition: le_cellnet_interface.h:192


le_cellnet_TryConnectService
le_result_t le_cellnet_TryConnectService(void)


LE_CELLNET_REG_EMERGENCY
Only emergency calls are allowed. 
Definition: le_cellnet_interface.h:183


le_cellnet_DisconnectService
void le_cellnet_DisconnectService(void)


LE_CELLNET_SIM_ABSENT
No SIM card available. 
Definition: le_cellnet_interface.h:195


LE_CELLNET_RADIO_OFF
The radio is switched-off. 
Definition: le_cellnet_interface.h:180


le_sim_interface.h


le_cellnet_State_t
le_cellnet_State_t
Definition: le_cellnet_interface.h:178


le_cellnet_Release
void le_cellnet_Release(le_cellnet_RequestObjRef_t cellNetRef)


le_cellnet_AddStateEventHandler
le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler(le_cellnet_StateHandlerFunc_t handlerPtr, void *contextPtr)


le_cellnet_Request
le_cellnet_RequestObjRef_t le_cellnet_Request(void)


le_cellnet_ConnectService
void le_cellnet_ConnectService(void)


le_cellnet_StateEventHandlerRef_t
struct le_cellnet_StateEventHandler * le_cellnet_StateEventHandlerRef_t
Definition: le_cellnet_interface.h:206


le_cellnet_RequestObjRef_t
struct le_cellnet_RequestObj * le_cellnet_RequestObjRef_t
Definition: le_cellnet_interface.h:169


LE_CELLNET_REG_HOME
Registered, home network. 
Definition: le_cellnet_interface.h:186



le_cellnet_RemoveStateEventHandler
void le_cellnet_RemoveStateEventHandler(le_cellnet_StateEventHandlerRef_t addHandlerRef)


LE_CELLNET_REG_ROAMING
Registered to a roaming network. 
Definition: le_cellnet_interface.h:189


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


le_cellnet_GetNetworkState
le_result_t le_cellnet_GetNetworkState(le_cellnet_State_t *statePtr)


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