// Copyright 2018 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.control;

using fuchsia.bluetooth;

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

enum OutputCapabilityType {
    NONE = 0;
    DISPLAY = 1;
};

/// 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 = 0;

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

    /// 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 = 2;

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

enum PairingKeypressType {
    /// The user has entered a single digit.
    DIGIT_ENTERED = 0;

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

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

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

protocol PairingDelegate {
    /// Called for most pairing requests. 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 `device`.
    OnPairingRequest(RemoteDevice device, PairingMethod method, string? displayed_passkey)
        -> (bool accept, string? 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 `status`.
    OnPairingComplete(string device_id, fuchsia.bluetooth.Status status);

    /// 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(string device_id, PairingKeypressType keypress);

    /// The delegate can send this event to notify the peer of local keypresses
    /// during pairing using PairingMethod.PASSKEY_ENTRY.
    -> OnLocalKeypress(string device_id, PairingKeypressType keypress);
};