Snapdragon® Telematics Application Framework (TelAF) Interface Specification
Network Service

API Reference

The Network service APIs unified TelAF networking APIs for configuration.

Network service provides APIs for applications to manage route, gateway, DNS, NAT, GSB, VLAN, Socksv5, L2tp, filter, and firewall.

IPC interfaces binding

All functions of this API are provided by the tafNetSvc application service.

The following example shows how to bind to the network service. 

bindings:
{
    clientExe.clientComponent.taf_net -> tafNetSvc.taf_net
}

Route management

Routes can be changed using taf_net_ChangeRoute with the interface name, destination address, prefix length, metric, and isAdd passed as parameters.

The following example shows how to change a route. This example adds a route with interface "eth0", destination address "192.168.10.0", subnet mask "255.255.255.0", and metric 0. 

result=taf_net_ChangeRoute("eth0","192.168.10.0",24,0,TAF_NET_ADD);

Before changing the route, an application can register a state handler using taf_net_AddRouteChangeHandler(). Once the route is changed, the handler will be called. 

routeChangeHandlerRef = taf_net_AddRouteChangeHandler(
                        (taf_net_RouteChangeHandlerFunc_t)NetRouteChangeHandlerFunc, NULL);

To remove the handler, an application can use taf_net_RemoveRouteChangeHandler(routeChangeHandlerRef);

Gateway management

Gateway management provides APIs to set, backup, restore system default gateway, and query interface gateway, including IPv4 and IPv6 addresses.

The default gateway can be set using taf_net_SetDefaultGW with the interface name passed as a parameter. The gateway addresses of the interface will be retrieved and set into the system.

The following example shows how to set the default gateway. This example sets the system default gateways with gateway addresses from interface "rmnet_data1", including IPv4 and IPv6 gateways. 

result=taf_net_SetDefaultGW("rmnet_data1");

Before setting the default gateway, an application can register a state handler using taf_net_AddGatewayChangeHandler(). Once the default gateway is set, the handler will be called. 

gatewayChangeHandlerRef = taf_net_AddGatewayChangeHandler(
                        (taf_net_GatewayChangeHandlerFunc_t)NetGatewayChangeHandlerFunc, NULL);

To remove the handler, an application can use taf_net_RemoveGatewayChangeHandler(gatewayChangeHandlerRef);

The following APIs are supported for gateway management

DNS management

DNS can be set using taf_net_SetDNS with the interface name passed as the parameter. The DNS addresses of the interface will be retrieved and set into the system including the primary IPv4 and IPv6 addresses and secondary IPv4 and IPv6 addresses.

The following example shows how to set DNS. This example sets the system DNS addresses with DNS addresses from interface "rmnet_data1", including IPv4 and IPv6 DNS addresses. 

result=taf_net_SetDNS("rmnet_data1");

Before setting the DNS, an application can register a state handler using taf_net_AddDNSChangeHandler(). Once the DNS is set, the handler will be called. 

DNSChangeHandlerRef = taf_net_AddDNSChangeHandler(
                        (taf_net_DNSChangeHandlerFunc_t)NetDNSChangeHandlerFunc, NULL);

To remove the handler, an application can use taf_net_RemoveDNSChangeHandler(DNSChangeHandlerRef).

taf_net_GetInterfaceDNS() can be used to query the interface DNS addresses, including the primary IPv4 and IPv6 addresses and secondary IPv4 and IPv6 addresses.

Static destination NAT management

Static destination NAT can be added, removed, and retrieved for the default PDN and on-demand PDN.

Static destination NAT can be added using taf_net_AddDestNatEntryOnDefaultPdn with the private IP address, private port, global port, and IP protocol type passed as parameters. The destination NAT will be added into iptables if the default PDN is brought up.

The following example shows how to add a static destination NAT entry on the default PDN. This example adds a static destination NAT entry on the default PDN with private IP address "192.168.225.30", private port 5000, global port 5000 and TCP protocol type. 

result=taf_net_AddDestNatEntryOnDefaultPdn("192.168.225.30", 5000, 5000, TAF_NET_TCP);

The following APIs are supported for NAT management

Note
When adding a static destination NAT entry, and changing the default profile ID the static destination NAT entry will be changed accordingly.
After binding VLAN with the profile ID, the corresponding destination NAT for on-demand PDN can be added into iptables.

VLAN management

VLAN management provides APIs for VLAN creation, VLAN binding, and VLAN information querying.

VLAN can be created using taf_net_CreateVlan with VLAN ID and isAccelerated passed as parameters. After VLAN is created, the application can use taf_net_AddVlanInterface to add VLAN interface and then use taf_net_BindVlanWithProfile to bind VLAN with profile.

The following example shows how to create a VLAN. This example creates a VLAN with VLAN ID 5, and the VLAN will not be accelerated. The return value is the VLAN reference. 

vlanReference = taf_net_CreateVlan(5, false);
if (!vlanReference)
{
   LE_INFO("isAccelerated conflicts with old value");
   return LE_FAULT;
}

The following APIs are supported for VLAN

A VLAN interface can be added using taf_net_AddVlanInterface with VLAN reference and interface type passed as parameters.

The following example shows how to add a VLAN interface. This example adds a VLAN interface into VLAN with interface type TAF_NET_ETH. 

result = taf_net_AddVlanInterface(vlanReference, TAF_NET_ETH);

The following APIs are supported for VLAN interface

Note
When adding or deleting a VLAN interface for a VLAN with isAccelerated as true, if the interface is the first added or last deleted for the interface type in the system, the system will automatically reboot after 5 seconds.

The following APIs are supported for VLAN information retrieval.

VLAN can be bound with a profile using taf_net_BindVlanWithProfile with the VLAN reference and profile ID passed as parameters.

The following example shows how to bind VLAN with a profile. This example binds VLAN with profile ID 5. 

result = taf_net_BindVlanWithProfile(vlanReference, 5);

The API taf_net_UnbindVlanFromProfile can be used to unbind VLAN from a profile.

Note
If binding VLAN with the default profile ID, the system will automatically reboot after 5 seconds.
If unbinding VLAN from default profile id, the system will automatically reboot after 5 seconds.

L2TP management

L2TP management provides APIs for enabling and disabling L2TP, creating and removing tunnels, adding and removing sessions, setting UDP ports, starting and stopping tunnels, and querying L2TP information.

Tunnels can be created using taf_net_CreateTunnel. After creating a tunnel, the application can use taf_net_SetTunnelUdpPort to set the UDP port for UDP encapsulation protocol, taf_net_AddSession to add a session to the tunnel, and then taf_net_StartTunnel to start the tunnel.

The following example shows how to create a tunnel. This example creates a tunnel with IP encapsulation protocol, local tunnel ID 1, peer tunnel ID 1, peer IP address fd53:7cb8:383:5::2, and interface name eth0.5. The return value is the tunnel reference. 

tunnelReference = taf_net_CreateTunnel(TAF_NET_L2TP_IP, 1, 1, "fd53:7cb8:383:5::2", "eth0.5");
if (!tunnelReference)
{
   LE_INFO("Failed to create a tunnel");
   return LE_FAULT;
}

An application can synchrounously start a tunnel using taf_net_StartTunnel with the tunnel reference passed as a parameter.

result = taf_net_StartTunnel(tunnelReference);
if (result != LE_OK)
{
   LE_INFO("Failed to start a tunnel");
   return LE_FAULT;
}

An application can asynchrounously start a tunnel using taf_net_StartTunnelAsync with the tunnel reference and handler function passed as parameters.

taf_net_StartTunnelAsync(tunnelRef,StartTunnelAsyncHandlerFunc,NULL);

Before asynchrounously starting a tunnel, an application defines a handler function. Once the tunnel is started, the handler function will be called.

void StartTunnelAsyncHandlerFunc(taf_net_TunnelRef_t tunnelRef,
                                 le_result_t result,
                                 void* contextPtr)
{
    LE_INFO("**** Handler for Start Tunnel Asynchronously (Begin)****");
    LE_INFO("tunnelRef= %p, result: %d", tunnelRef, result);
    LE_INFO("**** Handler for Start Tunnel Asynchronously (End)****");
}

The following APIs are supported for tunnel configuration.

The following APIs are supported for tunnel information retrieval.

SOCKS management

Socket Secure (SOCKS) management provides APIs for enabling and disabling SOCKS, setting and getting SOCKS authentication method type, setting and getting LAN interface, and adding and removing SOCKS associations between usernames and profile IDs.

SOCKS can be enabled using taf_net_EnableSocks. After setting the authentication method type and LAN interface, and adding the association the application can enable SOCKS.

The following example shows how to enable SOCKS. This example starts a SOCKS application which listens on port 1080.

result = taf_net_EnableSocks();
if (result != LE_OK)
{
   LE_INFO("Failed to enable SOCKS");
   return LE_FAULT;
}

An application can asynchrounously enable SOCKS using taf_net_EnableSocksAsync with a handler function passed as a parameter.

taf_net_EnableSocksAsync(StartSocksAsyncHandlerFunc,NULL);

Before asynchrounously enabling SOCKS, an application defines a handler function. Once SOCKS is enabled, the handler function will be called.

 static void StartSocksAsyncHandlerFunc
 (
     le_result_t result, void* contextPtr
 )
 {
     LE_INFO("**** Handler for start socks Asynchronously (Begin)****");
     LE_INFO("result: %d", result);
     LE_INFO("**** Handler for start socks Asynchronously (End)****");
 }

The following APIs are supported for SOCKS management.

Note
If changing the SOCKS authentication method or association, the application needs to disable and enable SOCKS to use the new method or username.

GSB management

Generic software bridge (GSB) management provides APIs for enabling and disabling GSB, adding and removing GSB, and querying GSB information. GSB enables hardware IP acceleration (IPA) for traffic on physical interfaces corresponding to the NON-QTI WLAN and ethernet chips.

Note
GSB APIs are not supported on SA515M. The following example shows how to add GSB. This example adds an interface named "wlan0", of TAF_NET_GSB_WLAN_AP type, and with 800 Mbps bandwidth.
result = taf_net_AddGsb("wlan0", TAF_NET_GSB_WLAN_AP, 900);
if (result != LE_OK)
{
   LE_INFO("Failed to add GSB");
   return LE_FAULT;
}

An application can enable GSB using taf_net_EnableGsb after adding GSB. The following example shows how to enable GSB.

result = taf_net_EnableGsb();
if (result != LE_OK)
{
   LE_INFO("Failed to enable GSB");
   return LE_FAULT;
}

The following APIs are supported for GSB management.

phone ID support.

Network service provides APIs with phone ID as one of the input parameters in the DSSA/DSDA mode. The application can call these APIs on the wanted phone ID

profileReference = BindVlanWithProfileEx(vlanReference, 2, 5);

The following APIs are added for supporting phone ID selection.

VLAN priority.

Network service provides APIs to support VLAN priority.

The following example shows how to create a VLAN and set the VLAN priority. This example creates a VLAN with VLAN ID 5 and priority 6.

vlanReference = taf_net_CreateVlan(5, false);
if (!vlanReference)
{
   LE_INFO("isAccelerated conflicts with old value");
   return LE_FAULT;
}
result = taf_net_SetVlanPriority(vlanReference, 6);

The following APIs are added for supporting VLAN priority.