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 
  106 //--------------------------------------------------------------------------------------------------
  107 /**
  108  * Type for handler called when a server disconnects.
  109  */
  110 //--------------------------------------------------------------------------------------------------
  111 typedef void (*le_cellnet_DisconnectHandler_t)(void *);
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Connect the current client thread to the service providing this API. Block until the service is
  117  * available.
  118  *
  119  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  120  * called before any other functions in this API.  Normally, ConnectService is automatically called
  121  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  122  *
  123  * This function is created automatically.
  124  */
  125 //--------------------------------------------------------------------------------------------------
  126 void le_cellnet_ConnectService
  127 (
  128     void
  129 );
  130 
  131 //--------------------------------------------------------------------------------------------------
  132 /**
  133  *
  134  * Try to connect the current client thread to the service providing this API. Return with an error
  135  * if the service is not available.
  136  *
  137  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  138  * called before any other functions in this API.  Normally, ConnectService is automatically called
  139  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  140  *
  141  * This function is created automatically.
  142  *
  143  * @return
  144  *  - LE_OK if the client connected successfully to the service.
  145  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  146  *    bound.
  147  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  148  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  149  */
  150 //--------------------------------------------------------------------------------------------------
  151 le_result_t le_cellnet_TryConnectService
  152 (
  153     void
  154 );
  155 
  156 //--------------------------------------------------------------------------------------------------
  157 /**
  158  * Set handler called when server disconnection is detected.
  159  *
  160  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  161  * to continue without exiting, it should call longjmp() from inside the handler.
  162  */
  163 //--------------------------------------------------------------------------------------------------
  164 void le_cellnet_SetServerDisconnectHandler
  165 (
  166     le_cellnet_DisconnectHandler_t disconnectHandler,
  167     void *contextPtr
  168 );
  169 
  170 //--------------------------------------------------------------------------------------------------
  171 /**
  172  *
  173  * Disconnect the current client thread from the service providing this API.
  174  *
  175  * Normally, this function doesn't need to be called. After this function is called, there's no
  176  * longer a connection to the service, and the functions in this API can't be used. For details, see
  177  * @ref apiFilesC_client.
  178  *
  179  * This function is created automatically.
  180  */
  181 //--------------------------------------------------------------------------------------------------
  182 void le_cellnet_DisconnectService
  183 (
  184     void
  185 );
  186 
  187 
  188 //--------------------------------------------------------------------------------------------------
  189 /**
  190  * Reference returned by Request function and used by Release function
  191  */
  192 //--------------------------------------------------------------------------------------------------
  193 typedef struct le_cellnet_RequestObj* le_cellnet_RequestObjRef_t;
  194 
  195 
  196 //--------------------------------------------------------------------------------------------------
  197 /**
  198  * Cellular Network states.
  199  *
  200  */
  201 //--------------------------------------------------------------------------------------------------
  202 typedef enum
  203 {
  204     LE_CELLNET_RADIO_OFF = 0,
  205         ///< The radio is switched-off.
  206     LE_CELLNET_REG_EMERGENCY = 1,
  207         ///< Only emergency calls are allowed.
  208     LE_CELLNET_REG_HOME = 2,
  209         ///< Registered, home network.
  210     LE_CELLNET_REG_ROAMING = 3,
  211         ///< Registered to a roaming network.
  212     LE_CELLNET_REG_UNKNOWN = 4,
  213         ///< Unknown state.
  214     LE_CELLNET_SIM_ABSENT = 5
  215         ///< No SIM card available.
  216 }
  217 le_cellnet_State_t;
  218 
  219 
  220 //--------------------------------------------------------------------------------------------------
  221 /**
  222  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
  223  */
  224 //--------------------------------------------------------------------------------------------------
  225 typedef struct le_cellnet_StateEventHandler* le_cellnet_StateEventHandlerRef_t;
  226 
  227 
  228 //--------------------------------------------------------------------------------------------------
  229 /**
  230  * Handler for network state changes
  231  */
  232 //--------------------------------------------------------------------------------------------------
  233 typedef void (*le_cellnet_StateHandlerFunc_t)
  234 (
  235     le_cellnet_State_t state,
  236         ///< The cellular network state
  237     void* contextPtr
  238         ///<
  239 );
  240 
  241 //--------------------------------------------------------------------------------------------------
  242 /**
  243  * Add handler function for EVENT 'le_cellnet_StateEvent'
  244  *
  245  * This event provides information on network state changes
  246  */
  247 //--------------------------------------------------------------------------------------------------
  248 le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler
  249 (
  250     le_cellnet_StateHandlerFunc_t handlerPtr,
  251         ///< [IN]
  252     void* contextPtr
  253         ///< [IN]
  254 );
  255 
  256 //--------------------------------------------------------------------------------------------------
  257 /**
  258  * Remove handler function for EVENT 'le_cellnet_StateEvent'
  259  */
  260 //--------------------------------------------------------------------------------------------------
  261 void le_cellnet_RemoveStateEventHandler
  262 (
  263     le_cellnet_StateEventHandlerRef_t handlerRef
  264         ///< [IN]
  265 );
  266 
  267 //--------------------------------------------------------------------------------------------------
  268 /**
  269  * Request a cellular network
  270  *
  271  * @return
  272  *      - A reference to the cellular network
  273  *      - 0 (zero) if the network requested could not be processed
  274  */
  275 //--------------------------------------------------------------------------------------------------
  276 le_cellnet_RequestObjRef_t le_cellnet_Request
  277 (
  278     void
  279 );
  280 
  281 //--------------------------------------------------------------------------------------------------
  282 /**
  283  * Release a cellular network
  284  */
  285 //--------------------------------------------------------------------------------------------------
  286 void le_cellnet_Release
  287 (
  288     le_cellnet_RequestObjRef_t cellNetRef
  289         ///< [IN] Reference to a cellular network request.
  290 );
  291 
  292 //--------------------------------------------------------------------------------------------------
  293 /**
  294  * Set the PIN code in the secure storage.
  295  *
  296  * @return
  297  *  - LE_OUT_OF_RANGE    Invalid simId
  298  *  - LE_FORMAT_ERROR    PIN code is not in string format.
  299  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  300  *  - LE_OK              The function succeeded.
  301  *  - LE_FAULT           The function failed on any other errors
  302  *
  303  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  304  *       function will not return.
  305  *
  306  */
  307 //--------------------------------------------------------------------------------------------------
  308 le_result_t le_cellnet_SetSimPinCode
  309 (
  310     le_sim_Id_t simId,
  311         ///< [IN] SIM identifier.
  312     const char* pinCode
  313         ///< [IN] PIN code to insert in the secure storage.
  314 )
  315 __attribute__(( nonnull(2) ));
  316 
  317 //--------------------------------------------------------------------------------------------------
  318 /**
  319  * Retrieve the PIN code from the secure storage.
  320  *
  321  * @return
  322  *  - LE_OUT_OF_RANGE    Invalid simId
  323  *  - LE_NOT_FOUND       PIN code is not found in the secure storage.
  324  *  - LE_OVERFLOW        PIN code exceeds the maximum length of 8 digits.
  325  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  326  *  - LE_OK              The function succeeded.
  327  */
  328 //--------------------------------------------------------------------------------------------------
  329 le_result_t le_cellnet_GetSimPinCode
  330 (
  331     le_sim_Id_t simId,
  332         ///< [IN] SIM identifier.
  333     char* pinCode,
  334         ///< [OUT] Read the PIN code from the secure storage.
  335     size_t pinCodeSize
  336         ///< [IN]
  337 );
  338 
  339 //--------------------------------------------------------------------------------------------------
  340 /**
  341  * Retrieve the current cellular network state.
  342  *
  343  * @return
  344  *  - LE_OK             The function succeeded.
  345  *  - LE_FAILED         The function failed
  346  *  - LE_BAD_PARAMETER  A bad parameter was passed.
  347  *
  348  * @note If the caller passes a null pointer to this function, this is a fatal error and the
  349  *       function will not return.
  350  */
  351 //--------------------------------------------------------------------------------------------------
  352 le_result_t le_cellnet_GetNetworkState
  353 (
  354     le_cellnet_State_t* statePtr
  355         ///< [OUT] Cellular network state.
  356 );
  357 
  358 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
le_sim_Id_t
le_sim_Id_t
Definition: le_sim_interface.h:559


le_result_t
le_result_t
Definition: le_basics.h:35


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


LE_CELLNET_REG_UNKNOWN
Unknown state. 
Definition: le_cellnet_interface.h:212


le_cellnet_TryConnectService
le_result_t le_cellnet_TryConnectService(void)


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


le_cellnet_DisconnectService
void le_cellnet_DisconnectService(void)


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


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


le_sim_interface.h


le_cellnet_State_t
le_cellnet_State_t
Definition: le_cellnet_interface.h:202


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_DisconnectHandler_t
void(* le_cellnet_DisconnectHandler_t)(void *)
Definition: le_cellnet_interface.h:111


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


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


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



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


le_cellnet_RemoveStateEventHandler
void le_cellnet_RemoveStateEventHandler(le_cellnet_StateEventHandlerRef_t handlerRef)


le_cellnet_GetNetworkState
le_result_t le_cellnet_GetNetworkState(le_cellnet_State_t *statePtr)


le_cellnet_SetServerDisconnectHandler
void le_cellnet_SetServerDisconnectHandler(le_cellnet_DisconnectHandler_t disconnectHandler, void *contextPtr)


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


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