le_data_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_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  * @note This interface does not support yet data connection over a fixed link.
   24  *
   25  * @section le_data_binding IPC interfaces binding
   26  *
   27  * All the functions of this API are provided by the @b dataConnectionService application service.
   28  *
   29  * Here's a code sample binding to Data Connection services:
   30  * @verbatim
   31    bindings:
   32    {
   33       clientExe.clientComponent.le_data -> dataConnectionService.le_data
   34    }
   35    @endverbatim
   36  *
   37  * @section c_le_data_default Default Data Connection
   38  *
   39  * Default data connection is obtained using le_data_Request().  Before the data
   40  * connection is requested, an application registers a connection state handler using
   41  * le_data_AddConnectionStateHandler().  Once the data connection is established, the
   42  * handler will be called indicating it's now connected.  If the state of the data
   43  * connection changes, then the handler will be called with the new state. To release a data
   44  * connection, an application can use le_data_Release().
   45  *
   46  * The technology of the established connection can be retrieved with le_data_GetTechnology().
   47  *
   48  * If the default data connection is not currently available when le_data_Request() is called,
   49  * the data connection service first ensures all pre-conditions are satisfied (e.g.,
   50  * modem is registered on the network), before trying to start the data connection.
   51  *
   52  * If the default data connection is already available when le_data_Request() is called, a
   53  * new connection will not be started.  Instead, the existing data connection will be used.  This
   54  * happens if another application also requested the default data connection.  This
   55  * is how multiple applications can share the same data connection.
   56  *
   57  * Once an application makes a data connection request, it should monitor the connection state
   58  * reported to the registered connection state handler.  The application
   59  * should only try transmitting data when the state is connected, and should stop transmitting
   60  * data when the state is not connected.  If the state is not connected, the data connection
   61  * service will try to re-establish the connection. There's no need for an application to
   62  * issue a new connection request.
   63  *
   64  * The default data connection will not necessarily be released when an application calls
   65  * le_data_Release().  The data connection will be released only after le_data_Release()
   66  * is called by all applications that previously called le_data_Request().
   67  *
   68  * @section c_le_data_rank Technology rank
   69  *
   70  * The technology to use for the default data connection can be chosen by the applications
   71  * with an ordered list. If the connection becomes unavailable through a technology, the next
   72  * one in the list is used for the default data connection. If the connection is also unavailable
   73  * through the last technology of the list, the first technology will be used again.
   74  * The default sequence is @ref LE_DATA_WIFI at rank #1 and @ref LE_DATA_CELLULAR at rank #2.
   75  *
   76  * @note
   77  * - Only one list is available and therefore only one application should set the technology
   78  * preferences for the default data connection.
   79  * - The list should not be modified while the default data connection is established.
   80  * .
   81  *
   82  *
   83  * - le_data_SetTechnologyRank() sets the rank of the technology to use for the data connection
   84  * service.
   85  * le_data_SetTechnologyRank() inserts a technology into a list, so all the technologies
   86  * previously set with ranks @c r and @c r+n are automatically shifted to ranks @c r+1
   87  * and @c r+n+1. Technologies with ranks under @c r are not impacted. If the technology is already
   88  * in the list, it is removed from its current rank and added to the new rank.
   89  *
   90  * - le_data_GetFirstUsedTechnology() and le_data_GetNextUsedTechnology() let you retrieve
   91  * the different technologies of the ordered list to use for the default connection data.
   92  *
   93  * @section c_le_data_configdb Configuration tree
   94  * @copydoc c_le_data_configdbPage_Hide
   95  *
   96  * <HR>
   97  *
   98  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   99  */
  100 /**
  101  * @interface c_le_data_configdbPage_Hide
  102  *
  103  * The configuration of the Wi-Fi access point is stored in the configuration database of the
  104  * @c dataConnectionService under the following path:
  105  * @verbatim
  106     dataConnectionService:/
  107         wifi/
  108             SSID<string> == TestSsid
  109             secProtocol<int> == 3
  110             passphrase<string> == Passw0rd
  111    @endverbatim
  112  *
  113  * @note The security protocol is one of the supported protocols defined in the
  114  * @ref le_wifiClient_SecurityProtocol_t enumerator.
  115  *
  116  * @todo This solution is temporary, as the list of access points to connect to should be
  117  * managed by the Wi-Fi client. Until its API is modified, the config tree is used to configure
  118  * the only access point to use for the default data connection.
  119  *
  120  */
  121 /**
  122  * @file le_data_interface.h
  123  *
  124  * Legato @ref c_le_data include file.
  125  *
  126  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  127  */
  128 
  129 #ifndef LE_DATA_INTERFACE_H_INCLUDE_GUARD
  130 #define LE_DATA_INTERFACE_H_INCLUDE_GUARD
  131 
  132 
  133 #include "legato.h"
  134 
  135 //--------------------------------------------------------------------------------------------------
  136 /**
  137  *
  138  * Connect the current client thread to the service providing this API. Block until the service is
  139  * available.
  140  *
  141  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  142  * called before any other functions in this API.  Normally, ConnectService is automatically called
  143  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  144  *
  145  * This function is created automatically.
  146  */
  147 //--------------------------------------------------------------------------------------------------
  148 void le_data_ConnectService
  149 (
  150     void
  151 );
  152 
  153 //--------------------------------------------------------------------------------------------------
  154 /**
  155  *
  156  * Try to connect the current client thread to the service providing this API. Return with an error
  157  * if the service is not available.
  158  *
  159  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  160  * called before any other functions in this API.  Normally, ConnectService is automatically called
  161  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  162  *
  163  * This function is created automatically.
  164  *
  165  * @return
  166  *  - LE_OK if the client connected successfully to the service.
  167  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  168  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  169  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  170  */
  171 //--------------------------------------------------------------------------------------------------
  172 le_result_t le_data_TryConnectService
  173 (
  174     void
  175 );
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  *
  180  * Disconnect the current client thread from the service providing this API.
  181  *
  182  * Normally, this function doesn't need to be called. After this function is called, there's no
  183  * longer a connection to the service, and the functions in this API can't be used. For details, see
  184  * @ref apiFilesC_client.
  185  *
  186  * This function is created automatically.
  187  */
  188 //--------------------------------------------------------------------------------------------------
  189 void le_data_DisconnectService
  190 (
  191     void
  192 );
  193 
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 /**
  197  * Reference returned by Request function and used by Release function
  198  */
  199 //--------------------------------------------------------------------------------------------------
  200 typedef struct le_data_RequestObj* le_data_RequestObjRef_t;
  201 
  202 
  203 //--------------------------------------------------------------------------------------------------
  204 /**
  205  * Interface name string length.
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 #define LE_DATA_INTERFACE_NAME_MAX_LEN 100
  209 
  210 
  211 //--------------------------------------------------------------------------------------------------
  212 /**
  213  * Interface name string length. One extra byte is added for the null character.
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 #define LE_DATA_INTERFACE_NAME_MAX_BYTES 101
  217 
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Technologies.
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 typedef enum
  225 {
  226     LE_DATA_WIFI = 0,
  227         ///< Wi-Fi
  228 
  229     LE_DATA_CELLULAR = 1,
  230         ///< Cellular
  231 
  232     LE_DATA_MAX = 2
  233         ///< Unknown state.
  234 }
  235 le_data_Technology_t;
  236 
  237 
  238 //--------------------------------------------------------------------------------------------------
  239 /**
  240  * Reference type used by Add/Remove functions for EVENT 'le_data_ConnectionState'
  241  */
  242 //--------------------------------------------------------------------------------------------------
  243 typedef struct le_data_ConnectionStateHandler* le_data_ConnectionStateHandlerRef_t;
  244 
  245 
  246 //--------------------------------------------------------------------------------------------------
  247 /**
  248  * Handler for connection state changes
  249  *
  250  * @param intfName
  251  *        Interface name for the data connection
  252  * @param isConnected
  253  *        State: connected or disconnected
  254  * @param contextPtr
  255  */
  256 //--------------------------------------------------------------------------------------------------
  257 typedef void (*le_data_ConnectionStateHandlerFunc_t)
  258 (
  259     const char* intfName,
  260     bool isConnected,
  261     void* contextPtr
  262 );
  263 
  264 //--------------------------------------------------------------------------------------------------
  265 /**
  266  * Add handler function for EVENT 'le_data_ConnectionState'
  267  *
  268  * This event provides information on connection state changes
  269  */
  270 //--------------------------------------------------------------------------------------------------
  271 le_data_ConnectionStateHandlerRef_t le_data_AddConnectionStateHandler
  272 (
  273     le_data_ConnectionStateHandlerFunc_t handlerPtr,
  274         ///< [IN]
  275 
  276     void* contextPtr
  277         ///< [IN]
  278 );
  279 
  280 //--------------------------------------------------------------------------------------------------
  281 /**
  282  * Remove handler function for EVENT 'le_data_ConnectionState'
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 void le_data_RemoveConnectionStateHandler
  286 (
  287     le_data_ConnectionStateHandlerRef_t addHandlerRef
  288         ///< [IN]
  289 );
  290 
  291 //--------------------------------------------------------------------------------------------------
  292 /**
  293  * Request the default data connection
  294  *
  295  * @return
  296  *      - Reference to the data connection (to be used later for releasing the connection)
  297  *      - NULL if the data connection requested could not be processed
  298  */
  299 //--------------------------------------------------------------------------------------------------
  300 le_data_RequestObjRef_t le_data_Request
  301 (
  302     void
  303 );
  304 
  305 //--------------------------------------------------------------------------------------------------
  306 /**
  307  * Release a previously requested data connection
  308  */
  309 //--------------------------------------------------------------------------------------------------
  310 void le_data_Release
  311 (
  312     le_data_RequestObjRef_t requestRef
  313         ///< [IN] Reference to a previously requested data connection
  314 );
  315 
  316 //--------------------------------------------------------------------------------------------------
  317 /**
  318  * Set the rank of the technology used for the data connection service
  319  *
  320  * @return
  321  *      - @ref LE_OK if the technology is added to the list
  322  *      - @ref LE_BAD_PARAMETER if the technology is unknown
  323  *      - @ref LE_UNSUPPORTED if the technology is not available
  324  */
  325 //--------------------------------------------------------------------------------------------------
  326 le_result_t le_data_SetTechnologyRank
  327 (
  328     uint32_t rank,
  329         ///< [IN] Rank of the used technology
  330 
  331     le_data_Technology_t technology
  332         ///< [IN] Technology
  333 );
  334 
  335 //--------------------------------------------------------------------------------------------------
  336 /**
  337  * Get the first technology to use
  338  * @return
  339  *      - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
  340  *      - @ref LE_DATA_MAX if the list is empty
  341  */
  342 //--------------------------------------------------------------------------------------------------
  343 le_data_Technology_t le_data_GetFirstUsedTechnology
  344 (
  345     void
  346 );
  347 
  348 //--------------------------------------------------------------------------------------------------
  349 /**
  350  * Get the next technology to use
  351  * @return
  352  *      - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
  353  *      - @ref LE_DATA_MAX if the list is empty or the end of the list is reached
  354  */
  355 //--------------------------------------------------------------------------------------------------
  356 le_data_Technology_t le_data_GetNextUsedTechnology
  357 (
  358     void
  359 );
  360 
  361 //--------------------------------------------------------------------------------------------------
  362 /**
  363  * Get the technology currently used for the default data connection
  364  *
  365  * @return
  366  *      - One of the technologies from @ref le_data_Technology_t enumerator
  367  *      - @ref LE_DATA_MAX if the current technology is not set
  368  *
  369  * @note The supported technologies are @ref LE_DATA_WIFI and @ref LE_DATA_CELLULAR
  370  */
  371 //--------------------------------------------------------------------------------------------------
  372 le_data_Technology_t le_data_GetTechnology
  373 (
  374     void
  375 );
  376 
  377 
  378 #endif // LE_DATA_INTERFACE_H_INCLUDE_GUARD
  379 
LE_DATA_CELLULAR
Cellular. 
Definition: le_data_interface.h:229
le_data_Technology_t
le_data_Technology_t
Definition: le_data_interface.h:224
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:200
le_data_SetTechnologyRank
le_result_t le_data_SetTechnologyRank(uint32_t rank, le_data_Technology_t technology)
le_data_ConnectionStateHandlerFunc_t
void(* le_data_ConnectionStateHandlerFunc_t)(const char *intfName, bool isConnected, void *contextPtr)
Definition: le_data_interface.h:258
le_data_GetNextUsedTechnology
le_data_Technology_t le_data_GetNextUsedTechnology(void)
LE_DATA_MAX
Unknown state. 
Definition: le_data_interface.h:232
LE_DATA_WIFI
Wi-Fi. 
Definition: le_data_interface.h:226
le_data_TryConnectService
le_result_t le_data_TryConnectService(void)
le_data_DisconnectService
void le_data_DisconnectService(void)
legato.h
le_data_GetTechnology
le_data_Technology_t le_data_GetTechnology(void)
le_data_ConnectionStateHandlerRef_t
struct le_data_ConnectionStateHandler * le_data_ConnectionStateHandlerRef_t
Definition: le_data_interface.h:243
le_data_GetFirstUsedTechnology
le_data_Technology_t le_data_GetFirstUsedTechnology(void)
le_data_AddConnectionStateHandler
le_data_ConnectionStateHandlerRef_t le_data_AddConnectionStateHandler(le_data_ConnectionStateHandlerFunc_t handlerPtr, void *contextPtr)