// 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.avrcp.test;

using fuchsia.bluetooth as bt;
using fuchsia.bluetooth.avrcp as avrcp;
using zx;

/// NOTE: The test controller protocols returned by the
/// `Get{Browse|}ControllerForTarget` methods provide additional methods not
/// exposed by primary controller protocol that are designed to be used
/// for PTS qualification testing and debugging purposes only.
/// WARNING: This test controller protocol client can cause breaking
/// side-effects for other controller clients connected to this the same peer.
/// Use with caution and avoid having additional primary controller
/// clients interacting with the same remote peer while using the test
/// controller.
@discoverable
closed protocol PeerManagerExt {
    /// Returns a test browse controller client to a remote target service at
    /// the peer specified by `peer_id`. This client is to be used alongside the
    /// primary browse controller client.
    strict GetBrowseControllerForTarget(resource struct {
        peer_id bt.PeerId;
        client server_end:BrowseControllerExt;
    }) -> () error zx.Status;

    /// Returns a test controller client to a remote target service at the
    /// peer specified by `peer_id`. This client is to be used alongside the
    /// primary controller client.
    strict GetControllerForTarget(resource struct {
        peer_id bt.PeerId;
        client server_end:ControllerExt;
    }) -> () error zx.Status;
};

/// Provides additional methods not in `Controller` that are strictly for testing and debug.
closed protocol ControllerExt {
    /// Returns whether there is an underlying connection open with the remote device currently.
    strict IsConnected() -> (struct {
        connected bool;
    });

    /// Queries the target and returns what events are supported for notification.
    /// Sends GetCapabilties(0x03 (`EVENTS_SUPPORTED`)) command for all events supported by
    /// the negoitated version of AVRCP.
    strict GetEventsSupported() -> (struct {
        events_supported vector<avrcp.NotificationEvent>:avrcp.MAX_NOTIFICATIONS;
    }) error avrcp.ControllerError;

    /// Send raw vendor depedent "Control" command packet to a specific PDU on the remote peer.
    /// Returns the entire response packet including the headers or error if the remote endpoint
    /// disconnects or does not return a response in set amount of time.
    strict SendRawVendorDependentCommand(struct {
        pdu_id uint8;
        command vector<uint8>:MAX;
    }) -> (struct {
        response vector<uint8>:MAX;
    }) error avrcp.ControllerError;
};

/// Provides additional methods not in `BrowseController` that are strictly for
/// testing and debug.
closed protocol BrowseControllerExt {
    /// Returns whether there is an underlying connection open with the remote device currently.
    strict IsConnected() -> (struct {
        connected bool;
    });

    /// Send raw AVRCP "browse" command packet to a specific PDU on the remote peer.
    /// Returns the entire response packet including the headers or error if the remote endpoint
    /// disconnects or does not return a response in set amount of time.
    /// + request `command` contains a specific browse command's encoded
    ///         parameters.
    strict SendRawBrowseCommand(struct {
        pdu_id uint8;
        command vector<uint8>:MAX;
    }) -> (struct {
        response vector<uint8>:MAX;
    }) error avrcp.BrowseControllerError;
};