sdk/fidl/fuchsia.input.report/device.fidl

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

/// At the moment calling `ReadReports` drains the same report FIFO used
/// by fuchsia.input.report.InputDevice:GetReports.
/// TODO(44923) Remove GetReports API and then give InputReportsReader its own
/// FIFO.
protocol InputReportsReader {
    /// This is a Hanging-Get function to read the reports in the
    /// Report 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. At the moment, only one
    /// GetInputReportsReader can be created per connection to InputDevice
    /// TODO(44923) Remove GetReports API and then allow multiple
    /// InputReportsReaders.
    GetInputReportsReader(request<InputReportsReader> reader);

    /// Receive an event that will be signalled when there are reports in the
    /// Device's report FIFO. When there are events in the FIFO, `event` will have
    /// `DEV_STATE_READABLE` triggered. When the client has read all of the events,
    /// `DEV_STATE_READABLE` will be  cleared.
    GetReportsEvent() -> (zx.status status, zx.handle:EVENT event);

    /// Get all of the reports that have been seen since the last time this method was called.
    /// If this returns 0 reports, please wait on the report event.
    GetReports() -> (vector<InputReport>:MAX_DEVICE_REPORT_COUNT reports);

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