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 /** @addtogroup le_net le_net API Reference
  224  * @{
  225  * @file le_net_common.h
  226  * @file le_net_interface.h **/
  227 //--------------------------------------------------------------------------------------------------
  228 /**
  229  * Type for handler called when a server disconnects.
  230  */
  231 //--------------------------------------------------------------------------------------------------
  232 typedef void (*le_net_DisconnectHandler_t)(void *);
  233 
  234 //--------------------------------------------------------------------------------------------------
  235 /**
  236  *
  237  * Connect the current client thread to the service providing this API. Block until the service is
  238  * available.
  239  *
  240  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  241  * called before any other functions in this API.  Normally, ConnectService is automatically called
  242  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  243  *
  244  * This function is created automatically.
  245  */
  246 //--------------------------------------------------------------------------------------------------
  247 void le_net_ConnectService
  248 (
  249     void
  250 );
  251 
  252 //--------------------------------------------------------------------------------------------------
  253 /**
  254  *
  255  * Try to connect the current client thread to the service providing this API. Return with an error
  256  * if the service is not available.
  257  *
  258  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  259  * called before any other functions in this API.  Normally, ConnectService is automatically called
  260  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  261  *
  262  * This function is created automatically.
  263  *
  264  * @return
  265  *  - LE_OK if the client connected successfully to the service.
  266  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  267  *    bound.
  268  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  269  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  270  */
  271 //--------------------------------------------------------------------------------------------------
  272 le_result_t le_net_TryConnectService
  273 (
  274     void
  275 );
  276 
  277 //--------------------------------------------------------------------------------------------------
  278 /**
  279  * Set handler called when server disconnection is detected.
  280  *
  281  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  282  * to continue without exiting, it should call longjmp() from inside the handler.
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 LE_FULL_API void le_net_SetServerDisconnectHandler
  286 (
  287     le_net_DisconnectHandler_t disconnectHandler,
  288     void *contextPtr
  289 );
  290 
  291 //--------------------------------------------------------------------------------------------------
  292 /**
  293  *
  294  * Disconnect the current client thread from the service providing this API.
  295  *
  296  * Normally, this function doesn't need to be called. After this function is called, there's no
  297  * longer a connection to the service, and the functions in this API can't be used. For details, see
  298  * @ref apiFilesC_client.
  299  *
  300  * This function is created automatically.
  301  */
  302 //--------------------------------------------------------------------------------------------------
  303 void le_net_DisconnectService
  304 (
  305     void
  306 );
  307 
  308 
  309 //--------------------------------------------------------------------------------------------------
  310 /**
  311  * Structure used to communitcate a channel's DNS Server address
  312  */
  313 //--------------------------------------------------------------------------------------------------
  314 
  315 
  316 //--------------------------------------------------------------------------------------------------
  317 /**
  318  * Structure used to communitcate a channel's Default Gateway
  319  */
  320 //--------------------------------------------------------------------------------------------------
  321 
  322 
  323 //--------------------------------------------------------------------------------------------------
  324 /**
  325  * Add or remove a route on the given channel according to the input flag in the last argument for
  326  * the given destination address its given subnet's mask prefix length.
  327  *
  328  * The channel reference in the first input argument identifies the network interface which a route
  329  * is to be added onto or removed from. Whether the operation is an add or a remove depends on the
  330  * isAdd boolean value of the last API input argument.
  331  *
  332  * The IP address and subnet input arguments specify the destination address and subnet for the
  333  * route. If it is a network route, the formats used for them are the same as used in the Linux
  334  * command "route add -net <ipAddr>/<prefixLength> dev <netInterface>". If the route is a
  335  * host route, the prefixLength input argument should be given as "" (i.e. a null string).
  336  *
  337  * @note The prefixLength parameter used to take a subnet mask (255.255.255.0) for IPv4 and prefix
  338  *       length for IPv6. Now it only takes prefix length, although compatibility code is present
  339  *       to make it compatible with previous API declaration. Providing a subnet mask is however
  340  *       deprecated and the compatibility code will be removed in a latter version.
  341  *
  342  * @return
  343  *      - LE_OK upon success, otherwise another le_result_t failure code
  344  */
  345 //--------------------------------------------------------------------------------------------------
  346 le_result_t le_net_ChangeRoute
  347 (
  348     le_dcs_ChannelRef_t channelRef,
  349         ///< [IN] the channel onto which the route change is made
  350     const char* LE_NONNULL destAddr,
  351         ///< [IN] Destination IP address for the route
  352     const char* LE_NONNULL prefixLength,
  353         ///< [IN] Destination's subnet prefix length
  354     bool isAdd
  355         ///< [IN] the change is to add (true) or delete (false)
  356 );
  357 
  358 //--------------------------------------------------------------------------------------------------
  359 /**
  360  * Set the default GW addr for the given data channel retrieved from its technology
  361  *
  362  * @return
  363  *      - LE_OK upon success, otherwise LE_FAULT
  364  */
  365 //--------------------------------------------------------------------------------------------------
  366 le_result_t le_net_SetDefaultGW
  367 (
  368     le_dcs_ChannelRef_t channelRef
  369         ///< [IN] the channel on which interface its default GW
  370         ///< addr is to be set
  371 );
  372 
  373 //--------------------------------------------------------------------------------------------------
  374 /**
  375  * Get the default GW address for the given data channel.
  376  *
  377  * @note
  378  *      Accomodates dual-stack IPv4/IPv6 addresses. If the default GW address only is only IPv4 or
  379  *      IPv6, but not both, the unused field of "addr" will be nulled.
  380  *
  381  * @return
  382  *      - LE_OK upon success, otherwise LE_FAULT
  383  */
  384 //--------------------------------------------------------------------------------------------------
  385 le_result_t le_net_GetDefaultGW
  386 (
  387     le_dcs_ChannelRef_t channelRef,
  388         ///< [IN] Channel to retrieve GW addresses
  389     le_net_DefaultGatewayAddresses_t * addrPtr
  390         ///< [OUT] Channel's Default GW addresses
  391 );
  392 
  393 //--------------------------------------------------------------------------------------------------
  394 /**
  395  * Backup the current default GW configs of the system, including both IPv4 and IPv6 as applicable.
  396  * For each client application using this API to back up this system setting, only one backup copy
  397  * is kept. When a client application makes a second call to this API, its first backup copy will
  398  * be overwritten by the newer.
  399  * Thus, le_net keeps one single backup copy per client application, and, thus, multiple backup
  400  * copies altogether.  They are kept in their LIFO (last-in-first-out) chronological order that
  401  * the sequence for client applications to call le_net_RestoreDefaltGW() should be in the exact
  402  * reverse order of their calling le_net_BackupDefaultGW() such that config backups and restorations
  403  * happen in the correct LIFO manner.
  404  */
  405 //--------------------------------------------------------------------------------------------------
  406 void le_net_BackupDefaultGW
  407 (
  408     void
  409 );
  410 
  411 //--------------------------------------------------------------------------------------------------
  412 /**
  413  * Restore the default GW configs of the system to the last backed up ones, including IPv4 and/or
  414  * IPv6 depending on whether this same client application has called le_net_SetDefaultGW() to
  415  * change the system's IPv4 and/or IPv6 configs or not. The le_net interface remembers it and
  416  * perform config restoration only as necessary when le_net_RestoreDefaultGW() is called. When
  417  * le_net_BackupDefaultGW() is called, both IPv4 and IPv6 default GW configs are archived when
  418  * present.
  419  * As le_net keeps one single backup copy per client application, and, thus, multiple backup
  420  * copies altogether, they are kept in their LIFO (last-in-first-out) chronological order that
  421  * the sequence for client applications to call le_net_RestoreDefaltGW() should be in the exact
  422  * reverse order of their calling le_net_BackupDefaultGW() such that config backups and restorations
  423  * happen in the correct LIFO manner.
  424  * If these applications do not follow this order, the le_net interface will first generate a
  425  * warning in the system log and then still go ahead to restore the configs as directed. These
  426  * applications hold the responsibility for the resulting routing configs on the device.
  427  */
  428 //--------------------------------------------------------------------------------------------------
  429 le_result_t le_net_RestoreDefaultGW
  430 (
  431     void
  432 );
  433 
  434 //--------------------------------------------------------------------------------------------------
  435 /**
  436  * Set the DNS addresses for the given data channel retrieved from its technology
  437  *
  438  * @return
  439  *      - LE_OK upon success, otherwise LE_FAULT
  440  */
  441 //--------------------------------------------------------------------------------------------------
  442 le_result_t le_net_SetDNS
  443 (
  444     le_dcs_ChannelRef_t channelRef
  445         ///< [IN] the channel from which the DNS addresses retrieved
  446         ///< will be set into the system config
  447 );
  448 
  449 //--------------------------------------------------------------------------------------------------
  450 /**
  451  * Get the DNS server addresses for the given data channel retrieved from its technology
  452  *
  453  * @note
  454  *      Can accomodate up to two dual-stack DNS server addresses. In the case that there are more
  455  *      than two server addresses, the first two addresses of each IP version will be returned. If
  456  *      there are fewer than two dual-stack addresses, or contain only one type of IPv4 or IPv6
  457  *      addresses, the unused portions of the passed structure will be nulled and returned.
  458  *
  459  * @return
  460  *      - LE_OK upon success, otherwise LE_FAULT
  461  */
  462 //--------------------------------------------------------------------------------------------------
  463 le_result_t le_net_GetDNS
  464 (
  465     le_dcs_ChannelRef_t channelRef,
  466         ///< [IN] Channel to retrieve DNS server addresses
  467     le_net_DnsServerAddresses_t * addrPtr
  468         ///< [OUT] DNS server addresses
  469 );
  470 
  471 //--------------------------------------------------------------------------------------------------
  472 /**
  473  * Remove the last added DNS addresses via the le_dcs_SetDNS API
  474  */
  475 //--------------------------------------------------------------------------------------------------
  476 void le_net_RestoreDNS
  477 (
  478     void
  479 );
  480 
  481 /** @} **/
  482 
  483 #endif // LE_NET_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:46
le_net_DisconnectHandler_t
void(* le_net_DisconnectHandler_t)(void *)
Definition: le_net_interface.h:232
le_net_DisconnectService
void le_net_DisconnectService(void)
le_net_ConnectService
void le_net_ConnectService(void)
le_net_RestoreDNS
void le_net_RestoreDNS(void)
le_net_SetServerDisconnectHandler
LE_FULL_API void le_net_SetServerDisconnectHandler(le_net_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_net_SetDNS
le_result_t le_net_SetDNS(le_dcs_ChannelRef_t channelRef)
le_net_GetDNS
le_result_t le_net_GetDNS(le_dcs_ChannelRef_t channelRef, le_net_DnsServerAddresses_t *addrPtr)
le_net_RestoreDefaultGW
le_result_t le_net_RestoreDefaultGW(void)
le_net_DnsServerAddresses_t
Definition: le_net_common.h:64
le_dcs_ChannelRef_t
struct le_dcs_Channel * le_dcs_ChannelRef_t
Definition: le_dcs_common.h:79
le_dcs_interface.h
le_net_SetDefaultGW
le_result_t le_net_SetDefaultGW(le_dcs_ChannelRef_t channelRef)
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)
legato.h
le_net_GetDefaultGW
le_result_t le_net_GetDefaultGW(le_dcs_ChannelRef_t channelRef, le_net_DefaultGatewayAddresses_t *addrPtr)
le_net_BackupDefaultGW
void le_net_BackupDefaultGW(void)
le_net_DefaultGatewayAddresses_t
Definition: le_net_common.h:79
le_net_common.h
le_net_TryConnectService
le_result_t le_net_TryConnectService(void)