// 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();
};
Codebase Browser
chromium