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 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>
pub async fn refresh(&self, timeout: Duration) -> Result<NetworkRefreshResult>
Query fresh Windows reachability and network name and commit the result. Requires this view to be Running. The positive timeout covers admission, sampling and commit. Dropping the future invalidates uncommitted results. A slow name query preserves any later reachability observation while committing its fresh name; a newer name sample supersedes it with Cancelled. After input and lifecycle validation, other platforms return Unsupported; snapshot() remains a cheap cache read. Expired results cannot commit, but scheduling and lock contention can delay return beyond the timeout. Success does not wait for subscription callbacks to finish.
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 name
and IP stack retain their latest cached values with explicit provenance.
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>
pub fn refresh_blocking( &self, timeout: Duration, ) -> Result<NetworkRefreshResult>
Synchronously query and commit fresh Windows reachability and network name.
This is the blocking counterpart of Self::refresh, with 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 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. Network name and IP-stack values remain
cached, with their provenance preserved in the result. 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))
}