le_cellnet_interface.h

    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(). The le_cellnet_Request
   40  * function will turn on the radio if it is switched off and it will unlock the SIM if a PIN code
   41  * is required (it will retrieve the needed information from the config tree,
   42  * cf. @ref c_le_cellnet_config).
   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  *
   49  * To release the cellular network, an application can use le_cellnet_Release(). Once all user
   50  * applications release the cellular network access, then the service will turn off the radio.
   51  *
   52  * All configuration data required for a network registration, such as the PIN code of the SIM,
   53  * will be stored in the Config tree by the use of the le_cellnet_SetSimPinCode() function.
   54  *
   55  *
   56  * @section c_le_cellnet_config Cellular Network configuration
   57  *
   58  * Setting the SIM PIN code in the config tree and retreiving it is performed by two functions:
   59  * le_cellnet_SetSimPinCode() and le_cellnet_GetSimPinCode().
   60  *
   61  * The le_cellnet_SetSimPinCode() function takes two parameters : SIM identifier and SIM card
   62  * PIN code and stores the PIN code in the rigth path of the config tree.
   63  * Note that the function erases the previous stored SIM card PIN code.
   64  * Note that it is possible to set and retry a void entry ("") corresponding to an unlocked SIM.
   65  *
   66  * The le_cellnet_GetSimPinCode() function takes one parameter: the SIM identifier and retreives
   67  * the SIM card PIN code from the config tree.
   68  *
   69  * @note
   70  * when a new SIM is inserted and :
   71  *   - is locked, Cellular Network Service will read automatically the config tree in order to try
   72  *     to enter the pin for the SIM card.
   73  *   - is blocked, Cellular Network Service just log an error and did not try to enter the puk code.
   74  *   - when setting a too long PIN code (max 8 digits), a fatal error occurs, the function will
   75  *     not return.
   76  *
   77  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   78  */
   79 /**
   80  * @file le_cellnet_interface.h
   81  *
   82  * Legato @ref c_le_cellnet include file.
   83  *
   84  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   85  */
   86 
   87 #ifndef LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
   88 #define LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
   89 
   90 
   91 #include "legato.h"
   92 
   93 // Interface specific includes
   94 #include "le_sim_interface.h"
   95 
   96 
   97 //--------------------------------------------------------------------------------------------------
   98 /**
   99  *
  100  * Connect the current client thread to the service providing this API. Block until the service is
  101  * available.
  102  *
  103  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  104  * called before any other functions in this API.  Normally, ConnectService is automatically called
  105  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  106  *
  107  * This function is created automatically.
  108  */
  109 //--------------------------------------------------------------------------------------------------
  110 void le_cellnet_ConnectService
  111 (
  112     void
  113 );
  114 
  115 //--------------------------------------------------------------------------------------------------
  116 /**
  117  *
  118  * Try to connect the current client thread to the service providing this API. Return with an error
  119  * if the service is not available.
  120  *
  121  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  122  * called before any other functions in this API.  Normally, ConnectService is automatically called
  123  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  124  *
  125  * This function is created automatically.
  126  *
  127  * @return
  128  *  - LE_OK if the client connected successfully to the service.
  129  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  130  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  131  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  132  */
  133 //--------------------------------------------------------------------------------------------------
  134 le_result_t le_cellnet_TryConnectService
  135 (
  136     void
  137 );
  138 
  139 //--------------------------------------------------------------------------------------------------
  140 /**
  141  *
  142  * Disconnect the current client thread from the service providing this API.
  143  *
  144  * Normally, this function doesn't need to be called. After this function is called, there's no
  145  * longer a connection to the service, and the functions in this API can't be used. For details, see
  146  * @ref apiFilesC_client.
  147  *
  148  * This function is created automatically.
  149  */
  150 //--------------------------------------------------------------------------------------------------
  151 void le_cellnet_DisconnectService
  152 (
  153     void
  154 );
  155 
  156 
  157 //--------------------------------------------------------------------------------------------------
  158 /**
  159  * Reference returned by Request function and used by Release function
  160  */
  161 //--------------------------------------------------------------------------------------------------
  162 typedef struct le_cellnet_RequestObj* le_cellnet_RequestObjRef_t;
  163 
  164 
  165 //--------------------------------------------------------------------------------------------------
  166 /**
  167  * Cellular Network states.
  168  *
  169  */
  170 //--------------------------------------------------------------------------------------------------
  171 typedef enum
  172 {
  173     LE_CELLNET_RADIO_OFF = 0,
  174         ///< The radio is Off.
  175 
  176     LE_CELLNET_REG_EMERGENCY = 1,
  177         ///< Only Emergency calls are allowed.
  178 
  179     LE_CELLNET_REG_HOME = 2,
  180         ///< Registered, home network.
  181 
  182     LE_CELLNET_REG_ROAMING = 3,
  183         ///< Registered to a roaming network.
  184 
  185     LE_CELLNET_REG_UNKNOWN = 4
  186         ///< Unknown state.
  187 }
  188 le_cellnet_State_t;
  189 
  190 
  191 //--------------------------------------------------------------------------------------------------
  192 /**
  193  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
  194  */
  195 //--------------------------------------------------------------------------------------------------
  196 typedef struct le_cellnet_StateEventHandler* le_cellnet_StateEventHandlerRef_t;
  197 
  198 
  199 //--------------------------------------------------------------------------------------------------
  200 /**
  201  * Handler for network state changes
  202  *
  203  * @param state
  204  *        The cellular network state
  205  * @param contextPtr
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 typedef void (*le_cellnet_StateHandlerFunc_t)
  209 (
  210     le_cellnet_State_t state,
  211     void* contextPtr
  212 );
  213 
  214 //--------------------------------------------------------------------------------------------------
  215 /**
  216  * Add handler function for EVENT 'le_cellnet_StateEvent'
  217  *
  218  * This event provides information on network state changes
  219  */
  220 //--------------------------------------------------------------------------------------------------
  221 le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler
  222 (
  223     le_cellnet_StateHandlerFunc_t handlerPtr,
  224         ///< [IN]
  225 
  226     void* contextPtr
  227         ///< [IN]
  228 );
  229 
  230 //--------------------------------------------------------------------------------------------------
  231 /**
  232  * Remove handler function for EVENT 'le_cellnet_StateEvent'
  233  */
  234 //--------------------------------------------------------------------------------------------------
  235 void le_cellnet_RemoveStateEventHandler
  236 (
  237     le_cellnet_StateEventHandlerRef_t addHandlerRef
  238         ///< [IN]
  239 );
  240 
  241 //--------------------------------------------------------------------------------------------------
  242 /**
  243  * Request a cellular network
  244  *
  245  * @return
  246  *      - A reference to the cellular network
  247  *      - 0 (zero) if the network requested could not be processed
  248  */
  249 //--------------------------------------------------------------------------------------------------
  250 le_cellnet_RequestObjRef_t le_cellnet_Request
  251 (
  252     void
  253 );
  254 
  255 //--------------------------------------------------------------------------------------------------
  256 /**
  257  * Release a cellular network
  258  */
  259 //--------------------------------------------------------------------------------------------------
  260 void le_cellnet_Release
  261 (
  262     le_cellnet_RequestObjRef_t cellNetRef
  263         ///< [IN] Reference to a cellular network request.
  264 );
  265 
  266 //--------------------------------------------------------------------------------------------------
  267 /**
  268  * Set the PIN code in the config tree.
  269  *
  270  * @return
  271  *    LE_OUT_OF_RANGE    Invalid simId
  272  *  - LE_FORMAT_ERROR    PIN code is not in string format.
  273  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  274  *  - LE_OK              The function succeeded.
  275  *  - LE_FAULT           The function failed on any other errors
  276  *
  277  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  278  *       function will not return.
  279  *
  280  */
  281 //--------------------------------------------------------------------------------------------------
  282 le_result_t le_cellnet_SetSimPinCode
  283 (
  284     le_sim_Id_t simId,
  285         ///< [IN] SIM identifier.
  286 
  287     const char* pinCode
  288         ///< [IN] PIN code to insert in the config tree.
  289 );
  290 
  291 //--------------------------------------------------------------------------------------------------
  292 /**
  293  * Retreive the PIN code from the config tree.
  294  *
  295  * @return
  296  *    LE_OUT_OF_RANGE    Invalid simId
  297  *  - LE_NOT_FOUND       PIN code is not found in the config tree.
  298  *  - LE_OVERFLOW        PIN code exceeds the maximum length of 8 digits.
  299  *  - LE_UNDERFLOW       The PIN code is not long enough (min 4 digits).
  300  *  - LE_OK              The function succeeded.
  301  */
  302 //--------------------------------------------------------------------------------------------------
  303 le_result_t le_cellnet_GetSimPinCode
  304 (
  305     le_sim_Id_t simId,
  306         ///< [IN] SIM identifier.
  307 
  308     char* pinCode,
  309         ///< [OUT] Read the PIN code from the config tree.
  310 
  311     size_t pinCodeNumElements
  312         ///< [IN]
  313 );
  314 
  315 
  316 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
  317 
le_sim_Id_t
le_sim_Id_t
Definition: le_sim_interface.h:545
le_cellnet_StateHandlerFunc_t
void(* le_cellnet_StateHandlerFunc_t)(le_cellnet_State_t state, void *contextPtr)
Definition: le_cellnet_interface.h:209
le_result_t
le_result_t
Definition: le_basics.h:35
LE_CELLNET_REG_UNKNOWN
Unknown state. 
Definition: le_cellnet_interface.h:185
le_cellnet_TryConnectService
le_result_t le_cellnet_TryConnectService(void)
LE_CELLNET_REG_EMERGENCY
Only Emergency calls are allowed. 
Definition: le_cellnet_interface.h:176
le_cellnet_DisconnectService
void le_cellnet_DisconnectService(void)
LE_CELLNET_RADIO_OFF
The radio is Off. 
Definition: le_cellnet_interface.h:173
le_sim_interface.h
le_cellnet_State_t
le_cellnet_State_t
Definition: le_cellnet_interface.h:171
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:196
le_cellnet_RequestObjRef_t
struct le_cellnet_RequestObj * le_cellnet_RequestObjRef_t
Definition: le_cellnet_interface.h:162
LE_CELLNET_REG_HOME
Registered, home network. 
Definition: le_cellnet_interface.h:179
legato.h
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:182
le_cellnet_GetSimPinCode
le_result_t le_cellnet_GetSimPinCode(le_sim_Id_t simId, char *pinCode, size_t pinCodeNumElements)
le_cellnet_SetSimPinCode
le_result_t le_cellnet_SetSimPinCode(le_sim_Id_t simId, const char *pinCode)