Rtfwnl2CreateInterface

Rtfwnl2CreateInterface creates a new wRTOS network interface to be used by the Network Link Layer (NL2).

Syntax

Copy

bool Rtfwnl2CreateInterface(
    [in] const RTFW_NL2_INTERFACE * pNL2Interface
);

Parameters

[in] pNL2Interface

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

Return Value

If the function succeeds, it returns true. If the function fails, it returns false. Call GetLastError to obtain an error code.

Possible error codes:

Error code	Meaning
RT_ERROR_DEVICE_INSTANCE_ID_INVALID	The network interface configuration instance ID is not valid.
RT_ERROR_DRIVER_INVALID	The network interface configuration driver name is not valid.
RT_ERROR_DUPLICATE_DEVICE_INSTANCE_ID	The specified instance ID of the wRTOS-owned NIC for this interface is a duplicate.
RT_ERROR_DUPLICATE_MSIX_MESSAGE_ID	The message ID for non-queue interrupts is a duplicate.
RT_ERROR_DUPLICATE_NETWORK_DEVICE	The specified network device is a duplicate.
RT_ERROR_DUPLICATE_TX_QUEUE_INDEX	The specified transmit queue index is a duplicate.
RT_ERROR_INTERFACE_NAME_ALREADY_EXISTS	The specified interface name already exists.
RT_ERROR_INTERFACE_NAME_INVALID	The specified interface name is not valid. This name may only contain these characters: 'a' to 'z', 'A' to 'Z', '0' to '9', '_', and '-'.
RT_ERROR_INTERFACE_NAME_NOT_FOUND	The specified interface name could not be found.
RT_ERROR_INTERRUPT_TYPE_INVALID	The type of interrupt used by the NIC for this interface is not valid.
RT_ERROR_INVALID_IDEAL_PROCESSOR	The specified ideal processor is not valid.
RT_ERROR_INVALID_INGRESS_TIMESTAMPING_RULE	The specified ingress timestamping rule is not valid.
RT_ERROR_INVALID_INGRESS_TIMESTAMPING_UDP_PORT	The specified ingress timestamping UDP port is not valid.
RT_ERROR_INVALID_MSIX_MESSAGE_IST_IDEAL_PROCESSOR	The specified ideal processor for the IST for MSI-X interrupt types is not valid.
RT_ERROR_INVALID_MSIX_MESSAGE_IST_PRIORITY	The specified priority of the IST for MSI-X interrupt types is not valid.
RT_ERROR_INVALID_MSIX_NON_QUEUE_MESSAGE_ID	The specified message ID for non-queue interrupts is not valid.
RT_ERROR_INVALID_NONMSIX_IST_IDEAL_PROCESSOR	The specified ideal processor for the IST for non-MSI-X interrupt types is not valid.
RT_ERROR_INVALID_NONMSIX_IST_PRIORITY	The specified priority of the IST for non-MSI-X interrupt types is not valid.
RT_ERROR_INVALID_THREAD_PRIORITY	The specified thread priority is not valid.
RT_ERROR_INVALID_TX_QUEUE_IDEAL_PROCESSOR	The specified transmit queue ideal processor is not valid.
RT_ERROR_INVALID_TX_QUEUE_MSIX_MESSAGE_ID	The specified transmit queue MSI message ID is not valid.

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 wRTOS Settings. To see the most accurate limits, consult the appropriate user manual for your device.

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 (‘.’). For example: 10.0.8.5
No octet has a ‘0’ digit immediately to the left of another digit. For example: 10.1.2.5, not 10.1.02.5
Every octet must be between 0 and 255 (inclusive).
The first octet is between 0 and 223.

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 refer to a network location. 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 if the existing interface is disabled. If you were to then enable the first interface, it may result in error code RT_ERROR_DUPLICATE_DEVICE_INSTANCE_ID, 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_DUPLICATE_PCI_BUS_LOCATION when the other enabled interface with the same PCIBusLocation was detected.

Requirements

Minimum supported version	Header	Library
wRTOS 1.0 SDK	Rtfwnl2Api.h	Rtfwnl2Api.lib