sysinfo/common/network.rs
1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use std::collections::HashMap;
4use std::fmt;
5use std::net::{AddrParseError, IpAddr};
6use std::num::ParseIntError;
7use std::str::FromStr;
8
9use crate::{NetworkDataInner, NetworksInner};
10
11/// Interacting with network interfaces.
12///
13/// ```no_run
14/// use sysinfo::Networks;
15///
16/// let networks = Networks::new_with_refreshed_list();
17/// for (interface_name, network) in &networks {
18/// println!("[{interface_name}]: {network:?}");
19/// }
20/// ```
21pub struct Networks {
22 pub(crate) inner: NetworksInner,
23}
24
25impl<'a> IntoIterator for &'a Networks {
26 type Item = (&'a String, &'a NetworkData);
27 type IntoIter = std::collections::hash_map::Iter<'a, String, NetworkData>;
28
29 fn into_iter(self) -> Self::IntoIter {
30 self.iter()
31 }
32}
33
34impl Default for Networks {
35 fn default() -> Self {
36 Networks::new()
37 }
38}
39
40impl Networks {
41 /// Creates a new empty [`Networks`][crate::Networks] type.
42 ///
43 /// If you want it to be filled directly, take a look at [`Networks::new_with_refreshed_list`].
44 ///
45 /// ```no_run
46 /// use sysinfo::Networks;
47 ///
48 /// let mut networks = Networks::new();
49 /// networks.refresh(true);
50 /// for (interface_name, network) in &networks {
51 /// println!("[{interface_name}]: {network:?}");
52 /// }
53 /// ```
54 pub fn new() -> Self {
55 Self {
56 inner: NetworksInner::new(),
57 }
58 }
59
60 /// Creates a new [`Networks`][crate::Networks] type with the network interfaces
61 /// list loaded.
62 ///
63 /// ```no_run
64 /// use sysinfo::Networks;
65 ///
66 /// let networks = Networks::new_with_refreshed_list();
67 /// for network in &networks {
68 /// println!("{network:?}");
69 /// }
70 /// ```
71 pub fn new_with_refreshed_list() -> Self {
72 let mut networks = Self::new();
73 networks.refresh(false);
74 networks
75 }
76
77 /// Returns the network interfaces map.
78 ///
79 /// ```no_run
80 /// use sysinfo::Networks;
81 ///
82 /// let networks = Networks::new_with_refreshed_list();
83 /// for network in networks.list() {
84 /// println!("{network:?}");
85 /// }
86 /// ```
87 pub fn list(&self) -> &HashMap<String, NetworkData> {
88 self.inner.list()
89 }
90
91 /// Refreshes the network interfaces.
92 ///
93 /// ```no_run
94 /// use sysinfo::Networks;
95 ///
96 /// let mut networks = Networks::new_with_refreshed_list();
97 /// // Wait some time...? Then refresh the data of each network.
98 /// networks.refresh(true);
99 /// ```
100 pub fn refresh(&mut self, remove_not_listed_interfaces: bool) {
101 self.inner.refresh(remove_not_listed_interfaces)
102 }
103}
104
105impl std::ops::Deref for Networks {
106 type Target = HashMap<String, NetworkData>;
107
108 fn deref(&self) -> &Self::Target {
109 self.list()
110 }
111}
112
113/// Getting volume of received and transmitted data.
114///
115/// ```no_run
116/// use sysinfo::Networks;
117///
118/// let networks = Networks::new_with_refreshed_list();
119/// for (interface_name, network) in &networks {
120/// println!("[{interface_name}] {network:?}");
121/// }
122/// ```
123pub struct NetworkData {
124 pub(crate) inner: NetworkDataInner,
125}
126
127impl NetworkData {
128 /// Returns the number of received bytes since the last refresh.
129 ///
130 /// If you want the total number of bytes received, take a look at the
131 /// [`total_received`](NetworkData::total_received) method.
132 ///
133 /// ```no_run
134 /// use sysinfo::Networks;
135 /// use std::{thread, time};
136 ///
137 /// let mut networks = Networks::new_with_refreshed_list();
138 /// // Waiting a bit to get data from network...
139 /// thread::sleep(time::Duration::from_millis(10));
140 /// // Refreshing again to generate diff.
141 /// networks.refresh(true);
142 ///
143 /// for (interface_name, network) in &networks {
144 /// println!("in: {} B", network.received());
145 /// }
146 /// ```
147 pub fn received(&self) -> u64 {
148 self.inner.received()
149 }
150
151 /// Returns the total number of received bytes.
152 ///
153 /// If you want the amount of received bytes since the last refresh, take a look at the
154 /// [`received`](NetworkData::received) method.
155 ///
156 /// ```no_run
157 /// use sysinfo::Networks;
158 ///
159 /// let networks = Networks::new_with_refreshed_list();
160 /// for (interface_name, network) in &networks {
161 /// println!("in: {} B", network.total_received());
162 /// }
163 /// ```
164 pub fn total_received(&self) -> u64 {
165 self.inner.total_received()
166 }
167
168 /// Returns the number of transmitted bytes since the last refresh.
169 ///
170 /// If you want the total number of bytes transmitted, take a look at the
171 /// [`total_transmitted`](NetworkData::total_transmitted) method.
172 ///
173 /// ```no_run
174 /// use sysinfo::Networks;
175 /// use std::{thread, time};
176 ///
177 /// let mut networks = Networks::new_with_refreshed_list();
178 /// // Waiting a bit to get data from network...
179 /// thread::sleep(time::Duration::from_millis(10));
180 /// // Refreshing again to generate diff.
181 /// networks.refresh(true);
182 ///
183 /// for (interface_name, network) in &networks {
184 /// println!("out: {} B", network.transmitted());
185 /// }
186 /// ```
187 pub fn transmitted(&self) -> u64 {
188 self.inner.transmitted()
189 }
190
191 /// Returns the total number of transmitted bytes.
192 ///
193 /// If you want the amount of transmitted bytes since the last refresh, take a look at the
194 /// [`transmitted`](NetworkData::transmitted) method.
195 ///
196 /// ```no_run
197 /// use sysinfo::Networks;
198 ///
199 /// let networks = Networks::new_with_refreshed_list();
200 /// for (interface_name, network) in &networks {
201 /// println!("out: {} B", network.total_transmitted());
202 /// }
203 /// ```
204 pub fn total_transmitted(&self) -> u64 {
205 self.inner.total_transmitted()
206 }
207
208 /// Returns the number of incoming packets since the last refresh.
209 ///
210 /// If you want the total number of packets received, take a look at the
211 /// [`total_packets_received`](NetworkData::total_packets_received) method.
212 ///
213 /// ```no_run
214 /// use sysinfo::Networks;
215 /// use std::{thread, time};
216 ///
217 /// let mut networks = Networks::new_with_refreshed_list();
218 /// // Waiting a bit to get data from network...
219 /// thread::sleep(time::Duration::from_millis(10));
220 /// // Refreshing again to generate diff.
221 /// networks.refresh(true);
222 ///
223 /// for (interface_name, network) in &networks {
224 /// println!("in: {}", network.packets_received());
225 /// }
226 /// ```
227 pub fn packets_received(&self) -> u64 {
228 self.inner.packets_received()
229 }
230
231 /// Returns the total number of incoming packets.
232 ///
233 /// If you want the amount of received packets since the last refresh, take a look at the
234 /// [`packets_received`](NetworkData::packets_received) method.
235 ///
236 /// ```no_run
237 /// use sysinfo::Networks;
238 ///
239 /// let networks = Networks::new_with_refreshed_list();
240 /// for (interface_name, network) in &networks {
241 /// println!("in: {}", network.total_packets_received());
242 /// }
243 /// ```
244 pub fn total_packets_received(&self) -> u64 {
245 self.inner.total_packets_received()
246 }
247
248 /// Returns the number of outcoming packets since the last refresh.
249 ///
250 /// If you want the total number of packets transmitted, take a look at the
251 /// [`total_packets_transmitted`](NetworkData::total_packets_transmitted) method.
252 ///
253 /// ```no_run
254 /// use sysinfo::Networks;
255 /// use std::{thread, time};
256 ///
257 /// let mut networks = Networks::new_with_refreshed_list();
258 /// // Waiting a bit to get data from network...
259 /// thread::sleep(time::Duration::from_millis(10));
260 /// // Refreshing again to generate diff.
261 /// networks.refresh(true);
262 ///
263 /// for (interface_name, network) in &networks {
264 /// println!("out: {}", network.packets_transmitted());
265 /// }
266 /// ```
267 pub fn packets_transmitted(&self) -> u64 {
268 self.inner.packets_transmitted()
269 }
270
271 /// Returns the total number of outcoming packets.
272 ///
273 /// If you want the amount of transmitted packets since the last refresh, take a look at the
274 /// [`packets_transmitted`](NetworkData::packets_transmitted) method.
275 ///
276 /// ```no_run
277 /// use sysinfo::Networks;
278 ///
279 /// let networks = Networks::new_with_refreshed_list();
280 /// for (interface_name, network) in &networks {
281 /// println!("out: {}", network.total_packets_transmitted());
282 /// }
283 /// ```
284 pub fn total_packets_transmitted(&self) -> u64 {
285 self.inner.total_packets_transmitted()
286 }
287
288 /// Returns the number of incoming errors since the last refresh.
289 ///
290 /// If you want the total number of errors on received packets, take a look at the
291 /// [`total_errors_on_received`](NetworkData::total_errors_on_received) method.
292 ///
293 /// ```no_run
294 /// use sysinfo::Networks;
295 /// use std::{thread, time};
296 ///
297 /// let mut networks = Networks::new_with_refreshed_list();
298 /// // Waiting a bit to get data from network...
299 /// thread::sleep(time::Duration::from_millis(10));
300 /// // Refreshing again to generate diff.
301 /// networks.refresh(true);
302 ///
303 /// for (interface_name, network) in &networks {
304 /// println!("in: {}", network.errors_on_received());
305 /// }
306 /// ```
307 pub fn errors_on_received(&self) -> u64 {
308 self.inner.errors_on_received()
309 }
310
311 /// Returns the total number of incoming errors.
312 ///
313 /// If you want the amount of errors on received packets since the last refresh, take a look at
314 /// the [`errors_on_received`](NetworkData::errors_on_received) method.
315 ///
316 /// ```no_run
317 /// use sysinfo::Networks;
318 ///
319 /// let networks = Networks::new_with_refreshed_list();
320 /// for (interface_name, network) in &networks {
321 /// println!("in: {}", network.total_errors_on_received());
322 /// }
323 /// ```
324 pub fn total_errors_on_received(&self) -> u64 {
325 self.inner.total_errors_on_received()
326 }
327
328 /// Returns the number of outcoming errors since the last refresh.
329 ///
330 /// If you want the total number of errors on transmitted packets, take a look at the
331 /// [`total_errors_on_transmitted`](NetworkData::total_errors_on_transmitted) method.
332 ///
333 /// ```no_run
334 /// use sysinfo::Networks;
335 /// use std::{thread, time};
336 ///
337 /// let mut networks = Networks::new_with_refreshed_list();
338 /// // Waiting a bit to get data from network...
339 /// thread::sleep(time::Duration::from_millis(10));
340 /// // Refreshing again to generate diff.
341 /// networks.refresh(true);
342 ///
343 /// for (interface_name, network) in &networks {
344 /// println!("out: {}", network.errors_on_transmitted());
345 /// }
346 /// ```
347 pub fn errors_on_transmitted(&self) -> u64 {
348 self.inner.errors_on_transmitted()
349 }
350
351 /// Returns the total number of outcoming errors.
352 ///
353 /// If you want the amount of errors on transmitted packets since the last refresh, take a look at
354 /// the [`errors_on_transmitted`](NetworkData::errors_on_transmitted) method.
355 ///
356 /// ```no_run
357 /// use sysinfo::Networks;
358 ///
359 /// let networks = Networks::new_with_refreshed_list();
360 /// for (interface_name, network) in &networks {
361 /// println!("out: {}", network.total_errors_on_transmitted());
362 /// }
363 /// ```
364 pub fn total_errors_on_transmitted(&self) -> u64 {
365 self.inner.total_errors_on_transmitted()
366 }
367
368 /// Returns the MAC address associated to current interface.
369 ///
370 /// ```no_run
371 /// use sysinfo::Networks;
372 ///
373 /// let mut networks = Networks::new_with_refreshed_list();
374 /// for (interface_name, network) in &networks {
375 /// println!("MAC address: {}", network.mac_address());
376 /// }
377 /// ```
378 pub fn mac_address(&self) -> MacAddr {
379 self.inner.mac_address()
380 }
381
382 /// Returns the Ip Networks associated to current interface.
383 ///
384 /// ```no_run
385 /// use sysinfo::Networks;
386 ///
387 /// let mut networks = Networks::new_with_refreshed_list();
388 /// for (interface_name, network) in &networks {
389 /// println!("Ip Networks: {:?}", network.ip_networks());
390 /// }
391 /// ```
392 pub fn ip_networks(&self) -> &[IpNetwork] {
393 self.inner.ip_networks()
394 }
395
396 /// Returns the Maximum Transfer Unit (MTU) of the interface.
397 ///
398 /// ```no_run
399 /// use sysinfo::Networks;
400 ///
401 /// let mut networks = Networks::new_with_refreshed_list();
402 /// for (interface_name, network) in &networks {
403 /// println!("mtu: {}", network.mtu());
404 /// }
405 /// ```
406 pub fn mtu(&self) -> u64 {
407 self.inner.mtu()
408 }
409}
410
411/// MAC address for network interface.
412///
413/// It is returned by [`NetworkData::mac_address`][crate::NetworkData::mac_address].
414#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
415#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
416pub struct MacAddr(pub [u8; 6]);
417
418impl MacAddr {
419 /// A `MacAddr` with all bytes set to `0`.
420 pub const UNSPECIFIED: Self = MacAddr([0; 6]);
421
422 /// Checks if this `MacAddr` has all bytes equal to `0`.
423 pub fn is_unspecified(&self) -> bool {
424 self == &MacAddr::UNSPECIFIED
425 }
426}
427
428impl fmt::Display for MacAddr {
429 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
430 let data = &self.0;
431 write!(
432 f,
433 "{:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x}",
434 data[0], data[1], data[2], data[3], data[4], data[5],
435 )
436 }
437}
438
439/// Error type returned from `MacAddr::from_str` implementation.
440#[derive(Debug, Clone, PartialEq, Eq)]
441pub enum MacAddrFromStrError {
442 /// A number is not in hexadecimal format.
443 IntError(ParseIntError),
444 /// Input is not of format `{02X}:{02X}:{02X}:{02X}:{02X}:{02X}`.
445 InvalidAddrFormat,
446}
447
448impl FromStr for MacAddr {
449 type Err = MacAddrFromStrError;
450
451 fn from_str(s: &str) -> Result<Self, Self::Err> {
452 let mut parts = s
453 .split(':')
454 .map(|s| u8::from_str_radix(s, 16).map_err(MacAddrFromStrError::IntError));
455
456 let Some(data0) = parts.next() else {
457 return Err(MacAddrFromStrError::InvalidAddrFormat);
458 };
459 let Some(data1) = parts.next() else {
460 return Err(MacAddrFromStrError::InvalidAddrFormat);
461 };
462 let Some(data2) = parts.next() else {
463 return Err(MacAddrFromStrError::InvalidAddrFormat);
464 };
465 let Some(data3) = parts.next() else {
466 return Err(MacAddrFromStrError::InvalidAddrFormat);
467 };
468 let Some(data4) = parts.next() else {
469 return Err(MacAddrFromStrError::InvalidAddrFormat);
470 };
471 let Some(data5) = parts.next() else {
472 return Err(MacAddrFromStrError::InvalidAddrFormat);
473 };
474
475 if parts.next().is_some() {
476 return Err(MacAddrFromStrError::InvalidAddrFormat);
477 }
478
479 Ok(MacAddr([data0?, data1?, data2?, data3?, data4?, data5?]))
480 }
481}
482
483/// IP networks address for network interface.
484///
485/// It is returned by [`NetworkData::ip_networks`][crate::NetworkData::ip_networks].
486#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
487#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
488pub struct IpNetwork {
489 /// The IP of the network interface.
490 pub addr: IpAddr,
491 /// The netmask, prefix of the IP address.
492 pub prefix: u8,
493}
494
495impl fmt::Display for IpNetwork {
496 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
497 write!(f, "{}/{}", self.addr, self.prefix)
498 }
499}
500
501/// Error type returned from `MacAddr::from_str` implementation.
502#[derive(Debug, Clone, PartialEq, Eq)]
503pub enum IpNetworkFromStrError {
504 /// Prefix is not an integer.
505 PrefixError(ParseIntError),
506 /// Failed to parse IP address.
507 AddrParseError(AddrParseError),
508 /// Input is not of format `[IP address]/[number]`.
509 InvalidAddrFormat,
510}
511
512impl FromStr for IpNetwork {
513 type Err = IpNetworkFromStrError;
514
515 #[allow(clippy::from_str_radix_10)]
516 fn from_str(s: &str) -> Result<Self, Self::Err> {
517 let mut parts = s.split('/');
518
519 let Some(addr) = parts.next() else {
520 return Err(IpNetworkFromStrError::InvalidAddrFormat);
521 };
522 let Some(prefix) = parts.next() else {
523 return Err(IpNetworkFromStrError::InvalidAddrFormat);
524 };
525 if parts.next().is_some() {
526 return Err(IpNetworkFromStrError::InvalidAddrFormat);
527 }
528
529 Ok(IpNetwork {
530 addr: IpAddr::from_str(addr).map_err(IpNetworkFromStrError::AddrParseError)?,
531 prefix: u8::from_str_radix(prefix, 10).map_err(IpNetworkFromStrError::PrefixError)?,
532 })
533 }
534}
535
536#[cfg(test)]
537mod tests {
538 use crate::*;
539 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
540 use std::str::FromStr;
541
542 // Ensure that the `Display` and `Debug` traits are implemented on the `MacAddr` struct
543 #[test]
544 fn check_display_impl_mac_address() {
545 println!(
546 "{} {:?}",
547 MacAddr([0x1, 0x2, 0x3, 0x4, 0x5, 0x6]),
548 MacAddr([0xa, 0xb, 0xc, 0xd, 0xe, 0xf])
549 );
550 }
551
552 #[test]
553 fn check_mac_address_is_unspecified_true() {
554 assert!(MacAddr::UNSPECIFIED.is_unspecified());
555 assert!(MacAddr([0; 6]).is_unspecified());
556 }
557
558 #[test]
559 fn check_mac_address_is_unspecified_false() {
560 assert!(!MacAddr([1, 2, 3, 4, 5, 6]).is_unspecified());
561 }
562
563 #[test]
564 fn check_mac_address_conversions() {
565 let mac = MacAddr([0xa, 0xb, 0xc, 0xd, 0xe, 0xf]);
566
567 let mac_s = mac.to_string();
568 assert_eq!("0a:0b:0c:0d:0e:0f", mac_s);
569 assert_eq!(Ok(mac), MacAddr::from_str(&mac_s));
570
571 assert_eq!(
572 MacAddr::from_str("0a:0b:0c:0d:0e:0f:01"),
573 Err(MacAddrFromStrError::InvalidAddrFormat)
574 );
575 assert_eq!(
576 MacAddr::from_str("0a:0b:0c:0d:0e"),
577 Err(MacAddrFromStrError::InvalidAddrFormat)
578 );
579 }
580
581 // Ensure that the `Display` and `Debug` traits are implemented on the `IpNetwork` struct
582 #[test]
583 fn check_display_impl_ip_network_ipv4() {
584 println!(
585 "{} {:?}",
586 IpNetwork {
587 addr: IpAddr::from(Ipv4Addr::new(1, 2, 3, 4)),
588 prefix: 3
589 },
590 IpNetwork {
591 addr: IpAddr::from(Ipv4Addr::new(255, 255, 255, 0)),
592 prefix: 21
593 }
594 );
595 }
596
597 #[test]
598 fn check_display_impl_ip_network_ipv6() {
599 println!(
600 "{} {:?}",
601 IpNetwork {
602 addr: IpAddr::from(Ipv6Addr::new(0xffff, 0xaabb, 00, 0, 0, 0x000c, 11, 21)),
603 prefix: 127
604 },
605 IpNetwork {
606 addr: IpAddr::from(Ipv6Addr::new(0xffcc, 0, 0, 0xffcc, 0, 0xffff, 0, 0xccaa)),
607 prefix: 120
608 }
609 )
610 }
611
612 #[test]
613 fn check_ip_networks() {
614 if !IS_SUPPORTED_SYSTEM {
615 return;
616 }
617 let networks = Networks::new_with_refreshed_list();
618 if networks.iter().any(|(_, n)| !n.ip_networks().is_empty()) {
619 return;
620 }
621 panic!("Networks should have at least one IP network ");
622 }
623
624 #[test]
625 fn check_ip_network_conversions() {
626 let addr = IpNetwork {
627 addr: IpAddr::from(Ipv6Addr::new(0xff, 0xa, 0x8, 0x12, 0x7, 0xc, 0xa, 0xb)),
628 prefix: 12,
629 };
630
631 let addr_s = addr.to_string();
632 assert_eq!("ff:a:8:12:7:c:a:b/12", addr_s);
633 assert_eq!(Ok(addr), IpNetwork::from_str(&addr_s));
634
635 let addr = IpNetwork {
636 addr: IpAddr::from(Ipv4Addr::new(255, 255, 255, 0)),
637 prefix: 21,
638 };
639
640 let addr_s = addr.to_string();
641 assert_eq!("255.255.255.0/21", addr_s);
642 assert_eq!(Ok(addr), IpNetwork::from_str(&addr_s));
643
644 assert_eq!(
645 IpNetwork::from_str("ff:a:8:12:7:c:a:b"),
646 Err(IpNetworkFromStrError::InvalidAddrFormat)
647 );
648 assert_eq!(
649 IpNetwork::from_str("ff:a:8:12:7:c:a:b/12/12"),
650 Err(IpNetworkFromStrError::InvalidAddrFormat)
651 );
652 match IpNetwork::from_str("0a:0b:0c:0d:0e/12") {
653 Err(IpNetworkFromStrError::AddrParseError(_)) => {}
654 x => panic!("expected `IpNetworkFromStrError::AddrParseError`, found {x:?}"),
655 }
656 }
657}