NetworkInterface

Description

The NetworkInterface object is an abstract base object for all kind of specific network interface objects such as WiredNetworkInterface, WirelessNetworkInterface and MobileNetworkInterface. It provides common properties and enumerations which apply to all network interfaces and implements common configuration mechanisms.

› Inherits:

ConfigurationObject

› Inherited by:

MobileNetworkInterface, WiredNetworkInterface, WirelessNetworkInterface

Overview

Properties

bytesRx bytesTx dhcpClientIdentifier enabled enabledItem error errorString hardwareAddress hardwareAddressItem

hardwareName networkAddresses ntp ntpItem operationalState routes setupState trafficRx

trafficTx useRoutes useRoutesItem ConfigurationObject.items ConfigurationObject.name ConfigurationObject.nameItem Object.objectId Object.parent

Methods

pollBytesRx() pollBytesTx() pollTrafficRx() pollTrafficTx() ConfigurationObject.toDataMap()

Object.deserializeProperties() Object.fromJson() Object.serializeProperties() Object.toJson()

Signals

errorOccurred() routesDataChanged() ConfigurationObject.aboutToBeUpdated() ConfigurationObject.itemsDataChanged() ConfigurationObject.updated() Object.completed()

Enumerations

DhcpClientIdentifier Error OperationalState SetupState

Properties

bytesRx

This property holds the number of bytes received through this interface since the device has been started.

This property was introduced in InCore 2.6.

› Type:

UnsignedBigInteger

› Signal:

bytesRxChanged()

› Attributes:

Readonly, Requires Polling

bytesTx

This property holds the number of bytes transmitted through this interface since the device has been started.

This property was introduced in InCore 2.6.

› Type:

UnsignedBigInteger

› Signal:

bytesTxChanged()

› Attributes:

Readonly, Requires Polling

dhcpClientIdentifier

This property holds the DHCPv4 client identifier to use when sending DHCP requests. For all options the MAC address of the corresponding network interface is used to generate a unique identifier. When set to NetworkInterface.MacIdentifier the MAC address is used directly. Otherwise an RFC4361-compliant client ID is generated based on the MAC address.

› Type:

DhcpClientIdentifier

› Default:

NetworkInterface.MacIdentifier

› Signal:

dhcpClientIdentifierChanged()

› Attributes:

Writable, Optional

enabled

This property holds whether the network interface is enabled at all. If enabled the interface is managed and configured by the system according to the settings represented by other properties in this object and derived objects.

› Type:

Boolean

› Default:

false

› Signal:

enabledChanged()

› Attributes:

Writable

enabledItem

This property holds an internal ConfigurationItem instance for the enabled property.

› Type:

ConfigurationItem

› Attributes:

Readonly

error

This property holds the most recently occurred error or NetworkInterface.NoError if no error occurred. If the same error occurs multiple times this property does not change. Use the errorOccurred() signal to detect multiple occurrences of the same error.

› Type:

Error

› Signal:

errorChanged()

› Attributes:

Readonly

errorString

This property holds the current human readable error string corresponding to the current value in the error property. It may include additional information such as failure reasons or locations.

› Type:

String

› Signal:

errorStringChanged()

› Attributes:

Readonly

hardwareAddress

This property holds the hardware address of the network interface, usually the MAC address.

› Type:

String

› Signal:

hardwareAddressChanged()

› Attributes:

Readonly

hardwareAddressItem

This property holds an internal ConfigurationItem instance for the hardwareAddress property.

› Type:

ConfigurationItem

› Attributes:

Readonly

hardwareName

This property holds the unique hardware name of the network interface as seen by the operating system, e.g. eth0.

› Type:

String

› Attributes:

Readonly

networkAddresses

This property holds the actual IP addresses in effect which have been assigned by the network or configured by the user.

This property was introduced in InCore 1.1.

› Type:

StringList

› Signal:

networkAddressesChanged()

› Attributes:

Readonly

ntp

This property holds a list of NTP servers which should be used for synchronizing the system clock of the device. Multiple server addresses can be specified (IPv4/IPv6 addresses and resolvable hostnames allowed) and separated by space.

› Type:

String

› Signal:

ntpChanged()

› Attributes:

Writable

ntpItem

This property holds an internal ConfigurationItem instance for the ntp property.

› Type:

ConfigurationItem

› Attributes:

Readonly

operationalState

This property holds the operational state of the network interface. The most common case is to check whether the operational state equals NetworkInterface.Routable in order to determine whether the device is ready to communicate with certain hosts or networks. See the NetworkInterface.OperationalState enumeration for more details.

› Type:

OperationalState

› Default:

NetworkInterface.NoOperation

› Signal:

operationalStateChanged()

› Attributes:

Readonly

routes

This property holds a list of NetworkRoute objects which hold additional network routes to configure.

This property was introduced in InCore 2.3.

› Type:

List<NetworkRoute>

› Signal:

routesChanged()

› Attributes:

Readonly

setupState

This property holds the setup state of the network interface which specifies the state and progress of the interface configuration. The most common case is to check whether the setup state equals NetworkInterface.Configured which indicates that the network interface has been configured successfully. See the NetworkInterface.SetupState enumeration for more details.

› Type:

SetupState

› Default:

NetworkInterface.NoSetup

› Signal:

setupStateChanged()

› Attributes:

Readonly

trafficRx

This property holds the number of bytes received per second through this interface during the last polling interval.

This property was introduced in InCore 2.5.

› Type:

SignedInteger

› Signal:

trafficRxChanged()

› Attributes:

Readonly, Requires Polling

trafficTx

This property holds the number of bytes transmitted per second through this interface during the last polling interval.

This property was introduced in InCore 2.5.

› Type:

SignedInteger

› Signal:

trafficTxChanged()

› Attributes:

Readonly, Requires Polling

useRoutes

This property holds whether to add the routes received during the configuration process to the routing table (e.g. routes advertisted by DHCP servers). This can be important when using multiple network interfaces which would normally lead to multiple default routes being added to the routing table. If in this case not all network gateways have access to the internet, the internet connectivity of the device itself can be impacted as well and may not work reliable and deterministic. By setting this property to false except for one specific interface the device will access the internet and non-local networks through the specific interface.

› Type:

Boolean

› Default:

true

› Signal:

useRoutesChanged()

› Attributes:

Writable

useRoutesItem

This property holds an internal ConfigurationItem instance for the useRoutes property.

› Type:

ConfigurationItem

› Attributes:

Readonly

Methods

pollBytesRx()

This method polls the bytesRx property. It is called automatically when using a Polling property modifier on this property and usually does not have to be called manually.

pollBytesTx()

This method polls the bytesTx property. It is called automatically when using a Polling property modifier on this property and usually does not have to be called manually.

pollTrafficRx()

This method polls the trafficRx property. It is called automatically when using a Polling property modifier on this property and usually does not have to be called manually.

pollTrafficTx()

This method polls the trafficTx property. It is called automatically when using a Polling property modifier on this property and usually does not have to be called manually.

Signals

errorOccurred()

This signal is emitted whenever an error has occurred, regardless of whether the error property has changed or not. In contrast to the change notification signal of the error property this signal is also emitted several times if a certain error occurs several times in succession.

routesDataChanged(SignedInteger index)

This signal is emitted whenever the List.dataChanged() signal is emitted, i.e. the item at index in the routes list itself emitted the dataChanged() signal.

Enumerations

DhcpClientIdentifier

This enumeration describes the DHCPv4 client identifier to use when sending DHCP requests.

Name	Value	Description
NetworkInterface.MacIdentifier	0	Use the MAC address of the interface as DHCP client identifier.
NetworkInterface.DhcpUniqueIdentifier	1	Use an RFC4361-compliant client ID (based on the MAC address) as DUID.

Error

This enumeration describes all errors which can occur in NetworkInterface objects. The most recently occurred error is stored in the error property.

Name	Value	Description
NetworkInterface.NoError	0	No error occurred or was detected.
NetworkInterface.InvalidIndex	1	Invalid interface index.
NetworkInterface.InvalidConfigurationError	2	Invalid or empty configuration.
NetworkInterface.ConfigurationUpdateError	3	Can’t update configuration - likely configuration files could not be opened for writing.
NetworkInterface.ConfigurationApplyError	4	Can’t apply configuration likely due to system service errors.
NetworkInterface.SystemError	5	System error.
NetworkInterface.DeviceUnlockError	6	Device could not be unlocked, e.g. due to missing or invalid PIN.
NetworkInterface.InvalidCountryCode	7	Specified country code is invalid or could not be set.
NetworkInterface.OperationNotSupportedError	8	The requested operation is not supported by the the interface.
NetworkInterface.DeviceNotReadyError	9	The device for the network interface is not available or not ready yet.
NetworkInterface.InvalidAddressError	10	The address (e.g. SMS recipient number) is empty.
NetworkInterface.EmptyMessageError	11	The message (e.g. SMS text) is empty.
NetworkInterface.MessageCreateError	12	The message could not be created for sending.
NetworkInterface.MessageSendError	13	The message could not be sent, likely due to a network error or an invalid address.
NetworkInterface.MessageDeleteError	14	The message could not be deleted.

OperationalState

This enumeration describes all operational states a network interface can enter.

Name	Value	Description
NetworkInterface.NoOperation	0	The device is not operated at all.
NetworkInterface.Off	1	The device is powered down.
NetworkInterface.NoCarrier	2	The device is powered up, but it does not yet have a carrier.
NetworkInterface.Dormant	3	The device has a carrier, but is not yet ready for normal traffic.
NetworkInterface.DegradedCarrier	4	The link has carrier and addresses valid on the local link configured.
NetworkInterface.Carrier	5	The link has a carrier.
NetworkInterface.Degraded	6	The link has carrier and addresses valid on the local link configured.
NetworkInterface.Enslaved	7	The link has carrier and is enslaved to bond or bridge master network interface.
NetworkInterface.Routable	8	The link has carrier and routable address configured.

SetupState

This enumeration describes all setup states a network interface can enter.

Name	Value	Description
NetworkInterface.NoSetup	0	The link is not set up.
NetworkInterface.Pending	1	udev is still processing the link, we don’t yet know if we will manage it.
NetworkInterface.Initialized	2	udev has processed the link, but we don’t yet know if we will manage it.
NetworkInterface.Configuring	3	System is in the process of retrieving configuration or configuring the link.
NetworkInterface.Configured	4	The link has been configured successfully.
NetworkInterface.Unmanaged	5	The link is not managed by networkd.
NetworkInterface.Failed	6	networkd failed to manage the link.
NetworkInterface.Linger	7	The link is gone, but has not yet been dropped by networkd.