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_GetDefaultGW()          | Get the default gateway address(es) for the channel provided (retrieved from DHCP lease file)      |
   49  * | le_net_BackupDefaultGW()       | Back up a device's current default gateway addresses                                               |
   50  * | le_net_RestoreDefaultGW()      | Restore the default gateway addresses of a device previously backed up by le_net_BackupDefaultGW() |
   51  * | le_net_SetDNS()                | Set the DNS server addresses into the device's name server address table                           |
   52  * | le_net_GetDNS()                | Get the DNS server addresses for the channel provided (retrieved from DHCP lease file)             |
   53  * | le_net_RestoreDNS()            | Remove the DNS server addresses previously added to the device's name server address table         |
   54  *
   55  *
   56  * @subsection le_net_APIDetails_ChangeRoute Change Route
   57  *
   58  * An application can use the le_net_ChangeRoute() function to add or remove a host or network route
   59  * onto the network interface of a given channel. The channel reference as an API input identifies
   60  * the network interface which a route is to be added onto or removed from. Whether the operation
   61  * is an add or a remove depends on the isAdd boolean value of the last API input argument.
   62  *
   63  * The IP address and mask input arguments specify the destination address and mask for the route.
   64  * The formats used for them are the same as used in the Linux command
   65  *   "ip route add <ipAddr>/<prefixLength> dev <netInterface>".
   66  * If the route is a host route, the prefixLength input argument can be given as
   67  * "" (i.e. null string) or "32".
   68  * If it is a network route, it should then be specified as a prefix length, such as "16" for
   69  * 255.255.0.0 or "24" for 255.255.255.0.
   70  *
   71  * The following is some sample code over how to use le_net_ChangeRoute():
   72  * @code
   73  *    static le_dcs_ChannelRef_t myChannelRef;
   74  *
   75  *    void ClientChannelChangeRoute
   76  *    (
   77  *        le_dcs_ChannelRef_t channelRef,
   78  *        char *ipAddr,
   79  *        char *prefixLength,
   80  *        bool isAdd
   81  *    )
   82  *    {
   83  *        if (LE_OK != le_net_ChangeRoute(channelRef, ipAddr, prefixLength, isAdd))
   84  *        {
   85  *            LE_ERROR("Failed to %s route to destination address %s/%s",
   86  *                     isAdd ? "add" : "remove", ipAddr, prefixLength);
   87  *        }
   88  *    }
   89  *
   90  *    void AddMyHostRoute
   91  *    (
   92  *        void
   93  *    )
   94  *    {
   95  *        ClientChannelChangeRoute(myChannelRef, "1.1.1.1", "", true);
   96  *    }
   97  *
   98  *    void ChangeMySubnetRoute
   99  *    (
  100  *        bool isAdd
  101  *    )
  102  *    {
  103  *        ClientChannelChangeRoute(myChannelRef, "1.1.0.0", "16", isAdd);
  104  *    }
  105  *   @endcode
  106  *
  107  * @subsection le_net_APIDetails_DefaultGW Default Gateway Address
  108  *
  109  * The @c le_net interface provides four APIs for changing the default gateway address on a
  110  * device. To back up the original setting before changing it, le_net_BackupDefaultGW() can be
  111  * used. This will save both the default gateway address and the network interface on which it is
  112  * installed. Later, when this original setting is to be restored, le_net_RestoreDefaultGW() can
  113  * be used.
  114  *
  115  * To install a different default GW address on a device, le_net_SetDefaultGW() can be called
  116  * with the channel reference of the channel provided, which assigned default gateway address will
  117  * be used as the device's. Its assigned network interface will be the interface used for this
  118  * configuration. To query the channel's default GW address prior to installing it on the device,
  119  * le_net_GetDefaultGW() can be used.
  120  *
  121  * The following is some sample code over how to use le_net_RestoreDefaultGW() and
  122  * le_net_BackupDefaultGW():
  123  * @code
  124  *    static le_dcs_ChannelRef_t myChannelRef;
  125  *    static bool IsDefaultGWAdded = false;
  126  *
  127  *    void ClientConfigNetwork
  128  *    (
  129  *        char *ipAddr,
  130  *        char *prefixLength,
  131  *        bool isAdd
  132  *    )
  133  *    {
  134  *        if (isAdd)
  135  *        {
  136  *            LE_INFO("Adding network configs for channel reference %p", myChannelRef);
  137  *            le_net_BackupDefaultGW();
  138  *            IsDefaultGWAdded = (le_net_SetDefaultGW(myChannelRef) == LE_OK);
  139  *        }
  140  *        else if (IsDefaultGWAdded)
  141  *        {
  142  *            LE_INFO("Restoring network configs for channel reference %p", myChannelRef);
  143  *            if (LE_OK != le_net_RestoreDefaultGW())
  144  *            {
  145  *                LE_ERROR("Failed to restore default gateway addresses");
  146  *            }
  147  *            IsDefaultGWAdded = false;
  148  *        }
  149  *
  150  *        if (LE_OK != le_net_ChangeRoute(myChannelRef, ipAddr, prefixLength, isAdd))
  151  *        {
  152  *            LE_ERROR("Failed to %s route to destination %s/%s on channel with "
  153  *                     "reference %p", isAdd ? "add : "remove", ipAddr, prefixLength,
  154  *                     myChannelRef);
  155  *        }
  156  *    }
  157  *   @endcode
  158  *
  159  * @subsection le_net_APIDetails_DNS DNS Server Addresses
  160  *
  161  * There are three functions provided for setting a device's DNS server addresses and restoring
  162  * them. When an application calls le_net_SetDNS() to provide a channel reference, @c le_net
  163  * would query for the DNS server addresses assigned for this channel's use and add them into
  164  * the device's global name server address table, which on a typical Linux-based device is at
  165  * /etc/resolv.conf. The @c le_net interface would remember this lastly added set of DNS server
  166  * address. If, for whatever reason, an application needs to know what a channel's DNS server
  167  * address is, le_net_GetDNS() can be used.
  168  *
  169  * When the application is done with the channel, it needs to remove these previously added DNS
  170  * server addresses from the device's global name server address table, which can be done via
  171  * le_net_RestoreDNS(). With that called, @c le_net would retrive from its last archived
  172  * set of DNS server addresses and seek to delete them from the global table.
  173  *
  174  * Note that for each data channel there could be zero to two DNS server addresses assigned. The
  175  * @c le_net interface currently supports both IPv4 and IPv6.
  176  *
  177  * The following is some sample code over how to use le_net_SetDNS() and le_net_RestoreDNS():
  178  * @code
  179  *    static bool isDnsAdded = false;
  180  *
  181  *    void ClientConfigDNS
  182  *    (
  183  *        le_dcs_ChannelRef_t myChannelRef,
  184  *        bool isAdd
  185  *    )
  186  *    {
  187  *        if (isAdd)
  188  *        {
  189  *            LE_INFO("Adding DNS configs for channel reference %p", myChannelRef);
  190  *            isDnsAdded = (le_net_SetDNS(myChannelRef) == LE_OK);
  191  *        }
  192  *        else if (isDnsAdded)
  193  *        {
  194  *            LE_INFO("Restoring DNS configs for channel reference %p", myChannelRef);
  195  *            le_net_RestoreDNS();
  196  *            isDnsAdded = false;
  197  *        }
  198  *    }
  199  *   @endcode
  200  *
  201  * Copyright (C) Sierra Wireless Inc.
  202  */
  203 /**
  204  * @file le_net_interface.h
  205  *
  206  * Legato @ref c_le_net include file.
  207  *
  208  * Copyright (C) Sierra Wireless Inc.
  209  */
  210 
  211 #ifndef LE_NET_INTERFACE_H_INCLUDE_GUARD
  212 #define LE_NET_INTERFACE_H_INCLUDE_GUARD
  213 
  214 
  215 #include "legato.h"
  216 
  217 // Interface specific includes
  218 #include "le_dcs_interface.h"
  219 
  220 // Internal includes for this interface
  221 #include "le_net_common.h"
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Type for handler called when a server disconnects.
  225  */
  226 //--------------------------------------------------------------------------------------------------
  227 typedef void (*le_net_DisconnectHandler_t)(void *);
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  *
  232  * Connect the current client thread to the service providing this API. Block until the service is
  233  * available.
  234  *
  235  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  236  * called before any other functions in this API.  Normally, ConnectService is automatically called
  237  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  238  *
  239  * This function is created automatically.
  240  */
  241 //--------------------------------------------------------------------------------------------------
  242 void le_net_ConnectService
  243 (
  244     void
  245 );
  246 
  247 //--------------------------------------------------------------------------------------------------
  248 /**
  249  *
  250  * Try to connect the current client thread to the service providing this API. Return with an error
  251  * if the service is not available.
  252  *
  253  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  254  * called before any other functions in this API.  Normally, ConnectService is automatically called
  255  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  256  *
  257  * This function is created automatically.
  258  *
  259  * @return
  260  *  - LE_OK if the client connected successfully to the service.
  261  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  262  *    bound.
  263  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  264  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  265  */
  266 //--------------------------------------------------------------------------------------------------
  267 le_result_t le_net_TryConnectService
  268 (
  269     void
  270 );
  271 
  272 //--------------------------------------------------------------------------------------------------
  273 /**
  274  * Set handler called when server disconnection is detected.
  275  *
  276  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  277  * to continue without exiting, it should call longjmp() from inside the handler.
  278  */
  279 //--------------------------------------------------------------------------------------------------
  280 LE_FULL_API void le_net_SetServerDisconnectHandler
  281 (
  282     le_net_DisconnectHandler_t disconnectHandler,
  283     void *contextPtr
  284 );
  285 
  286 //--------------------------------------------------------------------------------------------------
  287 /**
  288  *
  289  * Disconnect the current client thread from the service providing this API.
  290  *
  291  * Normally, this function doesn't need to be called. After this function is called, there's no
  292  * longer a connection to the service, and the functions in this API can't be used. For details, see
  293  * @ref apiFilesC_client.
  294  *
  295  * This function is created automatically.
  296  */
  297 //--------------------------------------------------------------------------------------------------
  298 void le_net_DisconnectService
  299 (
  300     void
  301 );
  302 
  303 
  304 //--------------------------------------------------------------------------------------------------
  305 /**
  306  * Structure used to communitcate a channel's DNS Server address
  307  */
  308 //--------------------------------------------------------------------------------------------------
  309 
  310 
  311 //--------------------------------------------------------------------------------------------------
  312 /**
  313  * Structure used to communitcate a channel's Default Gateway
  314  */
  315 //--------------------------------------------------------------------------------------------------
  316 
  317 
  318 //--------------------------------------------------------------------------------------------------
  319 /**
  320  * Add or remove a route on the given channel according to the input flag in the last argument for
  321  * the given destination address its given subnet's mask prefix length.
  322  *
  323  * The channel reference in the first input argument identifies the network interface which a route
  324  * is to be added onto or removed from. Whether the operation is an add or a remove depends on the
  325  * isAdd boolean value of the last API input argument.
  326  *
  327  * The IP address and subnet input arguments specify the destination address and subnet for the
  328  * route. If it is a network route, the formats used for them are the same as used in the Linux
  329  * command "route add -net <ipAddr>/<prefixLength> dev <netInterface>". If the route is a
  330  * host route, the prefixLength input argument should be given as "" (i.e. a null string).
  331  *
  332  * @note The prefixLength parameter used to take a subnet mask (255.255.255.0) for IPv4 and prefix
  333  *       length for IPv6. Now it only takes prefix length, although compatibility code is present
  334  *       to make it compatible with previous API declaration. Providing a subnet mask is however
  335  *       deprecated and the compatibility code will be removed in a latter version.
  336  *
  337  * @return
  338  *      - LE_OK upon success, otherwise another le_result_t failure code
  339  */
  340 //--------------------------------------------------------------------------------------------------
  341 le_result_t le_net_ChangeRoute
  342 (
  343     le_dcs_ChannelRef_t channelRef,
  344         ///< [IN] the channel onto which the route change is made
  345     const char* LE_NONNULL destAddr,
  346         ///< [IN] Destination IP address for the route
  347     const char* LE_NONNULL prefixLength,
  348         ///< [IN] Destination's subnet prefix length
  349     bool isAdd
  350         ///< [IN] the change is to add (true) or delete (false)
  351 );
  352 
  353 //--------------------------------------------------------------------------------------------------
  354 /**
  355  * Set the default GW addr for the given data channel retrieved from its technology
  356  *
  357  * @return
  358  *      - LE_OK upon success, otherwise LE_FAULT
  359  */
  360 //--------------------------------------------------------------------------------------------------
  361 le_result_t le_net_SetDefaultGW
  362 (
  363     le_dcs_ChannelRef_t channelRef
  364         ///< [IN] the channel on which interface its default GW
  365         ///< addr is to be set
  366 );
  367 
  368 //--------------------------------------------------------------------------------------------------
  369 /**
  370  * Get the default GW address for the given data channel.
  371  *
  372  * @note
  373  *      Accomodates dual-stack IPv4/IPv6 addresses. If the default GW address only is only IPv4 or
  374  *      IPv6, but not both, the unused field of "addr" will be nulled.
  375  *
  376  * @return
  377  *      - LE_OK upon success, otherwise LE_FAULT
  378  */
  379 //--------------------------------------------------------------------------------------------------
  380 le_result_t le_net_GetDefaultGW
  381 (
  382     le_dcs_ChannelRef_t channelRef,
  383         ///< [IN] Channel to retrieve GW addresses
  384     le_net_DefaultGatewayAddresses_t * addrPtr
  385         ///< [OUT] Channel's Default GW addresses
  386 );
  387 
  388 //--------------------------------------------------------------------------------------------------
  389 /**
  390  * Backup the current default GW configs of the system, including both IPv4 and IPv6 as applicable.
  391  * For each client application using this API to back up this system setting, only one backup copy
  392  * is kept. When a client application makes a second call to this API, its first backup copy will
  393  * be overwritten by the newer.
  394  * Thus, le_net keeps one single backup copy per client application, and, thus, multiple backup
  395  * copies altogether.  They are kept in their LIFO (last-in-first-out) chronological order that
  396  * the sequence for client applications to call le_net_RestoreDefaltGW() should be in the exact
  397  * reverse order of their calling le_net_BackupDefaultGW() such that config backups and restorations
  398  * happen in the correct LIFO manner.
  399  */
  400 //--------------------------------------------------------------------------------------------------
  401 void le_net_BackupDefaultGW
  402 (
  403     void
  404 );
  405 
  406 //--------------------------------------------------------------------------------------------------
  407 /**
  408  * Restore the default GW configs of the system to the last backed up ones, including IPv4 and/or
  409  * IPv6 depending on whether this same client application has called le_net_SetDefaultGW() to
  410  * change the system's IPv4 and/or IPv6 configs or not. The le_net interface remembers it and
  411  * perform config restoration only as necessary when le_net_RestoreDefaultGW() is called. When
  412  * le_net_BackupDefaultGW() is called, both IPv4 and IPv6 default GW configs are archived when
  413  * present.
  414  * As le_net keeps one single backup copy per client application, and, thus, multiple backup
  415  * copies altogether, they are kept in their LIFO (last-in-first-out) chronological order that
  416  * the sequence for client applications to call le_net_RestoreDefaltGW() should be in the exact
  417  * reverse order of their calling le_net_BackupDefaultGW() such that config backups and restorations
  418  * happen in the correct LIFO manner.
  419  * If these applications do not follow this order, the le_net interface will first generate a
  420  * warning in the system log and then still go ahead to restore the configs as directed. These
  421  * applications hold the responsibility for the resulting routing configs on the device.
  422  */
  423 //--------------------------------------------------------------------------------------------------
  424 le_result_t le_net_RestoreDefaultGW
  425 (
  426     void
  427 );
  428 
  429 //--------------------------------------------------------------------------------------------------
  430 /**
  431  * Set the DNS addresses for the given data channel retrieved from its technology
  432  *
  433  * @return
  434  *      - LE_OK upon success, otherwise LE_FAULT
  435  */
  436 //--------------------------------------------------------------------------------------------------
  437 le_result_t le_net_SetDNS
  438 (
  439     le_dcs_ChannelRef_t channelRef
  440         ///< [IN] the channel from which the DNS addresses retrieved
  441         ///< will be set into the system config
  442 );
  443 
  444 //--------------------------------------------------------------------------------------------------
  445 /**
  446  * Get the DNS server addresses for the given data channel retrieved from its technology
  447  *
  448  * @note
  449  *      Can accomodate up to two dual-stack DNS server addresses. In the case that there are more
  450  *      than two server addresses, the first two addresses of each IP version will be returned. If
  451  *      there are fewer than two dual-stack addresses, or contain only one type of IPv4 or IPv6
  452  *      addresses, the unused portions of the passed structure will be nulled and returned.
  453  *
  454  * @return
  455  *      - LE_OK upon success, otherwise LE_FAULT
  456  */
  457 //--------------------------------------------------------------------------------------------------
  458 le_result_t le_net_GetDNS
  459 (
  460     le_dcs_ChannelRef_t channelRef,
  461         ///< [IN] Channel to retrieve DNS server addresses
  462     le_net_DnsServerAddresses_t * addrPtr
  463         ///< [OUT] DNS server addresses
  464 );
  465 
  466 //--------------------------------------------------------------------------------------------------
  467 /**
  468  * Remove the last added DNS addresses via the le_dcs_SetDNS API
  469  */
  470 //--------------------------------------------------------------------------------------------------
  471 void le_net_RestoreDNS
  472 (
  473     void
  474 );
  475 
  476 #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_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:45
le_net_SetServerDisconnectHandler
LE_FULL_API void le_net_SetServerDisconnectHandler(le_net_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_net_GetDNS
le_result_t le_net_GetDNS(le_dcs_ChannelRef_t channelRef, le_net_DnsServerAddresses_t *addrPtr)
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_apiFeatures.h:40
le_net_ChangeRoute
le_result_t le_net_ChangeRoute(le_dcs_ChannelRef_t channelRef, const char *LE_NONNULL destAddr, const char *LE_NONNULL prefixLength, bool isAdd)
le_net_DisconnectService
void le_net_DisconnectService(void)
le_net_DisconnectHandler_t
void(* le_net_DisconnectHandler_t)(void *)
Definition: le_net_interface.h:227
le_net_GetDefaultGW
le_result_t le_net_GetDefaultGW(le_dcs_ChannelRef_t channelRef, le_net_DefaultGatewayAddresses_t *addrPtr)