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}