le_data_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_data Data Connection
   12  *
   13  * @ref le_data_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * A data connection is needed for applications that exchange data with
   18  * devices where SMS messages are insufficient or not possible.  The data connection can
   19  * be over a mobile network, over Wi-Fi, or over a fixed link (e.g., Ethernet).
   20  *
   21  * The data connection service provides a basic API for requesting and releasing a data connection.
   22  *
   23  * @section le_data_binding IPC interfaces binding
   24  *
   25  * All the functions of this API are provided by the @b dataConnectionService application service.
   26  *
   27  * Here's a code sample binding to Data Connection services:
   28  * @verbatim
   29    bindings:
   30    {
   31       clientExe.clientComponent.le_data -> dataConnectionService.le_data
   32    }
   33    @endverbatim
   34  *
   35  * @section c_le_data_default Default Data Connection
   36  *
   37  * Default data connection is obtained using le_data_Request().  Before the data
   38  * connection is requested, an application registers a connection state handler using
   39  * le_data_AddConnectionStateHandler().  Once the data connection is established, the
   40  * handler will be called indicating it's now connected.  If the state of the data
   41  * connection changes, then the handler will be called with the new state. To release a data
   42  * connection, an application can use le_data_Release().
   43  *
   44  * If the default data connection is not currently available when le_data_Request() is called,
   45  * the data connection service first ensures all pre-conditions are satisfied (e.g.,
   46  * modem is registered on the network), before trying to start the data connection.
   47  *
   48  * If the default data connection is already available when le_data_Request() is called, a
   49  * new connection will not be started.  Instead, the existing data connection will be used.  This
   50  * happens if another application also requested the default data connection.  This
   51  * is how multiple applications can share the same data connection.
   52  *
   53  * Once an application makes a data connection request, it should monitor the connection state
   54  * reported to the registered connection state handler.  The application
   55  * should only try transmitting data when the state is connected, and should stop transmitting
   56  * data when the state is not connected.  If the state is not connected, the data connection
   57  * service will try to re-establish the connection. There's no need for an application to
   58  * issue a new connection request.
   59  *
   60  * The default data connection will not necessarily be released when an application calls
   61  * le_data_Release().  The data connection will be released only after le_data_Release
   62  * is called by all applications that previously called le_data_Request().
   63  *
   64  * All configuration data required for the default data connection, like the Access Point Name
   65  * (APN), will be stored in the Config database.
   66  *
   67  * @section c_le_data_configdb Configuration tree
   68  *
   69  * The configuration database path for the Data Connection Service is:
   70  * @verbatim
   71    /
   72        dataConnectionService/
   73            prefTech<string> == <technology>
   74 
   75   @endverbatim
   76  *
   77  * 'prefTech' is the preferred technology used for the data connection service. It can be set with
   78  * the following choices (string type):
   79  * - "wifi"
   80  * - "ethernet"
   81  * - "cellular"
   82  *
   83  * For example, with "cellular", the DCS will load a profile regarding a policy.
   84  * If the APN is empty the DCS will read a configuration file
   85  * (Containing all APN for MCC/MNC) to fill the APN regarding the MCC,MNC
   86  * (provided by the IMSI code).
   87  *
   88  *
   89  * @note Only "cellular" choice is available in the present version.
   90  *
   91  * @note Profile selection policy is not yet implemented. The first found profile of the selected
   92  * technology is loaded in the present version.
   93  *
   94  *
   95  * @section c_le_data_options Data Connection Options
   96  *
   97  * @note Functionality described in this section is not currently implemented; this
   98  * description is provided to outline future functionality.
   99  *
  100  * Some applications may have data connection requirements that are not met by the default data
  101  * connection (e.g., use a least cost data link or disable roaming on mobile networks). You can do this
  102  * by:
  103  * - creating a request object using le_data_CreateRequest(),
  104  * - setting optional values on that request object using le_data_SelectLeastCost() or
  105  * le_data_DisableRoaming(),
  106  * - and then submitting that object to a data connection request using le_data_SubmitRequest
  107  *
  108  * le_data_AddConnectionStateHandler() and le_data_Release() APIs can continue to be
  109  * used, as described above.
  110  *
  111  * <HR>
  112  *
  113  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  114  */
  115 /**
  116  * @file le_data_interface.h
  117  *
  118  * Legato @ref c_le_data include file.
  119  *
  120  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  121  */
  122 
  123 #ifndef LE_DATA_INTERFACE_H_INCLUDE_GUARD
  124 #define LE_DATA_INTERFACE_H_INCLUDE_GUARD
  125 
  126 
  127 #include "legato.h"
  128 
  129 //--------------------------------------------------------------------------------------------------
  130 /**
  131  *
  132  * Connect the current client thread to the service providing this API. Block until the service is
  133  * available.
  134  *
  135  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  136  * called before any other functions in this API.  Normally, ConnectService is automatically called
  137  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  138  *
  139  * This function is created automatically.
  140  */
  141 //--------------------------------------------------------------------------------------------------
  142 void le_data_ConnectService
  143 (
  144     void
  145 );
  146 
  147 //--------------------------------------------------------------------------------------------------
  148 /**
  149  *
  150  * Try to connect the current client thread to the service providing this API. Return with an error
  151  * if the service is not available.
  152  *
  153  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  154  * called before any other functions in this API.  Normally, ConnectService is automatically called
  155  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  156  *
  157  * This function is created automatically.
  158  *
  159  * @return
  160  *  - LE_OK if the client connected successfully to the service.
  161  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  162  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  163  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  164  */
  165 //--------------------------------------------------------------------------------------------------
  166 le_result_t le_data_TryConnectService
  167 (
  168     void
  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_data_DisconnectService
  184 (
  185     void
  186 );
  187 
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  * Reference returned by Request function and used by Release function
  192  */
  193 //--------------------------------------------------------------------------------------------------
  194 typedef struct le_data_RequestObj* le_data_RequestObjRef_t;
  195 
  196 
  197 //--------------------------------------------------------------------------------------------------
  198 /**
  199  * Reference type used by Add/Remove functions for EVENT 'le_data_ConnectionState'
  200  */
  201 //--------------------------------------------------------------------------------------------------
  202 typedef struct le_data_ConnectionStateHandler* le_data_ConnectionStateHandlerRef_t;
  203 
  204 
  205 //--------------------------------------------------------------------------------------------------
  206 /**
  207  * Handler for connection state changes
  208  *
  209  * @param intfName
  210  *        Interface name for the data connection
  211  * @param isConnected
  212  *        State: connected or disconnected
  213  * @param contextPtr
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 typedef void (*le_data_ConnectionStateHandlerFunc_t)
  217 (
  218     const char* intfName,
  219     bool isConnected,
  220     void* contextPtr
  221 );
  222 
  223 //--------------------------------------------------------------------------------------------------
  224 /**
  225  * Add handler function for EVENT 'le_data_ConnectionState'
  226  *
  227  * This event provides information on connection state changes
  228  */
  229 //--------------------------------------------------------------------------------------------------
  230 le_data_ConnectionStateHandlerRef_t le_data_AddConnectionStateHandler
  231 (
  232     le_data_ConnectionStateHandlerFunc_t handlerPtr,
  233         ///< [IN]
  234 
  235     void* contextPtr
  236         ///< [IN]
  237 );
  238 
  239 //--------------------------------------------------------------------------------------------------
  240 /**
  241  * Remove handler function for EVENT 'le_data_ConnectionState'
  242  */
  243 //--------------------------------------------------------------------------------------------------
  244 void le_data_RemoveConnectionStateHandler
  245 (
  246     le_data_ConnectionStateHandlerRef_t addHandlerRef
  247         ///< [IN]
  248 );
  249 
  250 //--------------------------------------------------------------------------------------------------
  251 /**
  252  * Request the default data connection
  253  *
  254  * @return
  255  *      - Reference to the data connection (to be used later for releasing the connection)
  256  *      - NULL if the data connection requested could not be processed
  257  */
  258 //--------------------------------------------------------------------------------------------------
  259 le_data_RequestObjRef_t le_data_Request
  260 (
  261     void
  262 );
  263 
  264 //--------------------------------------------------------------------------------------------------
  265 /**
  266  * Release a previously requested data connection
  267  */
  268 //--------------------------------------------------------------------------------------------------
  269 void le_data_Release
  270 (
  271     le_data_RequestObjRef_t requestRef
  272         ///< [IN] Reference to a previously requested data connection
  273 );
  274 
  275 
  276 #endif // LE_DATA_INTERFACE_H_INCLUDE_GUARD
  277 
le_data_ConnectService
void le_data_ConnectService(void)


le_result_t
le_result_t
Definition: le_basics.h:35


le_data_Release
void le_data_Release(le_data_RequestObjRef_t requestRef)


le_data_RemoveConnectionStateHandler
void le_data_RemoveConnectionStateHandler(le_data_ConnectionStateHandlerRef_t addHandlerRef)


le_data_Request
le_data_RequestObjRef_t le_data_Request(void)


le_data_RequestObjRef_t
struct le_data_RequestObj * le_data_RequestObjRef_t
Definition: le_data_interface.h:194


le_data_ConnectionStateHandlerFunc_t
void(* le_data_ConnectionStateHandlerFunc_t)(const char *intfName, bool isConnected, void *contextPtr)
Definition: le_data_interface.h:217


le_data_TryConnectService
le_result_t le_data_TryConnectService(void)


le_data_DisconnectService
void le_data_DisconnectService(void)



le_data_ConnectionStateHandlerRef_t
struct le_data_ConnectionStateHandler * le_data_ConnectionStateHandlerRef_t
Definition: le_data_interface.h:202


le_data_AddConnectionStateHandler
le_data_ConnectionStateHandlerRef_t le_data_AddConnectionStateHandler(le_data_ConnectionStateHandlerFunc_t handlerPtr, void *contextPtr)