// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.os.events</code> API to subscribe to real time events.
[implemented_in = "chrome/browser/chromeos/extensions/telemetry/api/events/events_api.h"]
namespace os.events {
// Note: Please update documentation as well when this interface is changed.
// The documentation lives here: //docs/telemetry_extension/api_overview.md.
// LINT.IfChange

    enum EventCategory {
        audio_jack,
        lid,
        usb,
        sd_card,
        power,
        keyboard_diagnostic,
        stylus_garage,
        touchpad_button,
        touchpad_touch,
        touchpad_connected,
        touchscreen_touch,
        touchscreen_connected,
        external_display,
        stylus_touch,
        stylus_connected
    };

    enum EventSupportStatus {
        supported,
        unsupported
    };

    dictionary EventSupportStatusInfo {
        EventSupportStatus? status;
    };

    callback EventSupportStatusInfoCallback = void(
        EventSupportStatusInfo info);

    enum AudioJackEvent {
        // The audio jack was connected.
        connected,
        // The audio jack was disconnected.
        disconnected
    };

    enum AudioJackDeviceType {
        // The device is a headphone.
        headphone,
        // The device is a microphone.
        microphone
    };

    enum KeyboardConnectionType {
        // Includes devices connected over USB that are on fully internal
        // busses, as well as the keyboards/touchpads for detachables.
        internal,
        usb,
        bluetooth,
        // An unknown device is most likely to be internal.
        unknown
    };

    enum PhysicalKeyboardLayout {
        unknown,
        // A typical Chrome OS keyboard with action keys on the top row, reduced
        // navigation keys, etc.
        // TODO: Should we map Wilco and drallion to chromeos?
        chrome_os
    };

    // The international standard that the layout follows.
    enum MechanicalKeyboardLayout {
        unknown,
        ansi,
        iso,
        jis
    };

    enum KeyboardNumberPadPresence {
        // Unknown indicates there is no reliable evidence whether a numberpad
        // is present. This is common for external keyboards.
        unknown,
        present,
        not_present
    };

    enum KeyboardTopRowKey {
        // Either no key at all, or no special action key at this position.
        no_key,
        // Marker for keys which cannot be decoded, but have some action.
        unknown,
        back,
        forward,
        refresh,
        fullscreen,
        overview,
        screenshot,
        screen_brightness_down,
        screen_brightness_up,
        privacy_screen_toggle,
        microphone_mute,
        volume_mute,
        volume_down,
        volume_up,
        keyboard_backlight_toggle,
        keyboard_backlight_down,
        keyboard_backlight_up,
        next_track,
        previous_track,
        play_pause,
        screen_mirror,
        delete
    };

    enum KeyboardTopRightKey {
        unknown,
        power,
        lock,
        control_panel
    };

    // Describes a connected keyboard.
    dictionary KeyboardInfo {
        // The number of the keyboard's /dev/input/event* node.
        long? id;
        KeyboardConnectionType? connectionType;
        DOMString? name;
        PhysicalKeyboardLayout? physicalLayout;
        MechanicalKeyboardLayout? mechanicalLayout;
        // For internal keyboards, the region code of the device (from which the
        // visual layout can be determined).
        DOMString? regionCode;
        KeyboardNumberPadPresence? numberPadPresent;
        // List of ChromeOS specific action keys in the top row. This list
        // excludes the left-most Escape key, and right-most key (usually
        // Power/Lock).
        // If a keyboard has F11-F15 keys beyond the rightmost action key,
        // they may not be included in this list (even as "none").
        KeyboardTopRowKey[] topRowKeys;
        // For CrOS keyboards, the glyph shown on the key at the far right end
        // of the top row. This data may not be completely reliable.
        KeyboardTopRightKey? topRightKey;
        // Only applicable to CrOS keyboards.
        boolean? hasAssistantKey;
    };

    // Keyboard diagnostics event info. It is fired when users completed a
    // keyboard diagnostic in the Diagnostics App.
    dictionary KeyboardDiagnosticEventInfo {
        // The keyboard which has been tested.
        KeyboardInfo? keyboardInfo;
        // Keys which have been tested. It is an array of the evdev key code.
        long[] testedKeys;
        // Top row keys which have been tested. They are positions of the key on
        // the top row after escape (0 is leftmost, 1 is next to the right,
        // etc.).
        // Generally, 0 is F1, in some fashion.
        // NOTE: This position may exceed the length of
        // keyboard_info->top_row_keys, for external keyboards with keys in the
        // F11-F15 range.
        long[] testedTopRowKeys;
    };

    enum LidEvent {
        // The lid was closed.
        closed,
        // The lid was opened.
        opened
    };

    enum UsbEvent {
        // A USB device was connected.
        connected,
        // A USB device was disconnected.
        disconnected
    };

    enum ExternalDisplayEvent {
        // An external display was connected.
        connected,
        // An external display was disconnected.
        disconnected
    };

    enum SdCardEvent {
        // A SD card was connected.
        connected,
        // A SD card was disconnected.
        disconnected
    };

    enum PowerEvent {
        // The device began consuming from an external power source.
        ac_inserted,
        // The device stopped consuming from an external power source.
        ac_removed,
        // The system received a suspend request.
        os_suspend,
        // The system completed a suspend request, i.e. resumed again.
        os_resume
    };

    enum StylusGarageEvent {
        // Stylus inserted into the garage.
        inserted,
        // Stylus removed from the garage.
        removed
    };

    dictionary AudioJackEventInfo {
        AudioJackEvent? event;
        AudioJackDeviceType? deviceType;
    };

    dictionary LidEventInfo {
        LidEvent? event;
    };

    dictionary UsbEventInfo {
        // Vendor name.
        DOMString? vendor;
        // Name, model name, product name.
        DOMString? name;
        // Vendor ID.
        long? vid;
        // Product ID.
        long? pid;
        // USB device categories.
        // https://www.usb.org/defined-class-codes
        DOMString[] categories;
        UsbEvent? event;
    };

    // An enumeration of display input type.
    enum DisplayInputType {
      // Unknown enum value.
      unknown,
      // Digital input.
      digital,
      // Analog input.
      analog
    };

    dictionary ExternalDisplayInfo {
      // Display width in millimeters.
      long? displayWidth;
      // Display height in millimeters.
      long? displayHeight;
      // Horizontal resolution.
      long? resolutionHorizontal;
      // Vertical resolution.
      long? resolutionVertical;
      // Refresh rate.
      double? refreshRate;
      // Three letter manufacturer ID.
      DOMString? manufacturer;
      // Manufacturer product code.
      long? modelId;
      // 32 bits serial number.
      long? serialNumber;
      // Week of manufacture.
      long? manufactureWeek;
      // Year of manufacture.
      long? manufactureYear;
      // EDID version.
      DOMString? edidVersion;
      // Digital or analog input.
      DisplayInputType inputType;
      // Name of display product.
      DOMString? displayName;
    };


    dictionary ExternalDisplayEventInfo {
        ExternalDisplayEvent? event;
        ExternalDisplayInfo? displayInfo;
    };

    dictionary SdCardEventInfo {
        SdCardEvent? event;
    };

    dictionary PowerEventInfo {
        PowerEvent? event;
    };

    dictionary StylusGarageEventInfo {
        StylusGarageEvent? event;
    };

    // An enumeration of input touch buttons. The enumeration refers to the
    // physical button that is present in some touchpads under the surface.
    // Clicks resulting from gestures such as two finger right-click are not
    // included here. Separate physical buttons external to the touchpad are
    // also not included.
    enum InputTouchButton {
      // Left key.
      left,
      // Middle key.
      middle,
      // Right key.
      right
    };

    enum InputTouchButtonState {
        // The button was pressed.
        pressed,
        // The button was released.
        released
    };

    dictionary TouchpadButtonEventInfo {
      InputTouchButton? button;
      InputTouchButtonState? state;
    };

    dictionary TouchPointInfo {
      // An id to track an initiated contact throughout its life cycle.
      long? trackingId;
      // The x position.
      long? x;
      // The y position.
      long? y;
      // The pressure applied to the touch contact. The value ranges from 0 to
      // |max_pressure| as defined in TouchpadConnectedEventInfo.
      long? pressure;
      // The length of the longer dimension of the touch contact.
      long? touchMajor;
      // The length of the shorter dimension of the touch contact.
      long? touchMinor;
    };

    dictionary TouchpadTouchEventInfo {
      // The touch points reported by the touchpad.
      TouchPointInfo[] touchPoints;
    };

    dictionary TouchpadConnectedEventInfo {
      // The maximum possible x position of touch points.
      long? maxX;
      // The maximum possible y position of touch points.
      long? maxY;
      // The maximum possible pressure of touch points, or 0 if pressure is not
      // supported.
      long? maxPressure;
      // The supported buttons;
      InputTouchButton[] buttons;
    };

    dictionary TouchscreenTouchEventInfo {
      // The touch points reported by the touchscreen.
      TouchPointInfo[] touchPoints;
    };

    dictionary TouchscreenConnectedEventInfo {
      // The maximum possible x position of touch points.
      long? maxX;
      // The maximum possible y position of touch points.
      long? maxY;
      // The maximum possible pressure of touch points, or 0 if pressure is not
      // supported.
      long? maxPressure;
    };

    dictionary StylusTouchPointInfo {
      // The x position. The value ranges from 0 to |max_x| as defined in
      // StylusConnectedEventInfo.
      long? x;
      // The y position. The value ranges from 0 to |max_y| as defined in
      // StylusConnectedEventInfo.
      long? y;
      // The pressure applied to the touch contact. The value ranges from 0 to
      // |max_pressure| as defined in StylusConnectedEventInfo.
      long? pressure;
    };

    dictionary StylusTouchEventInfo {
      // The info of the stylus touch point. A null touch point means the stylus
      // leaves the contact.
      StylusTouchPointInfo? touch_point;
    };

    dictionary StylusConnectedEventInfo {
      // The maximum possible x position of touch points.
      long? max_x;
      // The maximum possible y position of touch points.
      long? max_y;
      // The maximum possible pressure of touch points, or 0 if pressure is not
      // supported.
      long? max_pressure;
    };

    callback VoidCallback = void();

    interface Functions {
        // Checks whether an event is supported. The information returned by
        // this method is valid across reboots of the device.
        static void isEventSupported(
            EventCategory category, EventSupportStatusInfoCallback callback);

        // Starts capturing events for `EventCategory`. After calling this
        // method, an extension can expect to be updated about events through
        // invocations of `on<EventCategory>Event`, until either the PWA is
        // closed or `stopCapturingEvents` is called. Note that an extension
        // is only able to subscribe to events if the PWA is currently open.
        static void startCapturingEvents(
            EventCategory category, VoidCallback callback);

        // Stops capturing `EventCategory` events. This means
        // `on<EventCategory>Event` won't be invoked until
        // `startCapturingEvents` is succesfully called.
        static void stopCapturingEvents(
            EventCategory category, VoidCallback callback);
    };

    interface Events {
        // Informs the extension  that an `AudioJack` event occured.
        static void onAudioJackEvent(AudioJackEventInfo event_info);

        // Informs the extension that a Keyboard diagnostic has been completed
        // in the first party diagnostic tool.
        static void onKeyboardDiagnosticEvent(
            KeyboardDiagnosticEventInfo event_info);

        // Informs the extension that a `Lid` event occured.
        static void onLidEvent(LidEventInfo event_info);

        // Informs the extension that a `Usb` event occured.
        static void onUsbEvent(UsbEventInfo event_info);

        // Informs the extension that an `ExternalDisplay` event occured.
        static void onExternalDisplayEvent(ExternalDisplayEventInfo event_info);

        // Informs the extension that a `SD Card` event occured.
        static void onSdCardEvent(SdCardEventInfo event_info);

        // Informs the extension that a `Power` event occured.
        static void onPowerEvent(PowerEventInfo event_info);

        // Informs the extension that a `Stylus Garage` event occured.
        static void onStylusGarageEvent(StylusGarageEventInfo event_info);

        // Informs the extension that a `Touchpad Button` event occured.
        static void onTouchpadButtonEvent(TouchpadButtonEventInfo event_info);

        // Informs the extension that a `Touchpad Touch` event occured.
        static void onTouchpadTouchEvent(TouchpadTouchEventInfo event_info);

        // Informs the extension that a `Touchpad Connected` event occured.
        static void onTouchpadConnectedEvent(
            TouchpadConnectedEventInfo event_info);

        // Informs the extension that a `Touchscreen Touch` event occured.
        static void onTouchscreenTouchEvent(
            TouchscreenTouchEventInfo event_info);

        // Informs the extension that a `Touchscreen Connected` event occured.
        static void onTouchscreenConnectedEvent(
            TouchscreenConnectedEventInfo event_info);

        // Informs the extension that a `Stylus Touch` event occured.
        static void onStylusTouchEvent(StylusTouchEventInfo event_info);

        // Informs the extension that a `Stylus Connected` event occured.
        static void onStylusConnectedEvent(StylusConnectedEventInfo event_info);
    };

  // LINT.ThenChange(//docs/telemetry_extension/api_overview.md)
  // The following is an empty definition, since the IDL compiler only accepts
  // comments over valid definitions.
  callback EOF = void();
};