// 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.input.report;

using zx;

const uint32 MAX_DEVICE_REPORT_COUNT = 50;

/// Each `InputReportsReader` has its own FIFO of InputReports that it maintains.
/// When ReadInputReports is called it drains the InputReports FIFO.
/// If too many InputReports are created before the FIFO is drained, then
/// the oldest InputReport will be silently discarded.
protocol InputReportsReader {
    /// This is a Hanging-Get function to read the reports in the
    /// InputReport FIFO. This will not reply until there is at least one
    /// report available.
    /// If there is already one outstanding Hanging-Get, calling this
    /// again will return ZX_ERR_ALREADY_BOUND.
    ReadInputReports() -> (vector<InputReport>:MAX_DEVICE_REPORT_COUNT reports) error zx.status;
};

/// An `InputDevice` driver represents a single physical input device.
/// The InputDevice maintains an internal FIFO of `MAX_DEVICE_REPORT_COUNT`
/// reports for each client that connects. Reports are removed from the FIFO
/// once they are read by the client. If the FIFO is full, it will drop the
/// oldest report to make room for an incoming report.
protocol InputDevice {
    /// Open a new InputReportsReader on this device. Each reader receives
    /// their own reports.
    GetInputReportsReader(request<InputReportsReader> reader);

    /// Gets the device descriptor for this device.
    GetDescriptor() -> (DeviceDescriptor descriptor);

    /// Send a single output report to the device. This will throw an error
    /// if the output report does not follow the OutputDescriptor.
    SendOutputReport(OutputReport report) -> () error zx.status;

    /// Get the feature report for a given device. This requests the state of
    /// the device's features.
    GetFeatureReport() -> (FeatureReport report) error zx.status;

    /// Set the feature report for a given device. This sets the state of
    /// the device's features.
    SetFeatureReport(FeatureReport report) -> () error zx.status;
};