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