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;