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

using fuchsia.lowpan;
using zx;

/// Protocol for connecting to [`LegacyJoining`] on a LoWPAN
/// interface.
@discoverable
protocol LegacyJoiningConnector {
    /// Connects to the [`LegacyJoining`] protocol on the
    /// named LoWPAN interface.
    ///
    /// The name of the interface can be learned by calling
    /// [`fuchsia.lowpan/Lookup.GetDevices`].
    ///
    /// If there is an error in processing this request
    /// the given channel is closed and an epitaph code used
    /// to describe the reason for the failure:
    ///
    /// * `ZX_ERR_INVALID_ARGUMENT`: The given interface name
    ///   was not formatted correctly or otherwise invalid.
    /// * `ZX_ERR_NOT_FOUND`: No interface was found with the
    ///   given name.
    /// * `ZX_ERR_NOT_SUPPORTED`: The interface exists but
    ///   does not support this protocol.
    Connect(resource struct {
        name fuchsia.lowpan.InterfaceName;
        server_end server_end:LegacyJoining;
    });
};

/// Protocol for supporting non-standard in-band commissioning protocols.
/// Only one instance of this protocol may be valid at a time: after the
/// first request all subsequent requests for this protocol will fail until
/// the first instance is closed.
protocol LegacyJoining {
    /// Makes the interface joinable for Thread devices that need to use a
    /// non-standard in-band commissioning protocol. It is not used for
    /// standard Thread commissioning.
    ///
    /// When this call returns, the interface has been made joinable if
    /// requested.
    ///
    /// Subsequent calls to this method will override previous calls.
    /// To force the interface to no longer be joinable immediately, call
    /// this method with a duration of zero seconds and a port of zero (port
    /// is ignored in this case).
    ///
    /// This method must only be called when the interface is online
    /// (Specifically, either attaching, attached, or isolated). If the
    /// interface is in any other state, the channel will be closed with
    /// `ZX_ERR_BAD_STATE`.
    ///
    /// `duration` specifies a minimum time the interface should be made
    /// joinable, relative to the time the call is received. It may be rounded
    /// up to the nearest second.
    ///
    /// `port` specifies the local port that TCP or UDP commissioning traffic
    /// will be directed to.
    MakeJoinable(struct {
        duration zx.duration;
        port uint16;
    }) -> ();
};