oshi.hardware.NetworkIF Maven / Gradle / Ivy
/*
* Copyright 2016-2022 The OSHI Project Contributors
* SPDX-License-Identifier: MIT
*/
package oshi.hardware;
import java.net.NetworkInterface;
import java.util.Arrays;
import oshi.annotation.concurrent.ThreadSafe;
/**
* A network interface in the machine, including statistics.
*
* Thread safe for the designed use of retrieving the most recent data. Users should be aware that the
* {@link #updateAttributes()} method may update attributes, including the time stamp, and should externally synchronize
* such usage to ensure consistent calculations.
*/
@ThreadSafe
public interface NetworkIF {
/**
* Gets the {@link java.net.NetworkInterface} object.
*
* @return the network interface, an instance of {@link java.net.NetworkInterface}.
*/
NetworkInterface queryNetworkInterface();
/**
* Interface name.
*
* @return The interface name.
*/
String getName();
/**
* Interface index.
*
* @return The index of the network interface.
*/
int getIndex();
/**
* Interface description.
*
* @return The description of the network interface. On some platforms, this is identical to the name.
*/
String getDisplayName();
/**
* The {@code ifAlias} as described in RFC 2863.
*
* The ifAlias object allows a network manager to give one or more interfaces their own unique names, irrespective
* of any interface-stack relationship. Further, the ifAlias name is non-volatile, and thus an interface must retain
* its assigned ifAlias value across reboots, even if an agent chooses a new ifIndex value for the interface.
*
* Only implemented for Windows (Vista and newer) and Linux.
*
* @return The {@code ifAlias} of the interface if available, otherwise the empty string.
*/
default String getIfAlias() {
return "";
}
/**
* The {@code ifOperStatus} as described in RFC 2863.
*
* Only implemented for Windows (Vista and newer) and Linux.
*
* @return The current operational state of the interface.
*/
default IfOperStatus getIfOperStatus() {
return IfOperStatus.UNKNOWN;
}
/**
* The interface Maximum Transmission Unit (MTU).
*
* @return The MTU of the network interface.
*
* The value is a 32-bit integer which may be unsigned on some operating systems. On Windows, some
* non-physical interfaces (e.g., loopback) may return a value of -1 which is equivalent to the maximum
* unsigned integer value.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
*/
long getMTU();
/**
* The Media Access Control (MAC) address.
*
* @return The MAC Address.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
*/
String getMacaddr();
/**
* The Internet Protocol (IP) v4 address.
*
* @return An array of IPv4 Addresses.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
*/
String[] getIPv4addr();
/**
* The Internet Protocol (IP) v4 subnet masks.
*
* @return An array of IPv4 subnet mask lengths, corresponding to the IPv4 addresses from {@link #getIPv4addr()}.
* Ranges between 0-32.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
*
*/
Short[] getSubnetMasks();
/**
* The Internet Protocol (IP) v6 address.
*
* @return An array of IPv6 Addresses.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
*/
String[] getIPv6addr();
/**
* The Internet Protocol (IP) v6 address.
*
* @return The IPv6 address prefix lengths, corresponding to the IPv6 addresses from {@link #getIPv6addr()}. Ranges
* between 0-128.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
*/
Short[] getPrefixLengths();
/**
* (Windows, macOS) The NDIS Interface Type. NDIS interface types are registered with the Internet Assigned Numbers
* Authority (IANA), which publishes a list of interface types periodically in the Assigned Numbers RFC, or in a
* derivative of it that is specific to Internet network management number assignments.
*
* (Linux) ARP Protocol hardware identifiers defined in {@code include/uapi/linux/if_arp.h}
*
* @return the ifType
*/
default int getIfType() {
return 0;
}
/**
* (Windows Vista and higher only) The NDIS physical medium type. This member can be one of the values from the
* {@code NDIS_PHYSICAL_MEDIUM} enumeration type defined in the {@code Ntddndis.h} header file.
*
* @return the ndisPhysicalMediumType
*/
default int getNdisPhysicalMediumType() {
return 0;
}
/**
* (Windows Vista and higher) Set if a connector is present on the network interface.
*
* (Linux) Indicates the current physical link state of the interface.
*
* @return {@code true} if there is a physical network adapter (Windows) or a connected cable (Linux), false
* otherwise
*/
default boolean isConnectorPresent() {
return false;
}
/**
*
* Getter for the field bytesRecv.
*
*
* @return The Bytes Received.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getBytesRecv();
/**
*
* Getter for the field bytesSent.
*
*
* @return The Bytes Sent.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getBytesSent();
/**
*
* Getter for the field packetsRecv.
*
*
* @return The Packets Received.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getPacketsRecv();
/**
*
* Getter for the field packetsSent.
*
*
* @return The Packets Sent.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getPacketsSent();
/**
*
* Getter for the field inErrors.
*
*
* @return Input Errors.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getInErrors();
/**
*
* Getter for the field outErrors.
*
*
* @return The Output Errors.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getOutErrors();
/**
*
* Getter for the field inDrops.
*
*
* @return Incoming/Received dropped packets. On Windows, returns discarded incoming packets.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getInDrops();
/**
*
* Getter for the field collisions.
*
*
* @return Packet collisions. On Windows, returns discarded outgoing packets.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getCollisions();
/**
*
* Getter for the field speed.
*
*
* @return The speed of the network interface in bits per second.
*
* This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
* update this value, execute the {@link #updateAttributes()} method
*/
long getSpeed();
/**
*
* Getter for the field timeStamp.
*
*
* @return Returns the timeStamp.
*/
long getTimeStamp();
/**
* Determines if the MAC address on this interface corresponds to a known Virtual Machine.
*
* @return {@code true} if the MAC address corresponds to a known virtual machine.
*/
boolean isKnownVmMacAddr();
/**
* Updates interface network statistics on this interface. Statistics include packets and bytes sent and received,
* and interface speed.
*
* @return {@code true} if the update was successful, {@code false} otherwise.
*/
boolean updateAttributes();
/**
* The current operational state of a network interface.
*
* As described in RFC 2863.
*/
enum IfOperStatus {
/**
* Up and operational. Ready to pass packets.
*/
UP(1),
/**
* Down and not operational. Not ready to pass packets.
*/
DOWN(2),
/**
* In some test mode.
*/
TESTING(3),
/**
* The interface status is unknown.
*/
UNKNOWN(4),
/**
* The interface is not up, but is in a pending state, waiting for some external event.
*/
DORMANT(5),
/**
* Some component is missing
*/
NOT_PRESENT(6),
/**
* Down due to state of lower-layer interface(s).
*/
LOWER_LAYER_DOWN(7);
private final int value;
IfOperStatus(int value) {
this.value = value;
}
/**
* @return the integer value specified in RFC 2863 for this operational status.
*/
public int getValue() {
return this.value;
}
/**
* Find IfOperStatus by the integer value.
*
* @param value Integer value specified in RFC 2863
* @return the matching IfOperStatu or UNKNOWN if no matching IfOperStatus can be found
*/
public static IfOperStatus byValue(int value) {
return Arrays.stream(IfOperStatus.values()).filter(st -> st.getValue() == value).findFirst()
.orElse(UNKNOWN);
}
}
}