RTFW_NETWORK_INTERFACE Structure

RTFW_NETWORK_INTERFACE represents the configuration parameters of an RTX64 network interface.

Syntax

typedef struct _RTFW_NETWORK_INTERFACE(
    size_t Size;
  
    // These fields are required for TCP/IP and NAL interfaces.
    TCHAR Name[RTFW_MAX_INTERFACE_NAME_CHARS];
    bool Enabled;
    TCHAR Driver[MAX_PATH];
    unsigned int MaxPacketSize;
    bool LinkStatus;
    TCHAR PCIBusLocation[RTFW_MAX_INTERFACE_PCIBUSLOCATION_CHARS];
    RTFW_INTERRUPT_TYPE InterruptType;
    unsigned int TransmitCompletePriority;
    unsigned int TransmitCompleteIdealProcessor;
    unsigned int NumberReceiveBuffers;
    unsigned int NumberTransmitBuffers;
    unsigned int NumberReceiveQueues;
    unsigned int NumberTransmitQueues;
    unsigned int DefaultReceiveQueue;
    DWORD InterruptIdealProcessor;
    unsigned int InterruptPriority;
    TCHAR DeviceInstanceID[RTFW_MAX_INTERFACE_INSTANCEID_CHARS];
    bool SupportTCPIP;
 
    // These fields are required only if SupportTCPIP is set to TRUE.
    unsigned int CountIPv4Configurations;
    RTFW_IPV4_CONFIGURATIONW IPv4Configurations[RTFW_MAX_IPS_PER_INTERFACE];
    TCHAR Gateway[RTFW_IPV4ADDRESS_LENGTH];
    unsigned int MTU;
    bool FilterEnabled;
    TCHAR FilterDriver[MAX_PATH];
    TCHAR IPv6Address[RTFW_MAX_INTERFACE_IPV6ADDRESS_CHARS];
    unsigned int IPv6Prefix;
    unsigned int ReceivePriority;
    DWORD ReceiveIdealProcessor;
    RTFW_SPEED_DUPLEX SpeedDuplex; // This field is required even if SupportTCPIP is not set to TRUE.
} RTFW_NETWORK_INTERFACE, * PRTFW_NETWORK_INTERFACE;

Members

The below fields are required for TCP/IP and NAL interfaces.

Size

The size of this structure (in bytes). Client code must set this member to sizeof(RTFW_NETWORK_INTERFACE) before passing this structure to any function. This is used to identify the version of this structure if it is extended.

Name

The friendly name of this interface. The maximum length of this string is 63 characters (not including the terminating null character). This member may contain only these characters: 'a' to 'z', 'A' to 'Z', '0' to '9', '_', and '-'.

Enabled

If true, the network interface is enabled. If false, the network interface is not enabled.

Driver

The absolute pathname or the simple file name of the real-time device driver (RTDLL) for this interface. This must not be a relative pathname containing '\' characters. If this is an absolute pathname, the specified RTDLL file must exist. If this is a simple file name, the RTX64 Subsystem searches for the RTDLL file when this network interface is initialized. Use API RtfwSetSearchPath or the RTX64 Control Panel to configure the Search Path used by the Subsystem.

MaxPacketSize

The maximum packet size, in bytes. This value must be within the range 1514 bytes to 16380 bytes.

LinkStatus

If true, the NIC driver will monitor and report link status (if it is capable). If false, it will not monitor for status changes.

NOTE: This property must be false if the interface belongs to the Virtual Network.

PCIBusLocation

The PCI bus location of the RTX64-owned NIC for this interface in the form "bus;device;function", where bus, device, and function are each non-negative integers. If there is only one network interface configured to use the NIC driver specified in member Driver, this member can be set to "0;0;0" instead of the actual PCI bus location of the NIC. If multiple network interfaces are configured to use the same NIC driver, all of them must have the correct PCI bus location specified in this member. This NIC must be owned by RTX64, otherwise APIs that take this structure as input will fail.

See RtfwGetRTX64Devices, which will give you the PCI bus location for a converted NIC. This information is also available graphically from the Windows Device Manager.

NOTE: This member should not be modified if the interface belongs to the Virtual Network.

InterruptType

The type of interrupt used by the NIC for this interface. See RTFW_INTERRUPT_TYPE for more information.

NOTE: This member should not be modified if the interface belongs to the Virtual Network.

TransmitCompletePriority

The real-time priority of the transmit thread for this interface. This value must be within the range 0 to 127.

TransmitCompleteIdealProcessor

The ideal processor number for the real-time transmit thread for this interface.

NumberReceiveBuffers

The number of receive buffers allocated for this interface. The minimum value for this member is 64. The maximum value for this member is hardware dependent. This value must be a multiple of 8. See Device-Specific Interface Values for device-specific defaults and value ranges.

NumberTransmitBuffers

The number of transmit buffers allocated for this interface. The minimum value for this member is 64. The maximum value for this member is hardware dependent. This value must be a multiple of 8. See Device-Specific Interface Values for device-specific defaults and value ranges.

NumberReceiveQueues

The total number of receive queues for this interface. See Device-Specific Interface Values for device-specific defaults and value ranges.

NumberTransmitQueues

The total number of transmit queues for this interface. See Device-Specific Interface Values for device-specific defaults and value ranges.

DefaultReceiveQueue

The default receive queue for this interface. The default is 0. See Device-Specific Interface Values for device-specific defaults and value ranges.

InterruptIdealProcessor

The ideal processor number for the IST thread for this interface. This value must be either RTFW_FIRST_RTSS_PROCESSOR or the processor number of one of the configured RTSS processors.

NOTE: This property should not be modified if the interface belongs to the Virtual Network.

InterruptPriority

The interrupt priority of this interface. For the IGB, I10GB, and IPCH Network Interface Cards (NICs), this value must be between 1 and 127, inclusive. For other NICs, this value must be between 0 and 127, inclusive.

DeviceInstanceID

The Instance ID of the RTX64-owned NIC for this interface. This NIC must be owned by RTX64, otherwise APIs that take this structure as input will fail with error ERROR_INVALID_PARAMETER. This member is optional. To omit this configuration parameter, the client should set this member to the empty string. When not specified, the DeviceInstanceID will default to a standard value. If it cannot recognize any of the drivers or devices, the NAL limit will be used.

SupportTCPIP

Determines whether the interface supports TCP/IP.

SpeedDuplex

The method used to establish the Ethernet link. See RTFW_SPEED_DUPLEX for more information.

The below fields are required only for TCP/IP interfaces.

These members need to be set only if member SupportTCPIP is set to TRUE.

CountIPv4Configurations

The number of valid RTFW_IPV4_CONFIGURATIONS in array member IPv4AddressNetmaskPairs. The minimum value for this member is 1. The maximum value for this member is RTFW_MAX_IPS_PER_INTERFACE.

IPv4Configurations

An array of RTFW_IPV4_CONFIGURATION structures representing IPv4 addresses and netmasks assigned to this interface. If the interface has no IPv4 addresses, set element 0 of this array to specify IPv4 address 0.0.0.0 and netmask 0.0.0.0, and also set member CountIPv4Configurations to 1.

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

Gateway

The IPv4 gateway address for this interface in dotted-quad notation. This member cannot be the empty string. Use "0.0.0.0" to indicate the absence of a gateway.

MTU

The Maximum Transmission Unit (MTU) size, in bytes, of this interface. Valid values are in the range 1500 bytes to 9000 bytes (inclusive).

FilterEnabled

If true, the filter driver is enabled for this interface. If false, it is not enabled.

FilterDriver

The absolute pathname or simple filename of the real-time filter driver RTDLL for this interface. If a simple file name is given, it is searched for using the Subsystem Search Path. This must not be a relative pathname containing '\' characters. If this is an absolute pathname, the specified RTDLL file must exist. If a simple file name is given, the Subsystem searches for the RTDLL file when the TCP/IP Stack enables this filter driver. If this member is a non-empty string, it must specify an RTDLL file. If this member is the empty string, the filter driver is removed from this interface.

IPv6Address

The IPv6 address of this interface. This value must either be a valid IPv6 address or the word "auto", which means the interface will automatically configure the IPv6 address. This value cannot be a duplicate of an existing value on an enabled interface.

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

IPv6Prefix

The network prefix length of the IPv6 address. This value must be between 4 and 128 (inclusive).

ReceivePriority

The real-time priority of the receive thread for this interface. This value must be between values 0 to 127 (inclusive).

ReceiveIdealProcessor

The ideal processor number for the real-time receive thread for this interface.

NOTE: This property should not be modified if the interface belongs to the Virtual Network.

Remarks

If you specify a relative pathname to a supported NIC driver, the function will limit the value ranges to conform to that specific driver.

You can add an interface with the same DeviceInstanceID as an existing interface if 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.

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.

Requirements

Minimum Required Version

RTX64 3.4

API changes for RTX64 4.4

Added these parameters:

SpeedDuplex

API changes for RTX64 4.0

Renamed these parameters:

FriendlyName to Name
CountIPv4Addresses to CountIPv4Configurations

Removed these parameters:

LinkStatusPriority
LinkStatusIdealProcessor

Added these parameters:

MaxPacketSize
TransmitCompletePriority
TransmitCompleteIdealProcessor
NumberReceiveQueues
NumberTransmitQueues
DefaultReceiveQueue
SpeedDuplex
SupportTCPIP

Header

RtfwAPI.h

Library

RtfwAPI.lib