// Copyright 2023 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.

library fuchsia.net.root;

using fuchsia.net;
using fuchsia.net.interfaces.admin;

/// Provides access to installed network interfaces.
///
/// This protocol provides the ability to bypass regular ownership-controls
/// which allow only the interface owner (generally the entity installing the
/// interface) to perform management operations on an interface.
///
/// Circumventing the strong-ownership semantics through use of this protocol
/// is highly discouraged and applications considering use of this protocol
/// are encouraged to exhaust other options first by working with the Netstack
/// team to find an alternative solution.
@discoverable
closed protocol Interfaces {
    /// Obtain administrative control over a network interface.
    ///
    /// + request `id` identifies the interface to be controlled.
    /// + request `control` grants the client administrative control over
    ///     the interface. Closed without a terminal event if `id` does not
    ///     match an existing interface.
    strict GetAdmin(resource struct {
        id fuchsia.net.InterfaceId;
        control server_end:fuchsia.net.interfaces.admin.Control;
    });

    /// Return an interface's MAC address.
    ///
    /// + request `id` identifies the interface whose MAC is requested.
    /// - response `mac` is the interface's MAC address, if it has one.
    // TODO(https://fxbug.dev/42165832): Use an API like `fuchsia.net.interfaces`
    // for L2 information.
    strict GetMac(struct {
        id fuchsia.net.InterfaceId;
    }) -> (struct {
        mac box<fuchsia.net.MacAddress>;
    }) error strict enum {
        /// `id` does not identify an interface.
        NOT_FOUND = 1;
    };
};