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

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.

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 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.

Source

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.

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

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