API Reference

When applications need to exchange data with other devices on the packet switched data network, a data channel needs to be first established over a connectivity technology like cellular or WiFi. After such channel is successfully established, then applications can open up IP sockets on this data channel as necessary as a data pipe for sending and receiving data.

This le_net interface provides network services to Data Channel Service (DCS) client applications to install, uninstall and manage network configurations, while the le_dcs interface provides APIs for starting (associating with), stopping (disassociating from) selected channels.

Warning

Since these le_net APIs generate network and route changes that affect all services and applications on the device, users must use them with due diligence and full understanding of their global effects.

Unique Identifier

Like the le_dcs interface, many of the le_net APIs take channel reference, which is assigned and managed by le_dcs, as the input identifier to uniquely identify the channel which assigned network configurations are taken for use.

API Overview

The le_net interface provides. More details for these APIs can be found in later subsections.

Note

These following APIs have full support for cellular data channels, but only le_net_ChangeRoute() supports WiFi channels in the moment.

Change Route

An application can use the le_net_ChangeRoute() function to add or remove a host or network route onto the network interface of a given channel. The channel reference as an API input identifies the network interface which a route is to be added onto or removed from. Whether the operation is an add or a remove depends on the isAdd boolean value of the last API input argument.

The IP address and mask input arguments specify the destination address and mask for the route. The formats used for them are the same as used in the Linux command "ip route add <ipAddr>/<prefixLength> dev <netInterface>". If the route is a host route, the prefixLength input argument can be given as "" (i.e. null string) or "32". If it is a network route, it should then be specified as a prefix length, such as "16" for 255.255.0.0 or "24" for 255.255.255.0.

The following is some sample code over how to use le_net_ChangeRoute():

static le_dcs_ChannelRef_t myChannelRef;
 
void ClientChannelChangeRoute
(
    le_dcs_ChannelRef_t channelRef,
    char *ipAddr,
    char *prefixLength,
    bool isAdd
)
{
    if (LE_OK != le_net_ChangeRoute(channelRef, ipAddr, prefixLength, isAdd))
    {
        LE_ERROR("Failed to %s route to destination address %s/%s",
                 isAdd ? "add" : "remove", ipAddr, prefixLength);
    }
}
 
void AddMyHostRoute
(
    void
)
{
    ClientChannelChangeRoute(myChannelRef, "1.1.1.1", "", true);
}
 
void ChangeMySubnetRoute
(
    bool isAdd
)
{
    ClientChannelChangeRoute(myChannelRef, "1.1.0.0", "16", isAdd);
}

Default Gateway Address

The le_net interface provides four APIs for changing the default gateway address on a device. To back up the original setting before changing it, le_net_BackupDefaultGW() can be used. This will save both the default gateway address and the network interface on which it is installed. Later, when this original setting is to be restored, le_net_RestoreDefaultGW() can be used.

To install a different default GW address on a device, le_net_SetDefaultGW() can be called with the channel reference of the channel provided, which assigned default gateway address will be used as the device's. Its assigned network interface will be the interface used for this configuration. To query the channel's default GW address prior to installing it on the device, le_net_GetDefaultGW() can be used.

The following is some sample code over how to use le_net_RestoreDefaultGW() and le_net_BackupDefaultGW():

static le_dcs_ChannelRef_t myChannelRef;
static bool IsDefaultGWAdded = false;
 
void ClientConfigNetwork
(
    char *ipAddr,
    char *prefixLength,
    bool isAdd
)
{
    if (isAdd)
    {
        LE_INFO("Adding network configs for channel reference %p", myChannelRef);
        le_net_BackupDefaultGW();
        IsDefaultGWAdded = (le_net_SetDefaultGW(myChannelRef) == LE_OK);
    }
    else if (IsDefaultGWAdded)
    {
        LE_INFO("Restoring network configs for channel reference %p", myChannelRef);
        if (LE_OK != le_net_RestoreDefaultGW())
        {
            LE_ERROR("Failed to restore default gateway addresses");
        }
        IsDefaultGWAdded = false;
    }
 
    if (LE_OK != le_net_ChangeRoute(myChannelRef, ipAddr, prefixLength, isAdd))
    {
        LE_ERROR("Failed to %s route to destination %s/%s on channel with "
                 "reference %p", isAdd ? "add : "remove", ipAddr, prefixLength,
                 myChannelRef);
    }
}

DNS Server Addresses

There are three functions provided for setting a device's DNS server addresses and restoring them. When an application calls le_net_SetDNS() to provide a channel reference, le_net would query for the DNS server addresses assigned for this channel's use and add them into the device's global name server address table, which on a typical Linux-based device is at /etc/resolv.conf. The le_net interface would remember this lastly added set of DNS server address. If, for whatever reason, an application needs to know what a channel's DNS server address is, le_net_GetDNS() can be used.

When the application is done with the channel, it needs to remove these previously added DNS server addresses from the device's global name server address table, which can be done via le_net_RestoreDNS(). With that called, le_net would retrive from its last archived set of DNS server addresses and seek to delete them from the global table.

Note that for each data channel there could be zero to two DNS server addresses assigned. The le_net interface currently supports both IPv4 and IPv6.

The following is some sample code over how to use le_net_SetDNS() and le_net_RestoreDNS():

static bool isDnsAdded = false;
 
void ClientConfigDNS
(
    le_dcs_ChannelRef_t myChannelRef,
    bool isAdd
)
{
    if (isAdd)
    {
        LE_INFO("Adding DNS configs for channel reference %p", myChannelRef);
        isDnsAdded = (le_net_SetDNS(myChannelRef) == LE_OK);
    }
    else if (isDnsAdded)
    {
        LE_INFO("Restoring DNS configs for channel reference %p", myChannelRef);
        le_net_RestoreDNS();
        isDnsAdded = false;
    }
}

Copyright (C) Sierra Wireless Inc.