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  * @note When using the cellular technology, the data connection service can use a specific cellular
   71  * data profile if it has been set with the le_data_SetCellularProfileIndex() API or in the
   72  * configuration tree. Otherwise the default cellular profile is used. The profile in use can be
   73  * retrieved by le_data_GetCellularProfileIndex(). The profile to use is loaded when the first data
   74  * connection is initiated. The cellular data profile can be configured by le_mdc APIs or
   75  * cm data tool.
   76  *
   77  * @section c_le_data_routing Data connection routing
   78  *
   79  * @subsection c_le_data_defaultRoute Default route
   80  *
   81  * By default, the default route is automatically configured by the data connection service using
   82  * the modem parameters when the cellular technology is connected. If an application wishes to
   83  * configure its own default route, it should deactivate it in the data connection service by
   84  * setting the parameter @c useDefaultRoute to false in the configuration tree (see @ref
   85  * c_le_data_configdb):
   86  * @verbatim
   87    $ config set dataConnectionService:/routing/useDefaultRoute false bool
   88    @endverbatim
   89  *
   90  * @note The default route activation status can be retrieved with le_data_GetDefaultRouteStatus().
   91  *
   92  * @warning The default route activation status is only read at start-up and the change will only
   93  * be effective after a Legato restart.
   94  *
   95  * A sample code showing how to set the modem default route if it isn't set by the data connection
   96  * server is presented below:
   97  * @snippet "apps/test/dataConnectionService/dataConnectionServiceRouteTest/dcsRouteTestComp/dcsRouteTest.c" DefaultRoute
   98  *
   99  * @subsection c_le_data_addRemoveRoute Add or remove a route
  100  *
  101  * Specific routes can be added for the cellular connection with le_data_AddRoute(), which is
  102  * used to route IP packets to a specific address through the data connection service interface.
  103  * When the routes are not necessary anymore, they can be removed with le_data_DelRoute().
  104  * @code
  105  *   // Add a route to the 8.8.8.8 IP address for the cellular connection
  106  *   le_data_AddRoute("8.8.8.8");
  107  *
  108  *   // Remove a route to the 8.8.8.8 IP address for the cellular connection
  109  *   le_data_DelRoute("8.8.8.8");
  110  *   @endcode
  111  *
  112  * @section c_le_data_rank Technology rank
  113  *
  114  * The technology to use for the default data connection can be chosen by the applications
  115  * with an ordered list. If the connection becomes unavailable through a technology, the next
  116  * one in the list is used for the default data connection. If the connection is also unavailable
  117  * through the last technology of the list, the first technology will be used again.
  118  * The default sequence is @ref LE_DATA_WIFI at rank #1 and @ref LE_DATA_CELLULAR at rank #2.
  119  *
  120  * @note
  121  * - Only one list is available and therefore only one application should set the technology
  122  * preferences for the default data connection.
  123  * - The list should not be modified while the default data connection is established.
  124  * .
  125  *
  126  *
  127  * - le_data_SetTechnologyRank() sets the rank of the technology to use for the data connection
  128  * service.
  129  * le_data_SetTechnologyRank() inserts a technology into a list, so all the technologies
  130  * previously set with ranks @c r and @c r+n are automatically shifted to ranks @c r+1
  131  * and @c r+n+1. Technologies with ranks under @c r are not impacted. If the technology is already
  132  * in the list, it is removed from its current rank and added to the new rank.
  133  *
  134  * - le_data_GetFirstUsedTechnology() and le_data_GetNextUsedTechnology() let you retrieve
  135  * the different technologies of the ordered list to use for the default connection data.
  136  *
  137  * @section c_le_data_configdb Configuration tree
  138  * @copydoc c_le_data_configdbPage_Hide
  139  *
  140  * <HR>
  141  *
  142  * Copyright (C) Sierra Wireless Inc.
  143  */
  144 /**
  145  * @interface c_le_data_configdbPage_Hide
  146  *
  147  * The configuration of the default routing, the Wi-Fi access point and the cellular profile are
  148  * stored in the configuration database of the @c dataConnectionService under the following path:
  149  * @verbatim
  150     dataConnectionService:/
  151         routing/
  152             useDefaultRoute<bool> == true
  153         wifi/
  154             SSID<string> == TestSsid
  155             secProtocol<int> == 3
  156             passphrase<string> == Passw0rd
  157         cellular/
  158             profileIndex<int> == index
  159    @endverbatim
  160  *
  161  * @note The security protocol is one of the supported protocols defined in the
  162  * @ref le_wifiClient_SecurityProtocol_t enumerator.
  163  *
  164  * @todo This solution is temporary, as the list of access points to connect to should be
  165  * managed by the Wi-Fi client. Until its API is modified, the config tree is used to configure
  166  * the only access point to use for the default data connection.
  167  *
  168  */
  169 /**
  170  * @file le_data_interface.h
  171  *
  172  * Legato @ref c_le_data include file.
  173  *
  174  * Copyright (C) Sierra Wireless Inc.
  175  */
  176 
  177 #ifndef LE_DATA_INTERFACE_H_INCLUDE_GUARD
  178 #define LE_DATA_INTERFACE_H_INCLUDE_GUARD
  179 
  180 
  181 #include "legato.h"
  182 
  183 // Interface specific includes
  184 #include "le_mdc_interface.h"
  185 
  186 
  187 //--------------------------------------------------------------------------------------------------
  188 /**
  189  * Type for handler called when a server disconnects.
  190  */
  191 //--------------------------------------------------------------------------------------------------
  192 typedef void (*le_data_DisconnectHandler_t)(void *);
  193 
  194 //--------------------------------------------------------------------------------------------------
  195 /**
  196  *
  197  * Connect the current client thread to the service providing this API. Block until the service is
  198  * available.
  199  *
  200  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  201  * called before any other functions in this API.  Normally, ConnectService is automatically called
  202  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  203  *
  204  * This function is created automatically.
  205  */
  206 //--------------------------------------------------------------------------------------------------
  207 void le_data_ConnectService
  208 (
  209     void
  210 );
  211 
  212 //--------------------------------------------------------------------------------------------------
  213 /**
  214  *
  215  * Try to connect the current client thread to the service providing this API. Return with an error
  216  * if the service is not available.
  217  *
  218  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  219  * called before any other functions in this API.  Normally, ConnectService is automatically called
  220  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  221  *
  222  * This function is created automatically.
  223  *
  224  * @return
  225  *  - LE_OK if the client connected successfully to the service.
  226  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  227  *    bound.
  228  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  229  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  230  */
  231 //--------------------------------------------------------------------------------------------------
  232 le_result_t le_data_TryConnectService
  233 (
  234     void
  235 );
  236 
  237 //--------------------------------------------------------------------------------------------------
  238 /**
  239  * Set handler called when server disconnection is detected.
  240  *
  241  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  242  * to continue without exiting, it should call longjmp() from inside the handler.
  243  */
  244 //--------------------------------------------------------------------------------------------------
  245 void le_data_SetServerDisconnectHandler
  246 (
  247     le_data_DisconnectHandler_t disconnectHandler,
  248     void *contextPtr
  249 );
  250 
  251 //--------------------------------------------------------------------------------------------------
  252 /**
  253  *
  254  * Disconnect the current client thread from the service providing this API.
  255  *
  256  * Normally, this function doesn't need to be called. After this function is called, there's no
  257  * longer a connection to the service, and the functions in this API can't be used. For details, see
  258  * @ref apiFilesC_client.
  259  *
  260  * This function is created automatically.
  261  */
  262 //--------------------------------------------------------------------------------------------------
  263 void le_data_DisconnectService
  264 (
  265     void
  266 );
  267 
  268 
  269 //--------------------------------------------------------------------------------------------------
  270 /**
  271  * Interface name string length.
  272  */
  273 //--------------------------------------------------------------------------------------------------
  274 #define LE_DATA_INTERFACE_NAME_MAX_LEN 100
  275 
  276 //--------------------------------------------------------------------------------------------------
  277 /**
  278  * Interface name string length. One extra byte is added for the null character.
  279  */
  280 //--------------------------------------------------------------------------------------------------
  281 #define LE_DATA_INTERFACE_NAME_MAX_BYTES 101
  282 
  283 //--------------------------------------------------------------------------------------------------
  284 /**
  285  * Reference returned by Request function and used by Release function
  286  */
  287 //--------------------------------------------------------------------------------------------------
  288 typedef struct le_data_RequestObj* le_data_RequestObjRef_t;
  289 
  290 
  291 //--------------------------------------------------------------------------------------------------
  292 /**
  293  * Technologies.
  294  */
  295 //--------------------------------------------------------------------------------------------------
  296 typedef enum
  297 {
  298     LE_DATA_WIFI = 0,
  299         ///< Wi-Fi
  300     LE_DATA_CELLULAR = 1,
  301         ///< Cellular
  302     LE_DATA_MAX = 2
  303         ///< Unknown state.
  304 }
  305 le_data_Technology_t;
  306 
  307 
  308 //--------------------------------------------------------------------------------------------------
  309 /**
  310  * Reference type used by Add/Remove functions for EVENT 'le_data_ConnectionState'
  311  */
  312 //--------------------------------------------------------------------------------------------------
  313 typedef struct le_data_ConnectionStateHandler* le_data_ConnectionStateHandlerRef_t;
  314 
  315 
  316 //--------------------------------------------------------------------------------------------------
  317 /**
  318  * Handler for connection state changes
  319  */
  320 //--------------------------------------------------------------------------------------------------
  321 typedef void (*le_data_ConnectionStateHandlerFunc_t)
  322 (
  323     const char* LE_NONNULL intfName,
  324         ///< Interface name for the data connection
  325     bool isConnected,
  326         ///< State: connected or disconnected
  327     void* contextPtr
  328         ///<
  329 );
  330 
  331 //--------------------------------------------------------------------------------------------------
  332 /**
  333  * Add handler function for EVENT 'le_data_ConnectionState'
  334  *
  335  * This event provides information on connection state changes
  336  */
  337 //--------------------------------------------------------------------------------------------------
  338 le_data_ConnectionStateHandlerRef_t le_data_AddConnectionStateHandler
  339 (
  340     le_data_ConnectionStateHandlerFunc_t handlerPtr,
  341         ///< [IN]
  342     void* contextPtr
  343         ///< [IN]
  344 );
  345 
  346 //--------------------------------------------------------------------------------------------------
  347 /**
  348  * Remove handler function for EVENT 'le_data_ConnectionState'
  349  */
  350 //--------------------------------------------------------------------------------------------------
  351 void le_data_RemoveConnectionStateHandler
  352 (
  353     le_data_ConnectionStateHandlerRef_t handlerRef
  354         ///< [IN]
  355 );
  356 
  357 //--------------------------------------------------------------------------------------------------
  358 /**
  359  * Request the default data connection
  360  *
  361  * @return
  362  *      - Reference to the data connection (to be used later for releasing the connection)
  363  *      - NULL if the data connection requested could not be processed
  364  */
  365 //--------------------------------------------------------------------------------------------------
  366 le_data_RequestObjRef_t le_data_Request
  367 (
  368     void
  369 );
  370 
  371 //--------------------------------------------------------------------------------------------------
  372 /**
  373  * Release a previously requested data connection
  374  */
  375 //--------------------------------------------------------------------------------------------------
  376 void le_data_Release
  377 (
  378     le_data_RequestObjRef_t requestRef
  379         ///< [IN] Reference to a previously requested data connection
  380 );
  381 
  382 //--------------------------------------------------------------------------------------------------
  383 /**
  384  * Set the rank of the technology used for the data connection service
  385  *
  386  * @return
  387  *      - @ref LE_OK if the technology is added to the list
  388  *      - @ref LE_BAD_PARAMETER if the technology is unknown
  389  *      - @ref LE_UNSUPPORTED if the technology is not available
  390  */
  391 //--------------------------------------------------------------------------------------------------
  392 le_result_t le_data_SetTechnologyRank
  393 (
  394     uint32_t rank,
  395         ///< [IN] Rank of the used technology
  396     le_data_Technology_t technology
  397         ///< [IN] Technology
  398 );
  399 
  400 //--------------------------------------------------------------------------------------------------
  401 /**
  402  * Get the first technology to use
  403  * @return
  404  *      - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
  405  *      - @ref LE_DATA_MAX if the list is empty
  406  */
  407 //--------------------------------------------------------------------------------------------------
  408 le_data_Technology_t le_data_GetFirstUsedTechnology
  409 (
  410     void
  411 );
  412 
  413 //--------------------------------------------------------------------------------------------------
  414 /**
  415  * Get the next technology to use
  416  * @return
  417  *      - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
  418  *      - @ref LE_DATA_MAX if the list is empty or the end of the list is reached
  419  */
  420 //--------------------------------------------------------------------------------------------------
  421 le_data_Technology_t le_data_GetNextUsedTechnology
  422 (
  423     void
  424 );
  425 
  426 //--------------------------------------------------------------------------------------------------
  427 /**
  428  * Get the technology currently used for the default data connection
  429  *
  430  * @return
  431  *      - One of the technologies from @ref le_data_Technology_t enumerator
  432  *      - @ref LE_DATA_MAX if the current technology is not set
  433  *
  434  * @note The supported technologies are @ref LE_DATA_WIFI and @ref LE_DATA_CELLULAR
  435  */
  436 //--------------------------------------------------------------------------------------------------
  437 le_data_Technology_t le_data_GetTechnology
  438 (
  439     void
  440 );
  441 
  442 //--------------------------------------------------------------------------------------------------
  443 /**
  444  * Get the default route activation status for the data connection service interface.
  445  *
  446  * @return
  447  *      - true:  the default route is set by the data connection service
  448  *      - false: the default route is not set by the data connection service
  449  */
  450 //--------------------------------------------------------------------------------------------------
  451 bool le_data_GetDefaultRouteStatus
  452 (
  453     void
  454 );
  455 
  456 //--------------------------------------------------------------------------------------------------
  457 /**
  458  * Add a route on the data connection service interface, if the data session is connected using
  459  * the cellular technology and has an IPv4 or IPv6 address.
  460  *
  461  * @return
  462  *      - LE_OK             on success
  463  *      - LE_UNSUPPORTED    cellular technology not currently used
  464  *      - LE_BAD_PARAMETER  incorrect IP address
  465  *      - LE_FAULT          for all other errors
  466  *
  467  * @note Limitations:
  468  *      - only IPv4 is supported for the moment
  469  *      - route only added for a cellular connection
  470  */
  471 //--------------------------------------------------------------------------------------------------
  472 le_result_t le_data_AddRoute
  473 (
  474     const char* LE_NONNULL ipDestAddrStr
  475         ///< [IN] The destination IP address in dotted
  476         ///< format
  477 );
  478 
  479 //--------------------------------------------------------------------------------------------------
  480 /**
  481  * Delete a route on the data connection service interface, if the data session is connected using
  482  * the cellular technology and has an IPv4 or IPv6 address.
  483  *
  484  * @return
  485  *      - LE_OK             on success
  486  *      - LE_UNSUPPORTED    cellular technology not currently used
  487  *      - LE_BAD_PARAMETER  incorrect IP address
  488  *      - LE_FAULT          for all other errors
  489  *
  490  * @note Limitations:
  491  *      - only IPv4 is supported for the moment
  492  *      - route only removed for a cellular connection
  493  */
  494 //--------------------------------------------------------------------------------------------------
  495 le_result_t le_data_DelRoute
  496 (
  497     const char* LE_NONNULL ipDestAddrStr
  498         ///< [IN] The destination IP address in dotted
  499         ///< format
  500 );
  501 
  502 //--------------------------------------------------------------------------------------------------
  503 /**
  504  * Get the cellular profile index used by the data connection service when the cellular technology
  505  * is active.
  506  *
  507  * @return
  508  *      - Cellular profile index
  509  */
  510 //--------------------------------------------------------------------------------------------------
  511 int32_t le_data_GetCellularProfileIndex
  512 (
  513     void
  514 );
  515 
  516 //--------------------------------------------------------------------------------------------------
  517 /**
  518  * Set the cellular profile index used by the data connection service when the cellular technology
  519  * is active.
  520  *
  521  * @return
  522  *      - LE_OK             on success
  523  *      - LE_BAD_PARAMETER  if the profile index is invalid
  524  *      - LE_BUSY           the cellular connection is in use
  525  */
  526 //--------------------------------------------------------------------------------------------------
  527 le_result_t le_data_SetCellularProfileIndex
  528 (
  529     int32_t profileIndex
  530         ///< [IN] Cellular profile index to be used
  531 );
  532 
  533 #endif // LE_DATA_INTERFACE_H_INCLUDE_GUARD
LE_DATA_CELLULAR
Cellular. 
Definition: le_data_interface.h:300
le_data_Technology_t
le_data_Technology_t
Definition: le_data_interface.h:296
le_data_ConnectService
void le_data_ConnectService(void)
le_data_ConnectionStateHandlerFunc_t
void(* le_data_ConnectionStateHandlerFunc_t)(const char *LE_NONNULL intfName, bool isConnected, void *contextPtr)
Definition: le_data_interface.h:322
le_result_t
le_result_t
Definition: le_basics.h:35
le_data_Release
void le_data_Release(le_data_RequestObjRef_t requestRef)
le_mdc_interface.h
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:288
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_AddRoute
le_result_t le_data_AddRoute(const char *LE_NONNULL ipDestAddrStr)
LE_DATA_MAX
Unknown state. 
Definition: le_data_interface.h:302
LE_DATA_WIFI
Wi-Fi. 
Definition: le_data_interface.h:298
le_data_GetCellularProfileIndex
int32_t le_data_GetCellularProfileIndex(void)
le_data_TryConnectService
le_result_t le_data_TryConnectService(void)
le_data_DisconnectService
void le_data_DisconnectService(void)
legato.h
le_data_SetCellularProfileIndex
le_result_t le_data_SetCellularProfileIndex(int32_t profileIndex)
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_DelRoute
le_result_t le_data_DelRoute(const char *LE_NONNULL ipDestAddrStr)
le_data_DisconnectHandler_t
void(* le_data_DisconnectHandler_t)(void *)
Definition: le_data_interface.h:192
le_data_ConnectionStateHandlerRef_t
struct le_data_ConnectionStateHandler * le_data_ConnectionStateHandlerRef_t
Definition: le_data_interface.h:313
le_data_GetDefaultRouteStatus
bool le_data_GetDefaultRouteStatus(void)
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)