RtfwCreateNetworkInterface

RtfwCreateNetworkInterface creates a new RTX64 network interface to be used by the RT-TCP/IP Stack.

Syntax

bool RtfwCreateNetworkInterface(
    const RTFW_NETWORK_INTERFACE * pInterface,
    unsigned int reserved
);

Parameters

pInterface

A pointer to a RTFW_NETWORK_INTERFACE structure that contains the initial configuration of the new network interface. The Size member must be set to sizeof(RTFW_NETWORK_INTERFACE), otherwise this function's behavior is undefined.

reserved

This parameter must always be set to zero.

Return Value

The function returns true if it succeeds. Otherwise, it returns false. Call GetLastError for additional error information.

Possible error codes:

Error Code	Meaning
RT_ERROR_STRUCTURE_TOO_SMALL	The Size member of a structure is too small.
RT_ERROR_DEVICE_INSTANCE_ID_INVALID	An enabled interface already exists with the same DeviceInstanceID.
RT_ERROR_PCI_BUS_LOCATION_INVALID	An enabled interface already exists with the same PCIBusLocation.
RT_ERROR_IPV6_ADDRESS_INVALID	The specified IPv6 address is invalid. See Remarks for a list of valid and invalid IPv6 addresses.
RT_ERROR_IPV4_ADDRESS_INVALID	The specified IPv4 address is invalid. See Remarks for a list of valid and invalid IPv4 addresses.

Remarks

See Device-Specific Interface Values for device-specific defaults and value ranges.

Some devices may have more restrictive limits than what is documented or enforced by the Control Panel. To see the most accurate limits, consult the appropriate specification guide for your device.

If the RT-TCP/IP Stack is running when this function succeeds, it sets the last error value to RT_ERROR_RESTART_NETWORK. RtfwRestartRequired will report that the RT-TCP/IP Stack must be restarted.

NOTE: The RT-TCP/IP Stack must be restarted for the change to take effect.

IPv4 addresses must adhere to the following rules to be considered valid and accepted:

There must be exactly 4 groups of decimal digits (called “octets”) separated by a period (‘.’).
- Examples violating this rule: 10.0.8.5.9, 192.168.3
No octet has a ‘0’ digit immediately to the left of another digit.
- Examples violating this rule: 10.1.02.5, 192.167.00.1
Every octet must be between 0 and 255 (inclusive).
- Examples violating this rule: 10.300.2.3, 704.111.201.99
The first octet is between 0 and 223.
- Examples violating this rule: 250.1.2.3, 224.111.201.99

The following IPv6 addresses are valid and will be accepted:

A unicast or anycast address
A unique local address

The following IPv6 addresses are invalid and will not be accepted:

A duplicate address on more than one enabled interface
A multicast address
The loopback address
A link-local address
Address ::0

Any pathname passed to this function must not be a network pathname. This includes:

A pathname with a drive letter that specifies a mapped file share.
A UNC path: a pathname that starts with \\servername.

You can add an interface with the same DeviceInstanceID as an existing interface as long as the existing interface is disabled. If you were to then enable the first interface, it may result in error code RT_ERROR_DEVICE_INSTANCE_ID_INVALID, which indicates there is already an enabled interface with the same DeviceInstanceID.

The same is true when adding an interface with the same PCIBusLocation as an existing interface, only this would result in error code RT_ERROR_PCI_BUS_LOCATION_INVALID when the other enabled interface with the same PCIBusLocation was detected.
The same is also true when adding an interface with the same IPv4 address or IPv6 address, only this would result in error codes RT_ERROR_IPV4_ADDRESS_INVALID and RT_ERROR_IPV6_ADDRESS_INVALID respectively, when the other enabled interface with the same IPv4 or IPv6 address was detected.

Requirements

Minimum Required Version	RTX64 3.4
Header	RtfwAPI.h
Library	RtfwAPI.lib