// 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=7)
library fuchsia.lowpan;

/// Index used to identify a specific channel in the LoWPAN API.
alias ChannelIndex = uint16;

/// Transmit/Received power, in dBm.
///
/// Can represent transmit and receive power levels from .2 femtowatts (-127dBm)
/// to 5 gigawatts (127dBm).
///
/// The value -128 ([`RSSI_UNSPECIFIED`]) is reserved for
/// indicating that a signal level is unspecified when used
/// in the context of RSSI values, and must not be used when
/// specifying transmit power.
alias PowerDbm = int8;

/// LoWPAN MAC address.
///
/// On 802.15.4 networks, this is an EUI64.
@available(added=9)
alias MacAddress = bytes:8;

/// Type describing the name of the network interface.
///
/// Interface names must satisfy the following regular expression:
///
///     ^[a-z_][-_.+0-9a-z]{1,31}$
///
alias InterfaceName = string:32;

// Arbitrarily chosen at an expected maximum number of radio interfaces on
// a single device.
const MAX_LOWPAN_DEVICES uint32 = 8;

/// Protocol for discovering and resolving LoWPAN interfaces and their
/// associated control protocol instances.
@discoverable
protocol DeviceWatcher {
    /// Observes when devices are added or removed.
    ///
    /// The first call to this method returns immediately with a
    /// `DeviceChanges` struct containing only items in the `added` field with
    /// the names of all of the current devices. Subsequent calls
    /// will block until a device has been added or removed, at which
    /// point it will return with the `added` and/or `removed` fields
    /// filled out accordingly. The changes are reported since the
    /// time that the method returned.
    ///
    /// If both the `added` and `removed` fields have names in the returned
    /// table, then the `removed` field MUST be processed BEFORE `added` field.
    ///
    /// If a device was added and then removed in-between calls to this
    /// method, the device will be absent from both the `added` and `removed`
    /// lists.
    ///
    /// If the same device name is listed on both the `added` and `removed`
    /// fields, then the client should assume that the original device was
    /// removed and a new device instance started in its place. However, while
    /// the client should be able to handle this condition, it should not depend
    /// on the server will always have this behavior.
    WatchDevices() -> (struct {
        added vector<InterfaceName>:MAX_LOWPAN_DEVICES;
        removed vector<InterfaceName>:MAX_LOWPAN_DEVICES;
    });
};