// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// API intended for retrieving a snapshot of the network health state. Returns
// properties of any available network technologies and any connected or
// connecting network when available.

// NOTE: This mojom should kept in sync with the copy in Chromium's repo in
// src/chromeos/services/network_health/public/mojom/network_health.mojom.

module chromeos.network_health.mojom;

import "mojo/network_types.mojom";

enum NetworkState {
  // The network type is available but not yet initialized.
  kUninitialized,
  // The network type is available but disabled or disabling.
  kDisabled,
  // The network type is prohibited by policy.
  kProhibited,
  // The network type is available and enabled or enabling, but no network
  // connection has been established.
  kNotConnected,
  // The network type is available and enabled, and a network connection is
  // in progress.
  kConnecting,
  // The network is in a portal state.
  kPortal,
  // The network is in a connected state, but connectivity is limited.
  kConnected,
  // The network is connected and online.
  kOnline,
};

// Wrapper for optional uint32. // TODO(https://crbug.com/657632): Remove this
// once Mojo properly supports this.
struct UInt32Value {
  // The value of the uint64.
  uint32 value;
};

// Contains information for a single network connection and underlying
// network technology e.g WiFi.
struct Network {
  chromeos.network_config.mojom.NetworkType type;
  NetworkState state;
  // The unique identifier for the network when a network service exists.
  string? guid;
  // The user facing name of the network if available.
  string? name;
  // Optional string for the network devices's mac_address. This field is not
  // intended to be parsed and is only for informational purposes.
  string? mac_address;
  // Signal strength of the network provided only for wireless networks. Values
  // are normalized between 0 to 100 inclusive. Values less than 30 are
  // considered potentially problematic for the connection. See
  // src/platform2/shill/doc/service-api.txt for more details.
  UInt32Value? signal_strength;
  // Optional string for the network's ipv4_address. This is only intended to be
  // used for display and is not meant to be parsed.
  string? ipv4_address;
  // Optional list of strings for the network's ipv6_addresses. A single network
  // can have multiple addresses (local, global, temporary etc.). This is only
  // intended to be used for display and is not meant to be parsed.
  array<string> ipv6_addresses;
  // An enum of the network's captive portal state. This information is
  // supplementary to the NetworkState.
  chromeos.network_config.mojom.PortalState portal_state = kUnknown;
};

// Aggregate structure for all of the network health state.
struct NetworkHealthState {
  // This is a list of networking devices and any associated connections. Only
  // networking technologies that are present on the device are included.
  // Networks will be sorted with active connections listed first.
  array<Network> networks;
};

// Implemented by clients who desire network notifications.
interface NetworkEventsObserver {
  // Fired when a network’s connection state changes.
  OnConnectionStateChanged(string guid, NetworkState state);
  // Fired when a wireless network’s signal strength changes by ten or more
  // percent.
  OnSignalStrengthChanged(string guid, UInt32Value signal_strength);
};

// Interface for retrieving aggregated information about the current network
// state and health.
interface NetworkHealthService {
  // Adds an observer to be notified on network events. The caller can remove
  // the observer created by this call by closing their end of the message
  // pipe.
  AddObserver(pending_remote<NetworkEventsObserver> observer);

  // Returns a list of networks. See NetworkHealthState.networks for more
  // details.
  GetNetworkList() => (array<Network> networks);

  // Returns the current network health state.
  // This is currently the same information provided by GetNetworkList. More
  // information will be added over time.
  GetHealthSnapshot() => (NetworkHealthState state);
};