Skip to main content

NetStatusClient

Struct NetStatusClient 

Source
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

Source

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.

Source

pub async fn stop(&self) -> Result<()>

Stop monitoring while keeping subscriptions alive for a later restart.

Source

pub async fn shutdown(&self) -> Result<()>

Permanently close monitoring and publish its final Closed snapshot.

Source

pub fn snapshot(&self) -> Result<NetworkSnapshot>

Read the latest coherent snapshot, including an inactive or final state.

Source

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.

Source

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.

Source

pub fn subscribe(&self) -> Result<StateReceiver<NetworkSnapshot>>

Subscribe to the current snapshot and later changes across stop/restart.

Source

pub fn on_change<F>(&self, callback: F) -> Result<Subscription>
where F: Fn(CallbackContext, Result<NetworkSnapshot>) + Send + Sync + 'static,

Observe the same snapshots as an asynchronous subscription on the shared callback pool. Keep the returned owner alive while observing changes.

Source

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.

Source

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.

Source

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.

Source

pub async fn refresh(&self, timeout: Duration) -> Result<NetworkRefreshResult>

👎Deprecated:

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.

Source

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.

Source

pub fn refresh_blocking( &self, timeout: Duration, ) -> Result<NetworkRefreshResult>

👎Deprecated:

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.

Source

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))
}

Trait Implementations§

Source§

impl Clone for NetStatusClient

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for NetStatusClient

Source§

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more