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 the network name included in a refresh result.
7#[non_exhaustive]
8#[derive(Clone, Copy, Debug, PartialEq, Eq)]
9pub enum NetworkNameSource {
10    /// The latest cached name, preserved without querying Windows for a name.
11    /// Used by `NetStatusClient::refresh_reachability`.
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}
20
21/// Provenance of the IP-stack field included in a refresh result.
22#[non_exhaustive]
23#[derive(Clone, Copy, Debug, PartialEq, Eq)]
24pub enum NetworkIpStackSource {
25    /// The latest background interface observation, not this Windows query.
26    BackgroundObservation,
27}
28
29/// A completed Windows sampling window and the associated client snapshot.
30///
31/// `refresh` freshly queries reachability and network name;
32/// `refresh_reachability` queries only reachability and preserves the cached
33/// name, identified by `NetworkNameSource::CachedObservation`. The IP-stack
34/// field retains the latest background interface observation. These system calls
35/// form a sampling window, not an atomic Windows snapshot. A successful query
36/// with unchanged values preserves the snapshot's revision and observed_at.
37#[non_exhaustive]
38#[derive(Clone, Debug)]
39pub struct NetworkRefreshResult {
40    /// This client's latest snapshot after committing the sample. Each field
41    /// retains its newest observation: a full query whose name was slow may
42    /// preserve reachability from a later reachability-only query. Compare
43    /// `sampled_reachability` for this sampling window's own system result.
44    pub snapshot: NetworkSnapshot,
45    /// Reachability returned by this sampling window's own Windows query.
46    /// `snapshot.reachability` may already contain a newer observation.
47    pub sampled_reachability: super::NetworkStatus,
48    /// Increasing sampling-start identifier within this OpenNet engine. Results
49    /// may complete out of order; failed/cancelled samples may leave gaps. This
50    /// is not a snapshot or event revision.
51    pub sample_id: u64,
52    /// Wall-clock time immediately before this round's system queries.
53    pub sample_started_at: SystemTime,
54    /// Wall-clock time immediately after the queries. Clock corrections can
55    /// move wall time backwards; use sample_id for ordering.
56    pub sampled_at: SystemTime,
57    /// Source of the network name, including a successful absence or a cached
58    /// value which was not queried by this sample.
59    pub network_name_source: NetworkNameSource,
60    /// Query faults bypassed by a successful fresh NLM name fallback.
61    pub network_name_diagnostics: Vec<NetError>,
62    /// Explicitly identifies the IP-stack field as a background observation.
63    pub ip_stack_source: NetworkIpStackSource,
64}