le_cellnet_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_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 //--------------------------------------------------------------------------------------------------
  108 /**
  109  * Type for handler called when a server disconnects.
  110  */
  111 //--------------------------------------------------------------------------------------------------
  112 typedef void (*le_cellnet_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_cellnet_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_cellnet_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_cellnet_SetServerDisconnectHandler
  166 (
  167     le_cellnet_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_cellnet_DisconnectService
  184 (
  185     void
  186 );
  187 
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  * Reference returned by Request function and used by Release function
  192  */
  193 //--------------------------------------------------------------------------------------------------
  194 
  195 
  196 //--------------------------------------------------------------------------------------------------
  197 /**
  198  * Cellular Network states.
  199  *
  200  */
  201 //--------------------------------------------------------------------------------------------------
  202 
  203 
  204 //--------------------------------------------------------------------------------------------------
  205 /**
  206  * Handler for network state changes
  207  */
  208 //--------------------------------------------------------------------------------------------------
  209 
  210 
  211 //--------------------------------------------------------------------------------------------------
  212 /**
  213  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 
  217 
  218 //--------------------------------------------------------------------------------------------------
  219 /**
  220  * Add handler function for EVENT 'le_cellnet_StateEvent'
  221  *
  222  * This event provides information on network state changes
  223  */
  224 //--------------------------------------------------------------------------------------------------
  225 le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler
  226 (
  227     le_cellnet_StateHandlerFunc_t handlerPtr,
  228         ///< [IN]
  229     void* contextPtr
  230         ///< [IN]
  231 );
  232 
  233 //--------------------------------------------------------------------------------------------------
  234 /**
  235  * Remove handler function for EVENT 'le_cellnet_StateEvent'
  236  */
  237 //--------------------------------------------------------------------------------------------------
  238 void le_cellnet_RemoveStateEventHandler
  239 (
  240     le_cellnet_StateEventHandlerRef_t handlerRef
  241         ///< [IN]
  242 );
  243 
  244 //--------------------------------------------------------------------------------------------------
  245 /**
  246  * Request a cellular network
  247  *
  248  * @return
  249  *      - A reference to the cellular network
  250  *      - 0 (zero) if the network requested could not be processed
  251  */
  252 //--------------------------------------------------------------------------------------------------
  253 le_cellnet_RequestObjRef_t le_cellnet_Request
  254 (
  255     void
  256 );
  257 
  258 //--------------------------------------------------------------------------------------------------
  259 /**
  260  * Release a cellular network
  261  */
  262 //--------------------------------------------------------------------------------------------------
  263 void le_cellnet_Release
  264 (
  265     le_cellnet_RequestObjRef_t cellNetRef
  266         ///< [IN] Reference to a cellular network request.
  267 );
  268 
  269 //--------------------------------------------------------------------------------------------------
  270 /**
  271  * Set the PIN code in the secure storage.
  272  *
  273  * @return
  274  *  - LE_OUT_OF_RANGE    Invalid simId
  275  *  - LE_FORMAT_ERROR    PIN code is not in string format.
  276  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  277  *  - LE_OK              The function succeeded.
  278  *  - LE_FAULT           The function failed on any other errors
  279  *
  280  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  281  *       function will not return.
  282  *
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 le_result_t le_cellnet_SetSimPinCode
  286 (
  287     le_sim_Id_t simId,
  288         ///< [IN] SIM identifier.
  289     const char* LE_NONNULL pinCode
  290         ///< [IN] PIN code to insert in the secure storage.
  291 );
  292 
  293 //--------------------------------------------------------------------------------------------------
  294 /**
  295  * Retrieve the PIN code from the secure storage.
  296  *
  297  * @return
  298  *  - LE_OUT_OF_RANGE    Invalid simId
  299  *  - LE_NOT_FOUND       PIN code is not found in the secure storage.
  300  *  - LE_OVERFLOW        PIN code exceeds the maximum length of 8 digits.
  301  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  302  *  - LE_OK              The function succeeded.
  303  *  - LE_FAULT           If there are some other errors.
  304  */
  305 //--------------------------------------------------------------------------------------------------
  306 le_result_t le_cellnet_GetSimPinCode
  307 (
  308     le_sim_Id_t simId,
  309         ///< [IN] SIM identifier.
  310     char* pinCode,
  311         ///< [OUT] Read the PIN code from the secure storage.
  312     size_t pinCodeSize
  313         ///< [IN]
  314 );
  315 
  316 //--------------------------------------------------------------------------------------------------
  317 /**
  318  * Retrieve the current cellular network state.
  319  *
  320  * @return
  321  *  - LE_OK             The function succeeded.
  322  *  - LE_FAILED         The function failed
  323  *  - LE_BAD_PARAMETER  A bad parameter was passed.
  324  *
  325  * @note If the caller passes a null pointer to this function, this is a fatal error and the
  326  *       function will not return.
  327  */
  328 //--------------------------------------------------------------------------------------------------
  329 le_result_t le_cellnet_GetNetworkState
  330 (
  331     le_cellnet_State_t* statePtr
  332         ///< [OUT] Cellular network state.
  333 );
  334 
  335 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:35
le_cellnet_TryConnectService
le_result_t le_cellnet_TryConnectService(void)
le_cellnet_DisconnectService
void le_cellnet_DisconnectService(void)
le_sim_interface.h
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:112
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_cellnet_SetServerDisconnectHandler
LE_FULL_API void le_cellnet_SetServerDisconnectHandler(le_cellnet_DisconnectHandler_t disconnectHandler, void *contextPtr)
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_SetSimPinCode
le_result_t le_cellnet_SetSimPinCode(le_sim_Id_t simId, const char *LE_NONNULL pinCode)
le_cellnet_GetSimPinCode
le_result_t le_cellnet_GetSimPinCode(le_sim_Id_t simId, char *pinCode, size_t pinCodeSize)