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