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