// Copyright 2019 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.bluetooth.sys;

using fuchsia.bluetooth as bt;

/// Input and Output Capabilities for pairing exchanges.
/// See Volume 3, Part C, Table 5.3 and 5.4
enum InputCapability {
    NONE = 1;
    CONFIRMATION = 2;
    KEYBOARD = 3;
};

enum OutputCapability {
    NONE = 1;
    DISPLAY = 2;
};

/// Different types required by the Security Manager for pairing methods.
/// Bluetooth SIG has different requirements for different device capabilities.
enum PairingMethod {
    /// The user is asked to accept or reject pairing.
    CONSENT = 1;

    /// The user is shown a 6-digit numerical passkey which they must enter on the
    /// peer device.
    PASSKEY_DISPLAY = 2;

    /// The user is shown a 6-digit numerical passkey which will also shown on the
    /// peer device. The user must compare the passkeys and accept the pairing if
    /// the passkeys match.
    PASSKEY_COMPARISON = 3;

    /// The user is asked to enter a 6-digit passkey.
    PASSKEY_ENTRY = 4;
};

enum PairingKeypress {
    /// The user has entered a single digit.
    DIGIT_ENTERED = 1;

    /// The user has erased a single digit.
    DIGIT_ERASED = 2;

    /// The user has cleared the entire passkey.
    PASSKEY_CLEARED = 3;

    /// The user has finished entering the passkey.
    PASSKEY_ENTERED = 4;
};

protocol PairingDelegate {
    /// Called to initiate a pairing request. The delegate must respond with "true" or "false" to
    /// either accept or reject the pairing request. If the pairing method requires a passkey
    /// this is returned as well.
    ///
    /// Any response from this method will be ignored if the OnPairingComplete
    /// event has already been sent for `peer`.
    ///
    /// The `displayed_passkey` parameter should be displayed to the user if `method` equals
    /// `PairingMethod.PASSKEY_DISPLAY` or `PairingMethod.PASSKEY_COMPARISON`. Otherwise, this parameter
    /// has no meaning and should be ignored.
    ///
    /// The `entered_passkey` parameter only has meaning if `method` equals
    /// `PairingMethod.PASSKEY_ENTRY`. It will be ignored otherwise.
    OnPairingRequest(Peer peer, PairingMethod method, uint32 displayed_passkey)
        -> (bool accept, uint32 entered_passkey);

    /// Called if the pairing procedure for the device with the given ID is completed.
    /// This can be due to successful completion or an error (e.g. due to cancellation
    /// by the peer, a timeout, or disconnection) which is indicated by `success`.
    OnPairingComplete(bt.PeerId id, bool success);

    /// Called to notify keypresses from the peer device during pairing using
    /// `PairingMethod.PASSKEY_DISPLAY`.
    ///
    /// This event is used to provide key press events to the delegate for a responsive user
    /// experience as the user types the passkey on the peer device. This event will be called
    /// once for each key-press.
    OnRemoteKeypress(bt.PeerId id, PairingKeypress keypress);

    /// The delegate can send this event to notify the peer of local keypresses
    /// during pairing using `PairingMethod.PASSKEY_ENTRY`.
    -> OnLocalKeypress(bt.PeerId id, PairingKeypress keypress);
};