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 |
Properties¶
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 |
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 |
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 |
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.Carrier |
4 |
The link has a carrier. |
NetworkInterface.Degraded |
5 |
The link has carrier and addresses valid on the local link configured. |
NetworkInterface.Routable |
6 |
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.Failed |
2 |
networkd failed to manage the link. |
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.Linger |
6 |
The link is gone, but has not yet been dropped by networkd. |