le_net_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_net le_net Interface
   14  *
   15  * @ref le_net_interface.h "API Reference" <br>
   16  *
   17  * When applications need to exchange data with other devices on the packet switched data network,
   18  * a data channel needs to be first established over a connectivity technology like cellular or
   19  * WiFi.  After such channel is successfully established, then applications can open up IP
   20  * sockets on this data channel as necessary as a data pipe for sending and receiving data.
   21  *
   22  * This @c le_net interface provides network services to Data Channel Service (DCS) client
   23  * applications to install, uninstall and manage network configurations, while the @c le_dcs
   24  * interface provides APIs for starting (associating with), stopping (disassociating from) selected
   25  * channels.
   26  *
   27  * @warning Since these @c le_net APIs generate network and route changes that affect all services
   28  * and applications on the device, users must use them with due diligence and full understanding
   29  * of their global effects.
   30  *
   31  *  * @section le_net_UniqueID Unique Identifier
   32  *
   33  * Like the @c le_dcs interface, many of the @c le_net APIs take channel reference, which is
   34  * assigned and managed by @c le_dcs, as the input identifier to uniquely identify the channel
   35  * which assigned network configurations are taken for use.
   36  *
   37  * @section le_net_APIOverview API Overview
   38  *
   39  * The @c le_net interface provides. More details for these APIs can be found in later subsections.
   40  *
   41  * @note These following APIs have full support for cellular data channels, but only
   42  * le_net_ChangeRoute() supports WiFi channels in the moment.
   43  *
   44  * | Function                       | Description                                                                                        |
   45  * | -------------------------------| ---------------------------------------------------------------------------------------------------|
   46  * | le_net_ChangeRoute()           | Add or remove host or network route onto the network interface of a given data channel             |
   47  * | le_net_SetDefaultGW()          | Set a device's default gateway addresses to those assigned for a given channel use                 |
   48  * | le_net_BackupDefaultGW()       | Back up a device's current default gateway addresses                                               |
   49  * | le_net_RestoreDefaultGW()      | Restore the default gateway addresses of a device previously backed up by le_net_BackupDefaultGW() |
   50  * | le_net_SetDNS()                | Set the DNS server addresses into the device's name server address table                           |
   51  * | le_net_RestoreDNS()            | Remove the DNS server addresses previously added to the device's name server address table         |
   52  *
   53  *
   54  * @subsection le_net_APIDetails_ChangeRoute Change Route
   55  *
   56  * An application can use the le_net_ChangeRoute() function to add or remove a host or network route
   57  * onto the network interface of a given channel. The channel reference as an API input identifies
   58  * the network interface which a route is to be added onto or removed from. Whether the operation
   59  * is an add or a remove depends on the isAdd boolean value of the last API input argument.
   60  *
   61  * The IP address and mask input arguments specify the destination address and mask for the route.
   62  * The formats used for them are the same as used in the Linux command "route add -net <ipAddr>
   63  * netmask <ipMask> dev <netInterface>". If the route is a host route, the ipMask input argument
   64  * can be given as "" (i.e. null string) or "255.255.255.255". If it is a network route, it
   65  * should then be specified in the quad-dotted octet format, like 255.255.0.0.
   66  *
   67  * The following is some sample code over how to use le_net_ChangeRoute():
   68  * @code
   69  *    static le_dcs_ChannelRef_t myChannelRef;
   70  *
   71  *    void ClientChannelChangeRoute
   72  *    (
   73  *        le_dcs_ChannelRef_t channelRef,
   74  *        char *ipAddr,
   75  *        char *ipAddrMask,
   76  *        bool isAdd
   77  *    )
   78  *    {
   79  *        if (LE_OK != le_net_ChangeRoute(channelRef, ipAddr, ipAddrMask, isAdd))
   80  *        {
   81  *            LE_ERROR("Failed to %s route to destination address %s mask %s",
   82  *                     isAdd ? "add" : "remove", ipAddr, ipAddrMask);
   83  *        }
   84  *    }
   85  *
   86  *    void AddMyHostRoute
   87  *    (
   88  *        void
   89  *    )
   90  *    {
   91  *        ClientChannelChangeRoute(myChannelRef, "1.1.1.1", "", true);
   92  *    }
   93  *
   94  *    void ChangeMySubnetRoute
   95  *    (
   96  *        bool isAdd
   97  *    )
   98  *    {
   99  *        ClientChannelChangeRoute(myChannelRef, "1.1.0.0", "255.255.0.0", isAdd);
  100  *    }
  101  *   @endcode
  102  *
  103  * @subsection le_net_APIDetails_DefaultGW Default Gateway Address
  104  *
  105  * The @c le_net interface provides three APIs for changing the default gateway address on a
  106  * device. To back up the original setting before changing it, le_net_BackupDefaultGW() can be
  107  * used. This will save both the default gateway address and the network interface on which it is
  108  * installed. Later, when this original setting is to be restored, le_net_RestoreDefaultGW() can
  109  * be used.
  110  *
  111  * To install a different default GW address on a device, le_net_SetDefaultGW() can be called
  112  * with the channel reference of the channel provided, which assigned default gateway address will
  113  * be used as the device's. Its assigned network interface will be the interface used for this
  114  * configuration.
  115  *
  116  * @note This set of APIs for default gateway configuration management currently only supports
  117  * cellular channels but not WiFi.
  118  *
  119  * The following is some sample code over how to use le_net_RestoreDefaultGW() and
  120  * le_net_BackupDefaultGW():
  121  * @code
  122  *    static le_dcs_ChannelRef_t myChannelRef;
  123  *    static bool IsDefaultGWAdded = false;
  124  *
  125  *    void ClientConfigNetwork
  126  *    (
  127  *        char *ipAddr,
  128  *        char *ipAddrMask,
  129  *        bool isAdd
  130  *    )
  131  *    {
  132  *        if (isAdd)
  133  *        {
  134  *            LE_INFO("Adding network configs for channel reference %p", myChannelRef);
  135  *            le_net_BackupDefaultGW();
  136  *            IsDefaultGWAdded = (le_net_SetDefaultGW(myChannelRef) == LE_OK);
  137  *        }
  138  *        else if (IsDefaultGWAdded)
  139  *        {
  140  *            LE_INFO("Restoring network configs for channel reference %p", myChannelRef);
  141  *            if (LE_OK != le_net_RestoreDefaultGW())
  142  *            {
  143  *                LE_ERROR("Failed to restore default gateway addresses");
  144  *            }
  145  *            IsDefaultGWAdded = false;
  146  *        }
  147  *
  148  *        if (LE_OK != le_net_ChangeRoute(myChannelRef, ipAddr, ipAddrMask, isAdd))
  149  *        {
  150  *            LE_ERROR("Failed to %s route to destination %s mask %s on channel with "
  151  *                     "reference %p", isAdd ? "add : "remove", ipAddr, ipAddrMask,
  152  *                     myChannelRef);
  153  *        }
  154  *    }
  155  *   @endcode
  156  *
  157  * @subsection le_net_APIDetails_DNS DNS Server Addresses
  158  *
  159  * There are two functions provided for setting a device's DNS server addresses and restoring
  160  * them. When an application calls le_net_SetDNS() to provide a channel reference, @c le_net
  161  * would query for the DNS server addresses assigned for this channel's use and add them into
  162  * the device's global name server address table, which on a typical Linux-based device is at
  163  * /etc/resolv.conf. The @c le_net interface would remember this lastly added set of DNS server
  164  * address.
  165  *
  166  * When the application is done with the channel, it needs to remove these previously added DNS
  167  * server addresses from the device's global name server address table, which can be done via
  168  * le_net_RestoreDNS(). With that called, @c le_net would retrive from its last archived
  169  * set of DNS server addresses and seek to delete them from the global table.
  170  *
  171  * Note that for each data channel there could be zero to two DNS server addresses assigned. The
  172  * @c le_net interface currently supports both IPv4 and IPv6, but cellular channels only.
  173  *
  174  * The following is some sample code over how to use le_net_SetDNS() and le_net_RestoreDNS():
  175  * @code
  176  *    static bool isDnsAdded = false;
  177  *
  178  *    void ClientConfigDNS
  179  *    (
  180  *        le_dcs_ChannelRef_t myChannelRef,
  181  *        bool isAdd
  182  *    )
  183  *    {
  184  *        if (isAdd)
  185  *        {
  186  *            LE_INFO("Adding DNS configs for channel reference %p", myChannelRef);
  187  *            IsDnsAdded = (le_net_SetDNS(myChannelRef) == LE_OK);
  188  *        }
  189  *        else if (isDnsAdded)
  190  *        {
  191  *            LE_INFO("Restoring DNS configs for channel reference %p", myChannelRef);
  192  *            le_net_RestoreDNS();
  193  *            isDnsAdded = false;
  194  *        }
  195  *    }
  196  *   @endcode
  197  *
  198  * Copyright (C) Sierra Wireless Inc.
  199  */
  200 /**
  201  * @file le_net_interface.h
  202  *
  203  * Legato @ref c_le_net include file.
  204  *
  205  * Copyright (C) Sierra Wireless Inc.
  206  */
  207 
  208 #ifndef LE_NET_INTERFACE_H_INCLUDE_GUARD
  209 #define LE_NET_INTERFACE_H_INCLUDE_GUARD
  210 
  211 
  212 #include "legato.h"
  213 
  214 // Interface specific includes
  215 #include "le_dcs_interface.h"
  216 
  217 // Internal includes for this interface
  218 #include "le_net_common.h"
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Type for handler called when a server disconnects.
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 typedef void (*le_net_DisconnectHandler_t)(void *);
  225 
  226 //--------------------------------------------------------------------------------------------------
  227 /**
  228  *
  229  * Connect the current client thread to the service providing this API. Block until the service is
  230  * available.
  231  *
  232  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  233  * called before any other functions in this API.  Normally, ConnectService is automatically called
  234  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  235  *
  236  * This function is created automatically.
  237  */
  238 //--------------------------------------------------------------------------------------------------
  239 void le_net_ConnectService
  240 (
  241     void
  242 );
  243 
  244 //--------------------------------------------------------------------------------------------------
  245 /**
  246  *
  247  * Try to connect the current client thread to the service providing this API. Return with an error
  248  * if the service is not available.
  249  *
  250  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  251  * called before any other functions in this API.  Normally, ConnectService is automatically called
  252  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  253  *
  254  * This function is created automatically.
  255  *
  256  * @return
  257  *  - LE_OK if the client connected successfully to the service.
  258  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  259  *    bound.
  260  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  261  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  262  */
  263 //--------------------------------------------------------------------------------------------------
  264 le_result_t le_net_TryConnectService
  265 (
  266     void
  267 );
  268 
  269 //--------------------------------------------------------------------------------------------------
  270 /**
  271  * Set handler called when server disconnection is detected.
  272  *
  273  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  274  * to continue without exiting, it should call longjmp() from inside the handler.
  275  */
  276 //--------------------------------------------------------------------------------------------------
  277 LE_FULL_API void le_net_SetServerDisconnectHandler
  278 (
  279     le_net_DisconnectHandler_t disconnectHandler,
  280     void *contextPtr
  281 );
  282 
  283 //--------------------------------------------------------------------------------------------------
  284 /**
  285  *
  286  * Disconnect the current client thread from the service providing this API.
  287  *
  288  * Normally, this function doesn't need to be called. After this function is called, there's no
  289  * longer a connection to the service, and the functions in this API can't be used. For details, see
  290  * @ref apiFilesC_client.
  291  *
  292  * This function is created automatically.
  293  */
  294 //--------------------------------------------------------------------------------------------------
  295 void le_net_DisconnectService
  296 (
  297     void
  298 );
  299 
  300 
  301 //--------------------------------------------------------------------------------------------------
  302 /**
  303  * Add or remove a route on the given channel according to the input flag in the last argument for
  304  * the given destination address its given subnet, which is a subnet mask for IPv4 and subnet mask's
  305  * prefix length for IPv6
  306  *
  307  * The channel reference in the first input argument identifies the network interface which a route
  308  * is to be added onto or removed from. Whether the operation is an add or a remove depends on the
  309  * isAdd boolean value of the last API input argument.
  310  *
  311  * The IP address and subnet input arguments specify the destination address and subnet for the
  312  * route. If it is a network route, the formats used for them are the same as used in the Linux
  313  * command "route -A inet add -net <ipAddr> netmask <ipSubnet> dev <netInterface>" for IPv4, and
  314  * "route -A inet6 add -net <ipAddr/prefixLength> dev <netInterface>" for IPv6. If the route is a
  315  * host route, the subnet input argument should be given as "" (i.e. a null string).
  316  *
  317  * @return
  318  *      - LE_OK upon success, otherwise another le_result_t failure code
  319  */
  320 //--------------------------------------------------------------------------------------------------
  321 le_result_t le_net_ChangeRoute
  322 (
  323     le_dcs_ChannelRef_t channelRef,
  324         ///< [IN] the channel onto which the route change is made
  325     const char* LE_NONNULL destAddr,
  326         ///< [IN] Destination IP address for the route
  327     const char* LE_NONNULL destSubnet,
  328         ///< [IN] Destination's subnet: IPv4 netmask or IPv6 prefix
  329         ///< length
  330     bool isAdd
  331         ///< [IN] the change is to add (true) or delete (false)
  332 );
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Set the default GW addr for the given data channel retrieved from its technology
  337  *
  338  * @return
  339  *      - LE_OK upon success, otherwise LE_FAULT
  340  */
  341 //--------------------------------------------------------------------------------------------------
  342 le_result_t le_net_SetDefaultGW
  343 (
  344     le_dcs_ChannelRef_t channelRef
  345         ///< [IN] the channel on which interface its default GW
  346         ///< addr is to be set
  347 );
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Backup default GW config of the system
  352  */
  353 //--------------------------------------------------------------------------------------------------
  354 void le_net_BackupDefaultGW
  355 (
  356     void
  357 );
  358 
  359 //--------------------------------------------------------------------------------------------------
  360 /**
  361  * Backup default GW config of the system
  362  */
  363 //--------------------------------------------------------------------------------------------------
  364 le_result_t le_net_RestoreDefaultGW
  365 (
  366     void
  367 );
  368 
  369 //--------------------------------------------------------------------------------------------------
  370 /**
  371  * Set the DNS addresses for the given data channel retrieved from its technology
  372  *
  373  * @return
  374  *      - LE_OK upon success, otherwise LE_FAULT
  375  */
  376 //--------------------------------------------------------------------------------------------------
  377 le_result_t le_net_SetDNS
  378 (
  379     le_dcs_ChannelRef_t channelRef
  380         ///< [IN] the channel from which the DNS addresses retrieved
  381         ///< will be set into the system config
  382 );
  383 
  384 //--------------------------------------------------------------------------------------------------
  385 /**
  386  * Remove the last added DNS addresses via the le_dcs_SetDNS API
  387  */
  388 //--------------------------------------------------------------------------------------------------
  389 void le_net_RestoreDNS
  390 (
  391     void
  392 );
  393 
  394 #endif // LE_NET_INTERFACE_H_INCLUDE_GUARD
le_net_RestoreDNS
void le_net_RestoreDNS(void)
le_net_TryConnectService
le_result_t le_net_TryConnectService(void)
le_net_ChangeRoute
le_result_t le_net_ChangeRoute(le_dcs_ChannelRef_t channelRef, const char *LE_NONNULL destAddr, const char *LE_NONNULL destSubnet, bool isAdd)
le_net_BackupDefaultGW
void le_net_BackupDefaultGW(void)
le_net_SetDNS
le_result_t le_net_SetDNS(le_dcs_ChannelRef_t channelRef)
le_result_t
le_result_t
Definition: le_basics.h:35
le_net_SetServerDisconnectHandler
LE_FULL_API void le_net_SetServerDisconnectHandler(le_net_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_net_ConnectService
void le_net_ConnectService(void)
le_net_RestoreDefaultGW
le_result_t le_net_RestoreDefaultGW(void)
le_net_SetDefaultGW
le_result_t le_net_SetDefaultGW(le_dcs_ChannelRef_t channelRef)
le_dcs_interface.h
LE_FULL_API
#define LE_FULL_API
Definition: le_basics.h:288
le_net_DisconnectService
void le_net_DisconnectService(void)
le_net_DisconnectHandler_t
void(* le_net_DisconnectHandler_t)(void *)
Definition: le_net_interface.h:224