netRouteAdd (Function)

This function adds a network route to the system.

The routes tells the system how to send socket data to the receiver.

Normally the system handles it automatically based on the subnet for each network, using the NAT Gateway as the default route, see netSetNATParam.

When using more complex networks (Multiple subnets, VPN, or similar) it may be necessary to access devices on different subnets that can not use the default route.

In these cases, the netRouteAdd function can be used to create new routes for specific IP address ranges.

It is also possible to create multiple prioritized routes to the same destination by using different metric values, providing automatic fallback when an interface is disconnected.

The routes added with this function are not persistent across reset.

Input:

index : INT (1..25)

The index of the route.

iface : SINT

The network interface to use for the route. (See Network for available interfaces)

ip : DINT

The destination IP address or network for the route.

This is used in conjunction with the netmask to define the IP ranges handled by this route.

To match a single IP address, set ip to the IP address and netmask to 255.255.255.255.

To mach an IP range, set netmask to the netmask for the range and IP to the first IP address that matches the mask, i.e. if using the netmask 255.255.255.0, the IP address could be 192.168.1.0 and would match 192.168.1.1 - 192.168.1.254.

netmask : DINT (default -1 ( 255.255.255.255 ))

The subnet mask that, when combined with the destination IP address, determines the subnet which the route applies to.

gateway : DINT (default -1)

The IP address of the gateway to route the communication through.

When the gateway is all zeros, no gateway will be used and the destination IP range must be directly available on the network interface.

If set to -1, the gateway address of the network interface is used automatically.

If the gateway to the destination is on a different subnet than the directly attached network, a route must first be created to that gateway.

metric : INT (0..32000, default 0)

The metric of the route, which determines which route to use.

Lower values give higher priority.

Returns:

Declaration:

FUNCTION netRouteAdd;
VAR_INPUT
   index      : INT;
   ip         : DINT;
   netmask    : DINT := -1; // Mask : 255.255.255.255
   gateway    : DINT := -1;
   metric     : INT := 0;
   iface      : SINT;
END_VAR;

Example:

INCLUDE rtcu.inc
 
VAR
   _route_     : netRouteGet;
END_VAR;
 
FUNCTION show_iface : STRING;
VAR_INPUT
   iface    : SINT;
END_VAR;
 
CASE iface OF
   1: show_iface := "Cellular";
   2: show_iface := "LAN1";
   3: show_iface := "LAN2";
   4: show_iface := "WLAN";
   5: show_iface := "AP";
ELSE
      show_iface := "<unknown>";
END_CASE;
END_FUNCTION;
 
FUNCTION route_list;
VAR
   str         : STRING;
   tmp         : STRING;
   i           : INT;
END_VAR;
 
   // Show header
   DebugMsg(message := " Destination      Gateway          Subnet mask      Metric  Iface  Status");
 
   // Iterate routes
   FOR i := 1 TO 100 DO
      // Get route
      _route_(index := i);
      IF _route_.status < 1 THEN EXIT; END_IF;
 
      // Build output
      str := " ";
      tmp := sockIPToName(ip := _route_.ip);
      WHILE strLen(str := tmp) < 17 DO tmp := tmp + " "; END_WHILE;
      str := str + tmp;
      tmp := sockIPToName(ip := _route_.gateway);
      WHILE strLen(str := tmp) < 17 DO tmp := tmp + " "; END_WHILE;
      str := str + tmp;
      tmp := sockIPToName(ip := _route_.netmask);
      WHILE strLen(str := tmp) < 17 DO tmp := tmp + " "; END_WHILE;
      str := str + tmp;
      tmp := intToStr(v := _route_.metric);
      WHILE strLen(str := tmp) < 8 DO tmp := tmp + " "; END_WHILE;
      str := str + tmp;
      tmp := show_iface(iface := _route_.iface);
      WHILE strLen(str := tmp) < 7 DO tmp := tmp + " "; END_WHILE;
      str := str + tmp;
      str := str + intToStr(v := _route_.status);
 
      // Show
      DebugMsg(message := str);
 
   END_FOR;
END_FUNCTION;
 
PROGRAM example;
VAR
   rc    : INT;
END_VAR;
 
   // Add route
   rc := netRouteAdd(
                     index   := 1
                    ,iface   := 2
                    ,ip      := sockIPFromName(str := "10.0.0.0")
                    ,netmask := sockIPFromName(str := "255.0.0.0")
                    ,gateway := sockIPFromName(str := "192.168.1.1")
                    ,metric  := 100
                    );
   IF rc < 1 THEN
      DebugFmt(message := "  netRouteAdd=\1", v1 := rc);
      RETURN;
   END_IF;
 
   // List routes
   route_list();
 
   // Remove route
   rc := netRouteDelete(index := 1);
   IF rc < 1 THEN
      DebugFmt(message := "  netRouteDel=\1", v1 := rc);
      RETURN;
   END_IF;
 
BEGIN
END;
END_PROGRAM;