device/devices_app/usb/public/interfaces/device.mojom

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 module device.usb;
   6
   7 enum OpenDeviceError {
   8   // Opening the device succeeded.
   9   OK,
  10
  11   // The operating system denied access to the device.
  12   ACCESS_DENIED,
  13 };
  14
  15 enum TransferDirection {
  16   IN,
  17   OUT,
  18 };
  19
  20 enum ControlTransferType {
  21   STANDARD,
  22   CLASS,
  23   VENDOR,
  24   RESERVED
  25 };
  26
  27 enum ControlTransferRecipient {
  28   DEVICE,
  29   INTERFACE,
  30   ENDPOINT,
  31   OTHER
  32 };
  33
  34 enum EndpointType {
  35   BULK,
  36   INTERRUPT,
  37   ISOCHRONOUS,
  38 };
  39
  40 struct EndpointInfo {
  41   uint8 endpoint_number;
  42   TransferDirection direction;
  43   EndpointType type;
  44   uint32 packet_size;
  45 };
  46
  47 struct AlternateInterfaceInfo {
  48   uint8 alternate_setting;
  49   uint8 class_code;
  50   uint8 subclass_code;
  51   uint8 protocol_code;
  52   string? interface_name;
  53   array<EndpointInfo> endpoints;
  54 };
  55
  56 struct InterfaceInfo {
  57   uint8 interface_number;
  58   array<AlternateInterfaceInfo> alternates;
  59 };
  60
  61 struct ConfigurationInfo {
  62   uint8 configuration_value;
  63   string? configuration_name;
  64   array<InterfaceInfo> interfaces;
  65 };
  66
  67 struct WebUsbFunctionSubset {
  68   uint8 first_interface;
  69   array<string> origins;
  70 };
  71
  72 struct WebUsbConfigurationSubset {
  73   uint8 configuration_value;
  74   array<string> origins;
  75   array<WebUsbFunctionSubset> functions;
  76 };
  77
  78 struct WebUsbDescriptorSet {
  79   array<string> origins;
  80   array<WebUsbConfigurationSubset> configurations;
  81 };
  82
  83 struct DeviceInfo {
  84   string guid;
  85   uint8 usb_version_major;
  86   uint8 usb_version_minor;
  87   uint8 usb_version_subminor;
  88   uint8 class_code;
  89   uint8 subclass_code;
  90   uint8 protocol_code;
  91   uint16 vendor_id;
  92   uint16 product_id;
  93   uint8 device_version_major;
  94   uint8 device_version_minor;
  95   uint8 device_version_subminor;
  96   string? manufacturer_name;
  97   string? product_name;
  98   string? serial_number;
  99   array<ConfigurationInfo> configurations;
 100   WebUsbDescriptorSet? webusb_allowed_origins;
 101 };
 102
 103 struct ControlTransferParams {
 104   ControlTransferType type;
 105   ControlTransferRecipient recipient;
 106   uint8 request;
 107   uint16 value;
 108   uint16 index;
 109 };
 110
 111 enum TransferStatus {
 112   // The transfer completed successfully.
 113   COMPLETED,
 114
 115   // The transfer failed due to a non-specific error.
 116   ERROR,
 117
 118   // The transfer timed out.
 119   TIMEOUT,
 120
 121   // The transfer was cancelled.
 122   CANCELLED,
 123
 124   // The transfer stalled.
 125   STALLED,
 126
 127   // The transfer failed because the device was disconnected from the host.
 128   DISCONNECT,
 129
 130   // The transfer succeeded, but the device sent more data than was requested.
 131   // This applies only to inbound transfers.
 132   BABBLE,
 133
 134   // The transfer succeeded, but the device sent less data than was requested.
 135   // This applies only to inbound transfers.
 136   SHORT_PACKET,
 137 };
 138
 139 interface Device {
 140   // Retrieve a DeviceInfo struct containing metadata about the device,
 141   // including the set of all available device configurations.
 142   GetDeviceInfo() => (DeviceInfo? info);
 143
 144   // Retrieves the device's currently active configuration. May return null if
 145   // the device is unconfigured.
 146   GetConfiguration() => (ConfigurationInfo? info);
 147
 148   // Opens the device. Methods below require the device be opened first.
 149   Open() => (OpenDeviceError error);
 150
 151   // Closes the device.
 152   Close() => ();
 153
 154   // Initiates a device control transfer to set the device's configuration to
 155   // one with the configuration value |value|.
 156   SetConfiguration(uint8 value) => (bool success);
 157
 158   // Claims a single interface in the current device configuration.
 159   ClaimInterface(uint8 interface_number) => (bool success);
 160
 161   // Releases a claimed interface in the current device configuration.
 162   ReleaseInterface(uint8 interface_number) => (bool success);
 163
 164   // Selects an alternate setting for a given claimed interface.
 165   SetInterfaceAlternateSetting(uint8 interface_number, uint8 alternate_setting)
 166       => (bool success);
 167
 168   // Resets the device.
 169   Reset() => (bool success);
 170
 171   // Clear the halt/stall condition for an endpoint.
 172   ClearHalt(uint8 endpoint) => (bool success);
 173
 174   // Initiates an inbound control transfer request. |params| determine the
 175   // details of the request. Transfers to recipients other than DEVICE require a
 176   // corresponding interface to be claimed.
 177   //
 178   // |length| specifies the expected number of bytes to receive for this
 179   // transfer. The size of |data| will never exceed |length|, and |data| will be
 180   // null if |status| is neither COMPLETED, BABBLE, or SHORT_PACKET.
 181   //
 182   // |timeout| specifies the request timeout in milliseconds. A timeout of 0
 183   // indicates no timeout: the request will remain pending indefinitely until
 184   // completed or otherwise terminated.
 185   ControlTransferIn(ControlTransferParams params, uint32 length, uint32 timeout)
 186       => (TransferStatus status, array<uint8>? data);
 187
 188   // Initiates an inbound control transfer request. |params| determine the
 189   // details of the request. Transfers to recipients other than DEVICE require a
 190   // corresponding interface to be claimed.
 191   //
 192   // |data| specifies the bytes to send the device in the body of the request.
 193   //
 194   // |timeout| specifies the request timeout in milliseconds. A timeout of 0
 195   // indicates no timeout: the request will remain pending indefinitely until
 196   // completed or otherwise terminated.
 197   ControlTransferOut(ControlTransferParams params,
 198                      array<uint8> data,
 199                      uint32 timeout)
 200       => (TransferStatus status);
 201
 202   // Initiates an inbound generic transfer request on a specific endpoint. The
 203   // interface to which |endpoint_number| belongs must be claimed, and the
 204   // appropriate alternate setting must be set on that interface before
 205   // transfers can be initiated on the endpoint. The endpoint must be of type
 206   // BULK or INTERRUPT.
 207   //
 208   // |length| specifies the expected number of bytes to receive for this
 209   // transfer. The size of |data| will never exceed |length|, and |data| will be
 210   // null if |status| is neither COMPLETED, BABBLE, or SHORT_PACKET.
 211   //
 212   // |timeout| specifies the request timeout in milliseconds. A timeout of 0
 213   // indicates no timeout: the request will remain pending indefinitely until
 214   // completed or otherwise terminated.
 215   GenericTransferIn(uint8 endpoint_number, uint32 length, uint32 timeout)
 216       => (TransferStatus status, array<uint8>? data);
 217
 218   // Initiates an outbound generic transfer request on a specific endpoint. The
 219   // interface to which |endpoint_number| belongs must be claimed, and the
 220   // appropriate alternate setting must be set on that interface before
 221   // transfers can be initiated on the endpoint. The endpoint must be of type
 222   // BULK or INTERRUPT.
 223   //
 224   // |data| specifies the bytes to send the device in the body of the request.
 225   //
 226   // |timeout| specifies the request timeout in milliseconds. A timeout of 0
 227   // indicates no timeout: the request will remain pending indefinitely until
 228   // completed or otherwise terminated.
 229   GenericTransferOut(uint8 endpoint_number, array<uint8> data, uint32 timeout)
 230       => (TransferStatus status);
 231
 232   // Initiates an inbound isochronous transfer request on a specific endpoint.
 233   // The interface to which |endpoint_number| belongs must be claimed, and the
 234   // appropriate alternate setting must be set on that interface before
 235   // transfers can be initiated on the endpoint. The endpoint must be of type
 236   // ISOCHRONOUS.
 237   //
 238   // |packet_length| specifies the maximum expected number of bytes to receive
 239   // for each packet in this transfer. |num_packets| specifies the maximum total
 240   // number of packets to receive.
 241   //
 242   // |timeout| specifies the request timeout in milliseconds. A timeout of 0
 243   // indicates no timeout: the request will remain pending indefinitely until
 244   // completed or otherwise terminated.
 245   //
 246   // |packets| contains the set of packets received from the device, in order.
 247   // No received packet's size will exceed |packet_length|, and will be null
 248   // if |status| is neither COMPLETED, BABBLE, or SHORT_PACKET.
 249   IsochronousTransferIn(uint8 endpoint_number,
 250                         uint32 num_packets,
 251                         uint32 packet_length,
 252                         uint32 timeout)
 253       => (TransferStatus status, array<array<uint8>>? packets);
 254
 255   // Initiates an outbound isochronous transfer request on a specific endpoint.
 256   // The interface to which |endpoint_number| belongs must be claimed, and the
 257   // appropriate alternate setting must be set on that interface before
 258   // transfers can be initiated on the endpoint. The endpoint must be of type
 259   // ISOCHRONOUS.
 260   //
 261   // |packets| specifies the series of data packets to send to the device for
 262   // this transfer.
 263   //
 264   // |timeout| specifies the request timeout in milliseconds. A timeout of 0
 265   // indicates no timeout: the request will remain pending indefinitely until
 266   // completed or otherwise terminated.
 267   IsochronousTransferOut(uint8 endpoint_number,
 268                          array<array<uint8>> packets,
 269                          uint32 timeout)
 270       => (TransferStatus status);
 271 };