// 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);
};