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

/// Timestamp represents the number of seconds and nanoseconds since the Unix epoch.
struct Timestamp {
    /// Valid values for |subsec_nanos| can be greater than 10^9-1. Therefore the total
    /// seconds elapsed since the epoch is defined by the value of |seconds| plus
    /// |subsec_nanos| / 10^9 - the value of |seconds| alone may not be sufficient.
    ///
    /// It is invalid for the carry from |subsec_nanos| to overflow the |seconds| field.
    /// A client or server should reject such data as malformed.
    uint32 subsec_nanos;
    uint64 seconds;
};

/// Messages coming through the Host Controller Interface can be one of three types.
enum PacketType {
    /// Command sent from the host to the controller.
    CMD = 0;
    /// Event sent from the controller to the host.
    EVENT = 1;
    /// Data sent from the controller to the host.
    DATA = 2;
};

struct SnoopPacket {
    /// true if this packet is sent from the controller to the host.
    bool is_received;
    PacketType type;
    /// Timestamp that the bt-snoop service received the packet from a snoop channel as measured
    /// by the host system.
    Timestamp timestamp;
    /// Original length of the packet before truncation.
    uint32 original_len;
    /// Payload sent over the HCI.
    bytes payload;
};

/// Interface to receive packets recorded as received or transmitted for a Bluetooth host.
/// Packets are received by the client as datagrams through the fidl channel as |OnPacket|
/// events.
[Discoverable]
protocol Snoop {
    /// Subscribe to receive packets from the server. Packets that have been recorded are sent
    /// first.
    ///
    /// If |follow| is true, the channel stays open and packets are sent to the client as
    /// the snoop server receives them. If |follow| is false, the channel is closed by the server
    /// when all recorded packets have been sent.
    ///
    /// A |host_device| name may be provided; if so, only events from that host are sent to the client.
    /// If |host_device| is absent, the client is sent events from all host devices.
    ///
    /// Errors:
    ///   |Start| can only be called once per connection. After the first request, subsequent requests
    ///   always return an error.
    ///   |host_device| values that are not recognized by the server return an error.
    Start(bool follow, string? host_device) -> (fuchsia.bluetooth.Status status);

    /// An event containing a packet that the client has registered interest in receiving and the
    /// |host_device| which generated the packet.
    -> OnPacket(string host_device, SnoopPacket packet);
};