// 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.hardware.hiddevice;

using zx;

enum HidReportType : uint8 {
    INPUT = 1;
    OUTPUT = 2;
    FEATURE = 3;
};

const uint16 HID_MAX_DESC_LEN = 8192;
const uint16 HID_MAX_REPORT_LEN = 8192;
const uint16 HID_MAX_REPORT_IDS = 256;

[Transport = "Banjo", BanjoLayout = "ddk-interface"]
protocol HidReportListener {
    /// Sends a single report to the listener. This comes with a timestamp that was gotten
    /// from the computer's monotonic clock.
    ReceiveReport(vector<uint8>:HID_MAX_REPORT_LEN report, zx.time report_time);
};

struct HidDeviceInfo {
    uint32 vendor_id;
    uint32 product_id;
    uint32 version;
};

[Transport = "Banjo", BanjoLayout = "ddk-protocol"]
protocol HidDevice {
    /// Register a listener to begin receiving HID Reports. At the moment only a single listener
    /// is supported. It is an error to call this without unregistering.
    RegisterListener(HidReportListener listener) -> (zx.status s);

    /// Unregister the listener.
    UnregisterListener();

    GetHidDeviceInfo() -> (HidDeviceInfo info);

    GetDescriptor() -> (zx.status s, vector<uint8>:HID_MAX_DESC_LEN descriptor);

    /// Request a given report. Can be used to get FEATURE and INPUT reports. Getting an OUTPUT
    /// report is an error. This should be used most frequently to get FEATURE reports,
    /// since most devices will send normal INPUT reports through the Listener API.
    GetReport(HidReportType rpt_type, uint8 rpt_id) -> (zx.status s, vector<uint8>:HID_MAX_REPORT_LEN
            report);

    /// Set a given report. Only FEATURE and OUTPUT type reports can be set. Setting an INPUT
    /// report is an error.
    SetReport(HidReportType rpt_type, uint8 rpt_id, vector<uint8>:HID_MAX_REPORT_LEN report) -> (zx.status s);
};