pub struct NetStatusClient { /* private fields */ }Expand description
An independent view of the engine’s shared network monitor. Clones share this view’s lifecycle; other named views remain independent.
Implementations§
Source§impl NetStatusClient
impl NetStatusClient
Sourcepub async fn start(&self) -> Result<NetworkSnapshot>
pub async fn start(&self) -> Result<NetworkSnapshot>
Start monitoring and await the first coherent observation. Repeated calls share the active monitor and its initialization result.
Sourcepub async fn stop(&self) -> Result<()>
pub async fn stop(&self) -> Result<()>
Stop monitoring while keeping subscriptions alive for a later restart.
Sourcepub async fn shutdown(&self) -> Result<()>
pub async fn shutdown(&self) -> Result<()>
Permanently close monitoring and publish its final Closed snapshot.
Sourcepub fn snapshot(&self) -> Result<NetworkSnapshot>
pub fn snapshot(&self) -> Result<NetworkSnapshot>
Read the latest coherent snapshot, including an inactive or final state.
Sourcepub fn observe_network_names(
&self,
options: NetworkNameOptions,
) -> Result<NetworkNameObserver>
pub fn observe_network_names( &self, options: NetworkNameOptions, ) -> Result<NetworkNameObserver>
Explicitly observe Windows Wi-Fi SSID or NLM network display names.
This is the only monitoring API that enables name collection. It does not start connectivity monitoring or modify connectivity snapshots, HTTP observations, or network events. The returned observer owns its name demand and exposes a separate latest-value stream.
A stopped connectivity client can observe names. stop() affects only
connectivity; client shutdown/destroy and engine shutdown close names
too. Drop requests cancellation; await the observer’s close() to
confirm that cached/pending values and in-flight work have retired.
Already returned application-owned copies cannot be recalled.
Invalid options are rejected before lifecycle checks. Closed clients
reject admission; other platforms return Unsupported. Creation on
Windows does not wait for an OS query. recv() starts with Pending
unless the observer has already closed; snapshot() reads the latest
state, which may already contain a result. Sampling errors are delivered
on the name stream.
Sourcepub fn query_lan_ipv4(&self) -> Result<LanIpv4Snapshot>
pub fn query_lan_ipv4(&self) -> Result<LanIpv4Snapshot>
Collect a fresh LAN IPv4 inventory using crate::network::lan_ipv4_snapshot.
Synchronous OS query: it blocks this caller and needs no caller runtime. Stopped, Starting, Running and ordinary monitoring Failed states permit the query; it neither starts monitoring nor requires Internet access. It never changes the cached network snapshot, revisions or event stream. Existing network events do not guarantee notification of LAN-only changes.
A closed client (including its clones), destroyed named client, or closing engine rejects new queries with Closed. A query admitted before closing may finish normally; shutdown does not wait for this caller’s read-only query, which owns no monitored resources. Prefer a blocking worker when calling from async/UI code.
Sourcepub fn subscribe(&self) -> Result<StateReceiver<NetworkSnapshot>>
pub fn subscribe(&self) -> Result<StateReceiver<NetworkSnapshot>>
Subscribe to the current snapshot and later changes across stop/restart.
Sourcepub fn on_change<F>(&self, callback: F) -> Result<Subscription>
pub fn on_change<F>(&self, callback: F) -> Result<Subscription>
Observe the same snapshots as an asynchronous subscription on the shared callback pool. Keep the returned owner alive while observing changes.
Sourcepub fn subscribe_events(
&self,
options: NetworkEventOptions,
) -> Result<EventReceiver<NetworkEvent>>
pub fn subscribe_events( &self, options: NetworkEventOptions, ) -> Result<EventReceiver<NetworkEvent>>
Subscribe atomically to an initial baseline and ordered committed events. Each subscription has its own bounded queue. Overflow drains the queued prefix, reports a failure, and ends that subscription; subscribe again to establish a fresh baseline. Initial and lifecycle entries use capacity.
Sourcepub fn on_event<F>(
&self,
options: NetworkEventOptions,
callback: F,
) -> Result<Subscription>
pub fn on_event<F>( &self, options: NetworkEventOptions, callback: F, ) -> Result<Subscription>
Observe the same ordered events with a serial callback on the shared callback pool. Retain the returned Subscription while observing events.
Sourcepub fn on_recoverable_event<F>(
&self,
options: NetworkEventOptions,
callback: F,
) -> Result<Subscription>
pub fn on_recoverable_event<F>( &self, options: NetworkEventOptions, callback: F, ) -> Result<Subscription>
Observe ordered events and automatically reestablish an atomic baseline after a bounded queue overflows. The same logical subscription and callback context ID survive every recovery and monitor stop/restart.
The retained prefix is delivered first, then Reconciled, then events
after that baseline. Callbacks are serial across recovery. Only queue
overflow is recovered; other errors terminate the observer, and callback
panic stops delivery. Dispatch failures cannot always invoke the callback
again, but remain observable through Subscription::close and logs.
Unsubscribe cancels future callback admission and recovery. On success,
Subscription::close additionally confirms that the driver and admitted
callbacks have retired. Polling close inside a subscription callback
follows its shared context rule: it unsubscribes and returns InvalidInput
without confirming retirement; use CallbackContext::unsubscribe there.
Sourcepub async fn refresh(&self, timeout: Duration) -> Result<NetworkRefreshResult>
👎Deprecated: use refresh_reachability; network names require observe_network_names
pub async fn refresh(&self, timeout: Duration) -> Result<NetworkRefreshResult>
use refresh_reachability; network names require observe_network_names
Compatibility alias for Self::refresh_reachability.
This method no longer queries, caches, or publishes network names.
Sourcepub async fn refresh_reachability(
&self,
timeout: Duration,
) -> Result<NetworkRefreshResult>
pub async fn refresh_reachability( &self, timeout: Duration, ) -> Result<NetworkRefreshResult>
Query and commit fresh Windows reachability without querying a name.
Uses a separate bounded worker so a slow or failed network-name query
cannot block this query or background reachability monitoring. The IP
stack retains its latest background value. The compatibility name field
is always None, with NotCollected provenance and no name diagnostics.
Requires Running and a positive timeout covering admission, sampling and
commit. Dropping this future invalidates uncommitted results. A newer
committed reachability sample supersedes an older query with Cancelled.
After input and lifecycle validation, other platforms return Unsupported.
As with Self::refresh, the timeout is a result-validity budget, not a
hard real-time return deadline; success does not await observer callbacks.
Sourcepub fn refresh_blocking(
&self,
timeout: Duration,
) -> Result<NetworkRefreshResult>
👎Deprecated: use refresh_reachability_blocking; network names require observe_network_names
pub fn refresh_blocking( &self, timeout: Duration, ) -> Result<NetworkRefreshResult>
use refresh_reachability_blocking; network names require observe_network_names
Compatibility alias for Self::refresh_reachability_blocking.
This no longer queries names. It has the same
sampling, field provenance and lifecycle checks. A positive timeout is
required; after input and lifecycle validation, other platforms return
Unsupported. Errors never silently fall back to Self::snapshot.
Expired samples cannot commit, but scheduling and lock contention can
delay the return beyond the budget; it is not a hard real-time bound.
Success means the sample was committed, not that observers have finished.
Blocks the calling thread. Ordinary threads, external Tokio runtimes,
nested futures executors and the SDK’s separate subscription callback
pool are supported; the SDK drives its own timers and sampling workers.
Prefer Self::refresh_reachability in async code and avoid blocking a UI thread.
SDK management-runtime threads (including its blocking pool) and sampling
threads are rejected before any query with InvalidInput, stage
NetworkMonitor, and field network_status.refresh_blocking.context.
Entering an SDK runtime context alone does not trigger this rejection.
Sourcepub fn refresh_reachability_blocking(
&self,
timeout: Duration,
) -> Result<NetworkRefreshResult>
pub fn refresh_reachability_blocking( &self, timeout: Duration, ) -> Result<NetworkRefreshResult>
Synchronously query and commit fresh Windows reachability only.
The blocking counterpart of Self::refresh_reachability, using its
independent sampling lane. The IP-stack value remains cached; no name
is queried or returned. Requires Running
and a positive timeout; other platforms return Unsupported after these
checks. Never substitutes a cached snapshot for a failed fresh query.
The blocking, timeout and SDK-thread restrictions of
Self::refresh_blocking apply. Async callers should normally use
Self::refresh_reachability instead.
use open_net::{NetStatusClient, NetworkRefreshResult, Result};
use std::time::Duration;
// Call from a synchronous integration after start().await has succeeded.
fn query_now(client: &NetStatusClient) -> Result<NetworkRefreshResult> {
client.refresh_reachability_blocking(Duration::from_secs(3))
}