// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=8)
library fuchsia.net.reachability;

/// Provides snapshots of reachability state.
@discoverable
protocol Monitor {
    /// Controls verbosity of results returned from calls to [`Watch`]. If
    /// options are set via this method, it must be in the first call made
    /// over the channel.
    ///
    /// Calling this method after either it or [`Watch`] have already been
    /// invoked will result in closing the channel. If this method is not
    /// called before calling [`Watch`], [`Snapshot`] responses will not be
    /// modified.
    //
    // This table is currently empty, but is expected to provide the ability
    // to filter more detailed configuration and service state.
    SetOptions(@generated_name("MonitorOptions") table {});

    /// Hanging-get API for changes in network reachability state.
    ///
    /// `Watch` returns a snapshot of the system's most recent reachability
    /// state information. The first call returns a current snapshot.
    /// Subsequent calls to `Watch` block until the previously-observed state
    /// changes.
    ///
    /// While this API guarantees that any state returned was a valid network
    /// state at some point, it does not guarantee observation of every
    /// intermediate state.
    ///
    /// It is not valid to call `Watch` concurrently. Calling `Watch` while
    /// another call over the same server end is in flight will result in the
    /// closing the channel.
    ///
    /// - response a snapshot of current system reachability state.
    Watch() -> (Snapshot);
};

/// Information about network configuration and apparent reachability status
/// of external networks.
type Snapshot = table {
    /// Signifies whether internet reachability is available.
    1: internet_available bool;
};