1 /*
2 * Copyright 2016-2022 The OSHI Project Contributors
3 * SPDX-License-Identifier: MIT
4 */
5 package oshi.hardware;
6
7 import java.net.NetworkInterface;
8 import java.util.Arrays;
9
10 import oshi.annotation.concurrent.ThreadSafe;
11
12 /**
13 * A network interface in the machine, including statistics.
14 * <p>
15 * Thread safe for the designed use of retrieving the most recent data. Users should be aware that the
16 * {@link #updateAttributes()} method may update attributes, including the time stamp, and should externally synchronize
17 * such usage to ensure consistent calculations.
18 */
19 @ThreadSafe
20 public interface NetworkIF {
21
22 /**
23 * Gets the {@link java.net.NetworkInterface} object.
24 *
25 * @return the network interface, an instance of {@link java.net.NetworkInterface}.
26 */
27 NetworkInterface queryNetworkInterface();
28
29 /**
30 * Interface name.
31 *
32 * @return The interface name.
33 */
34 String getName();
35
36 /**
37 * Interface index.
38 *
39 * @return The index of the network interface.
40 */
41 int getIndex();
42
43 /**
44 * Interface description.
45 *
46 * @return The description of the network interface. On some platforms, this is identical to the name.
47 */
48 String getDisplayName();
49
50 /**
51 * The {@code ifAlias} as described in RFC 2863.
52 * <p>
53 * The ifAlias object allows a network manager to give one or more interfaces their own unique names, irrespective
54 * of any interface-stack relationship. Further, the ifAlias name is non-volatile, and thus an interface must retain
55 * its assigned ifAlias value across reboots, even if an agent chooses a new ifIndex value for the interface.
56 * <p>
57 * Only implemented for Windows (Vista and newer) and Linux.
58 *
59 * @return The {@code ifAlias} of the interface if available, otherwise the empty string.
60 */
61 default String getIfAlias() {
62 return "";
63 }
64
65 /**
66 * The {@code ifOperStatus} as described in RFC 2863.
67 * <p>
68 * Only implemented for Windows (Vista and newer) and Linux.
69 *
70 * @return The current operational state of the interface.
71 */
72 default IfOperStatus getIfOperStatus() {
73 return IfOperStatus.UNKNOWN;
74 }
75
76 /**
77 * The interface Maximum Transmission Unit (MTU).
78 *
79 * @return The MTU of the network interface.
80 * <p>
81 * The value is a 32-bit integer which may be unsigned on some operating systems. On Windows, some
82 * non-physical interfaces (e.g., loopback) may return a value of -1 which is equivalent to the maximum
83 * unsigned integer value.
84 * <p>
85 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
86 */
87 long getMTU();
88
89 /**
90 * The Media Access Control (MAC) address.
91 *
92 * @return The MAC Address.
93 * <p>
94 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
95 */
96 String getMacaddr();
97
98 /**
99 * The Internet Protocol (IP) v4 address.
100 *
101 * @return An array of IPv4 Addresses.
102 * <p>
103 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
104 */
105 String[] getIPv4addr();
106
107 /**
108 * The Internet Protocol (IP) v4 subnet masks.
109 *
110 * @return An array of IPv4 subnet mask lengths, corresponding to the IPv4 addresses from {@link #getIPv4addr()}.
111 * Ranges between 0-32.
112 * <p>
113 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
114 *
115 */
116 Short[] getSubnetMasks();
117
118 /**
119 * The Internet Protocol (IP) v6 address.
120 *
121 * @return An array of IPv6 Addresses.
122 * <p>
123 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
124 */
125 String[] getIPv6addr();
126
127 /**
128 * The Internet Protocol (IP) v6 address.
129 *
130 * @return The IPv6 address prefix lengths, corresponding to the IPv6 addresses from {@link #getIPv6addr()}. Ranges
131 * between 0-128.
132 * <p>
133 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date.
134 */
135 Short[] getPrefixLengths();
136
137 /**
138 * (Windows, macOS) The NDIS Interface Type. NDIS interface types are registered with the Internet Assigned Numbers
139 * Authority (IANA), which publishes a list of interface types periodically in the Assigned Numbers RFC, or in a
140 * derivative of it that is specific to Internet network management number assignments.
141 * <p>
142 * (Linux) ARP Protocol hardware identifiers defined in {@code include/uapi/linux/if_arp.h}
143 *
144 * @return the ifType
145 */
146 default int getIfType() {
147 return 0;
148 }
149
150 /**
151 * (Windows Vista and higher only) The NDIS physical medium type. This member can be one of the values from the
152 * {@code NDIS_PHYSICAL_MEDIUM} enumeration type defined in the {@code Ntddndis.h} header file.
153 *
154 * @return the ndisPhysicalMediumType
155 */
156 default int getNdisPhysicalMediumType() {
157 return 0;
158 }
159
160 /**
161 * (Windows Vista and higher) Set if a connector is present on the network interface.
162 * <p>
163 * (Linux) Indicates the current physical link state of the interface.
164 *
165 * @return {@code true} if there is a physical network adapter (Windows) or a connected cable (Linux), false
166 * otherwise
167 */
168 default boolean isConnectorPresent() {
169 return false;
170 }
171
172 /**
173 * <p>
174 * Getter for the field <code>bytesRecv</code>.
175 * </p>
176 *
177 * @return The Bytes Received.
178 * <p>
179 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
180 * update this value, execute the {@link #updateAttributes()} method
181 */
182 long getBytesRecv();
183
184 /**
185 * <p>
186 * Getter for the field <code>bytesSent</code>.
187 * </p>
188 *
189 * @return The Bytes Sent.
190 * <p>
191 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
192 * update this value, execute the {@link #updateAttributes()} method
193 */
194 long getBytesSent();
195
196 /**
197 * <p>
198 * Getter for the field <code>packetsRecv</code>.
199 * </p>
200 *
201 * @return The Packets Received.
202 * <p>
203 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
204 * update this value, execute the {@link #updateAttributes()} method
205 */
206 long getPacketsRecv();
207
208 /**
209 * <p>
210 * Getter for the field <code>packetsSent</code>.
211 * </p>
212 *
213 * @return The Packets Sent.
214 * <p>
215 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
216 * update this value, execute the {@link #updateAttributes()} method
217 */
218 long getPacketsSent();
219
220 /**
221 * <p>
222 * Getter for the field <code>inErrors</code>.
223 * </p>
224 *
225 * @return Input Errors.
226 * <p>
227 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
228 * update this value, execute the {@link #updateAttributes()} method
229 */
230 long getInErrors();
231
232 /**
233 * <p>
234 * Getter for the field <code>outErrors</code>.
235 * </p>
236 *
237 * @return The Output Errors.
238 * <p>
239 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
240 * update this value, execute the {@link #updateAttributes()} method
241 */
242 long getOutErrors();
243
244 /**
245 * <p>
246 * Getter for the field <code>inDrops</code>.
247 * </p>
248 *
249 * @return Incoming/Received dropped packets. On Windows, returns discarded incoming packets.
250 * <p>
251 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
252 * update this value, execute the {@link #updateAttributes()} method
253 */
254 long getInDrops();
255
256 /**
257 * <p>
258 * Getter for the field <code>collisions</code>.
259 * </p>
260 *
261 * @return Packet collisions. On Windows, returns discarded outgoing packets.
262 * <p>
263 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
264 * update this value, execute the {@link #updateAttributes()} method
265 */
266 long getCollisions();
267
268 /**
269 * <p>
270 * Getter for the field <code>speed</code>.
271 * </p>
272 *
273 * @return The speed of the network interface in bits per second.
274 * <p>
275 * This value is set when the {@link oshi.hardware.NetworkIF} is instantiated and may not be up to date. To
276 * update this value, execute the {@link #updateAttributes()} method
277 */
278 long getSpeed();
279
280 /**
281 * <p>
282 * Getter for the field <code>timeStamp</code>.
283 * </p>
284 *
285 * @return Returns the timeStamp.
286 */
287 long getTimeStamp();
288
289 /**
290 * Determines if the MAC address on this interface corresponds to a known Virtual Machine.
291 *
292 * @return {@code true} if the MAC address corresponds to a known virtual machine.
293 */
294 boolean isKnownVmMacAddr();
295
296 /**
297 * Updates interface network statistics on this interface. Statistics include packets and bytes sent and received,
298 * and interface speed.
299 *
300 * @return {@code true} if the update was successful, {@code false} otherwise.
301 */
302 boolean updateAttributes();
303
304 /**
305 * The current operational state of a network interface.
306 * <p>
307 * As described in RFC 2863.
308 */
309 enum IfOperStatus {
310 /**
311 * Up and operational. Ready to pass packets.
312 */
313 UP(1),
314 /**
315 * Down and not operational. Not ready to pass packets.
316 */
317 DOWN(2),
318 /**
319 * In some test mode.
320 */
321 TESTING(3),
322 /**
323 * The interface status is unknown.
324 */
325 UNKNOWN(4),
326 /**
327 * The interface is not up, but is in a pending state, waiting for some external event.
328 */
329 DORMANT(5),
330 /**
331 * Some component is missing
332 */
333 NOT_PRESENT(6),
334 /**
335 * Down due to state of lower-layer interface(s).
336 */
337 LOWER_LAYER_DOWN(7);
338
339 private final int value;
340
341 IfOperStatus(int value) {
342 this.value = value;
343 }
344
345 /**
346 * @return the integer value specified in RFC 2863 for this operational status.
347 */
348 public int getValue() {
349 return this.value;
350 }
351
352 /**
353 * Find IfOperStatus by the integer value.
354 *
355 * @param value Integer value specified in RFC 2863
356 * @return the matching IfOperStatu or UNKNOWN if no matching IfOperStatus can be found
357 */
358 public static IfOperStatus byValue(int value) {
359 return Arrays.stream(IfOperStatus.values()).filter(st -> st.getValue() == value).findFirst()
360 .orElse(UNKNOWN);
361 }
362
363 }
364 }