Skip to main content

open_net/api/net_status/
refresh.rs

1use std::time::SystemTime;
2
3use super::NetworkSnapshot;
4use crate::NetError;
5
6/// Provenance of an explicitly requested network name.
7#[non_exhaustive]
8#[derive(Clone, Copy, Debug, PartialEq, Eq)]
9pub enum NetworkNameSource {
10    /// Legacy provenance retained for source compatibility. Connectivity
11    /// refreshes no longer preserve or return cached names.
12    CachedObservation,
13    /// An active Wi-Fi SSID.
14    WifiSsid,
15    /// A connected network reported by Windows Network List Manager.
16    NetworkListManager,
17    /// The system queries completed without a connected network name.
18    None,
19    /// No name query was requested. All connectivity refreshes return this value.
20    NotCollected,
21}
22
23/// Provenance of the IP-stack field included in a refresh result.
24#[non_exhaustive]
25#[derive(Clone, Copy, Debug, PartialEq, Eq)]
26pub enum NetworkIpStackSource {
27    /// The latest background interface observation, not this Windows query.
28    BackgroundObservation,
29}
30
31/// A completed Windows sampling window and the associated client snapshot.
32///
33/// All refresh methods query only reachability. Network names require a
34/// separate explicit name observer and never enter this result. The IP-stack
35/// field retains the latest background interface observation. These system calls
36/// form a sampling window, not an atomic Windows snapshot. A successful query
37/// with unchanged values preserves the snapshot's revision and observed_at.
38#[non_exhaustive]
39#[derive(Clone, Debug)]
40pub struct NetworkRefreshResult {
41    /// This client's latest snapshot after committing the sample. Compare
42    /// `sampled_reachability` for this sampling window's own system result.
43    pub snapshot: NetworkSnapshot,
44    /// Reachability returned by this sampling window's own Windows query.
45    /// `snapshot.reachability` may already contain a newer observation.
46    pub sampled_reachability: super::NetworkStatus,
47    /// Increasing sampling-start identifier within this OpenNet engine. Results
48    /// may complete out of order; failed/cancelled samples may leave gaps. This
49    /// is not a snapshot or event revision.
50    pub sample_id: u64,
51    /// Wall-clock time immediately before this round's system queries.
52    pub sample_started_at: SystemTime,
53    /// Wall-clock time immediately after the queries. Clock corrections can
54    /// move wall time backwards; use sample_id for ordering.
55    pub sampled_at: SystemTime,
56    /// Compatibility field; always `NetworkNameSource::NotCollected`.
57    pub network_name_source: NetworkNameSource,
58    /// Compatibility field; always empty. Name failures belong to the explicit
59    /// name observation and cannot fail a connectivity refresh.
60    pub network_name_diagnostics: Vec<NetError>,
61    /// Explicitly identifies the IP-stack field as a background observation.
62    pub ip_stack_source: NetworkIpStackSource,
63}