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}