// 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.snoop;

using fuchsia.io as io;
using zx;

/// HCI packet format
/// Defined by the Core Specification (v5.4: Vol 4, Part E, Sec 5.4)
type PacketFormat = flexible enum {
    /// Command sent to the controller from the host.
    COMMAND = 1;
    /// Exchange of data between host and controller.
    ACL_DATA = 2;
    /// Exchange of synchronous data (SCO or eSCO) betweeen host and controller.
    SYNCHRONOUS_DATA = 3;
    /// Used by the controller to notify the host when events occur.
    EVENT = 4;
    /// Used to exchange isochronous data between the host and controller.
    ISO_DATA = 5;
};

type SnoopPacket = table {
    /// true if this packet is sent from the controller to the host.
    /// Always present.
    1: is_received bool;
    /// Packet format, determined by the transport.
    /// Always present.
    2: format PacketFormat;
    /// Timestamp that the snoop service received the packet from a transport
    /// as measured by the host system, in system monotonic time.
    3: timestamp zx.Time;
    /// Length of the packet. This may differ from the length of `data`
    /// as payloads can be truncated for storage reasons.
    4: length uint32;
    /// Packet data. This may be truncated, but if non-empty contains the packet
    /// data starting from the beginning.
    5: data vector<uint8>:MAX;
};

type CaptureError = flexible union {
    /// Unrecognized device name
    1: UnrecognizedDeviceName table {};
};

type DevicePackets = table {
    /// The device these packets were observed from.
    /// Always provided.
    1: host_device string:io.MAX_FILENAME;
    /// Set of packets that were observed.
    /// Always provided.
    2: packets vector<SnoopPacket>:MAX;
};

open protocol PacketObserver {
    /// Observe some packets which have been transmitted over HCI.
    /// Return ack is used for flow control.
    flexible Observe(DevicePackets) -> ();

    /// Called when an error occurs either during capture or while starting
    /// capture.  The protocol will be closed after this is sent.
    flexible Error(CaptureError);
};

/// Interface to receive packets recorded as received or transmitted for a Bluetooth host.
@discoverable
open protocol Snoop {
    /// Subscribe to receive packets from the server. Packets that have been recorded are sent
    /// first.
    ///
    /// If `follow` is true, the protocol stays open and packets are returned to the client as
    /// the snoop server receives them. If `follow` is missing or false, the client is closed
    /// when all currently recorded packets have been sent.
    ///
    /// A `host_device` name may be provided; if so, only events from that host are sent.
    /// If `host_device` is absent, packets from all host devices are sent.
    ///
    /// Errors are reported through the client.
    flexible Start(resource table {
        1: follow bool;
        2: host_device string:io.MAX_FILENAME;
        3: client client_end:PacketObserver;
    });
};