extensions/common/api/usb.idl

   1 // Copyright 2014 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 // Use the <code>chrome.usb</code> API to interact with connected USB
   6 // devices. This API provides access to USB operations from within the context
   7 // of an app. Using this API, apps can function as drivers for hardware devices.
   8 //
   9 // Errors generated by this API are reported by setting
  10 // $(ref:runtime.lastError) and executing the function's regular callback. The
  11 // callback's regular parameters will be undefined in this case.
  12 namespace usb {
  13
  14   // Direction, Recipient, RequestType, and TransferType all map to their
  15   // namesakes within the USB specification.
  16   enum Direction {in, out};
  17   enum Recipient {device, _interface, endpoint, other};
  18   enum RequestType {standard, class, vendor, reserved};
  19   enum TransferType {control, interrupt, isochronous, bulk};
  20
  21   // For isochronous mode, SynchronizationType and UsageType map to their
  22   // namesakes within the USB specification.
  23   enum SynchronizationType {asynchronous, adaptive, synchronous};
  24   enum UsageType {data, feedback, explicitFeedback};
  25
  26   dictionary Device {
  27     // An opaque ID for the USB device. It remains unchanged until the device is
  28     // unplugged.
  29     long device;
  30     // The device vendor ID.
  31     long vendorId;
  32     // The product ID.
  33     long productId;
  34     // The iProduct string read from the device, if available.
  35     DOMString productName;
  36     // The iManufacturer string read from the device, if available.
  37     DOMString manufacturerName;
  38     // The iSerialNumber string read from the device, if available.
  39     DOMString serialNumber;
  40   };
  41
  42   dictionary ConnectionHandle {
  43     // An opaque handle representing this connection to the USB device and all
  44     // associated claimed interfaces and pending transfers. A new handle is
  45     // created each time the device is opened. The connection handle is
  46     // different from $(ref:Device.device).
  47     long handle;
  48     // The device vendor ID.
  49     long vendorId;
  50     // The product ID.
  51     long productId;
  52   };
  53
  54   [noinline_doc] dictionary EndpointDescriptor {
  55     // Endpoint address.
  56     long address;
  57     // Transfer type.
  58     TransferType type;
  59     // Transfer direction.
  60     Direction direction;
  61     // Maximum packet size.
  62     long maximumPacketSize;
  63     // Transfer synchronization mode (isochronous only).
  64     SynchronizationType? synchronization;
  65     // Endpoint usage hint.
  66     UsageType? usage;
  67     // Polling interval (interrupt and isochronous only).
  68     long? pollingInterval;
  69     // Extra descriptor data associated with this endpoint.
  70     ArrayBuffer extra_data;
  71   };
  72
  73   [noinline_doc] dictionary InterfaceDescriptor {
  74     // The interface number.
  75     long interfaceNumber;
  76     // The interface alternate setting number (defaults to <code>0</code).
  77     long alternateSetting;
  78     // The USB interface class.
  79     long interfaceClass;
  80     // The USB interface sub-class.
  81     long interfaceSubclass;
  82     // The USB interface protocol.
  83     long interfaceProtocol;
  84     // Description of the interface.
  85     DOMString? description;
  86     // Available endpoints.
  87     EndpointDescriptor[] endpoints;
  88     // Extra descriptor data associated with this interface.
  89     ArrayBuffer extra_data;
  90   };
  91
  92   [noinline_doc] dictionary ConfigDescriptor {
  93     // The configuration number.
  94     long configurationValue;
  95     // Description of the configuration.
  96     DOMString? description;
  97     // The device is self-powered.
  98     boolean selfPowered;
  99     // The device supports remote wakeup.
 100     boolean remoteWakeup;
 101     // The maximum power needed by this device in milliamps (mA).
 102     long maxPower;
 103     // Available interfaces.
 104     InterfaceDescriptor[] interfaces;
 105     // Extra descriptor data associated with this configuration.
 106     ArrayBuffer extra_data;
 107   };
 108
 109   dictionary ControlTransferInfo {
 110     // The transfer direction (<code>"in"</code> or <code>"out"</code>).
 111     Direction direction;
 112
 113     // The transfer target. The target given by <code>index</code> must be
 114     // claimed if <code>"interface"</code> or <code>"endpoint"</code>.
 115     Recipient recipient;
 116
 117     // The request type.
 118     RequestType requestType;
 119
 120     // The <code>bRequest</code> field, see <i>Universal Serial Bus Specification
 121     // Revision 1.1</i> &sect; 9.3.
 122     long request;
 123     // The <code>wValue</code> field, see <i>Ibid</i>.
 124     long value;
 125     // The <code>wIndex</code> field, see <i>Ibid</i>.
 126     long index;
 127
 128     // The amount of data to receive (required only by input transfers).
 129     long? length;
 130
 131     // The data to transmit (required only by output transfers).
 132     ArrayBuffer? data;
 133
 134     // Request timeout (in milliseconds). The default value <code>0</code>
 135     // indicates no timeout.
 136     long? timeout;
 137   };
 138
 139   dictionary GenericTransferInfo {
 140     // The transfer direction (<code>"in"</code> or <code>"out"</code>).
 141     Direction direction;
 142
 143     // The target endpoint address. The interface containing this endpoint must
 144     // be claimed.
 145     long endpoint;
 146
 147     // The amount of data to receive (required only by input transfers).
 148     long? length;
 149
 150     // The data to transmit (required only by output transfers).
 151     ArrayBuffer? data;
 152
 153     // Request timeout (in milliseconds). The default value <code>0</code>
 154     // indicates no timeout.
 155     long? timeout;
 156   };
 157
 158   dictionary IsochronousTransferInfo {
 159     // Transfer parameters. The transfer length or data buffer specified in this
 160     // parameter block is split along <code>packetLength</code> boundaries to
 161     // form the individual packets of the transfer.
 162     GenericTransferInfo transferInfo;
 163
 164     // The total number of packets in this transfer.
 165     long packets;
 166
 167     // The length of each of the packets in this transfer.
 168     long packetLength;
 169   };
 170
 171   dictionary TransferResultInfo {
 172     // A value of <code>0</code> indicates that the transfer was a success.
 173     // Other values indicate failure.
 174     long? resultCode;
 175
 176     // The data returned by an input transfer. <code>undefined</code> for output
 177     // transfers.
 178     ArrayBuffer? data;
 179   };
 180
 181   [noinline_doc] dictionary DeviceFilter {
 182     // Device vendor ID.
 183     long? vendorId;
 184     // Device product ID, checked only if the vendor ID matches.
 185     long? productId;
 186     // USB interface class, matches any interface on the device.
 187     long? interfaceClass;
 188     // USB interface sub-class, checked only if the interface class matches.
 189     long? interfaceSubclass;
 190     // USB interface protocol, checked only if the interface sub-class matches.
 191     long? interfaceProtocol;
 192   };
 193
 194   dictionary EnumerateDevicesOptions {
 195     [deprecated="Equivalent to setting $(ref:DeviceFilter.vendorId)."]
 196     long? vendorId;
 197     [deprecated="Equivalent to setting $(ref:DeviceFilter.productId)."]
 198     long? productId;
 199     // A device matching any given filter will be returned. An empty filter list
 200     // will return all devices the app has permission for.
 201     DeviceFilter[]? filters;
 202   };
 203
 204   dictionary EnumerateDevicesAndRequestAccessOptions {
 205     // The device vendor ID.
 206     long vendorId;
 207     // The product ID.
 208     long productId;
 209     // The interface ID to request access to.
 210     // Only available on Chrome OS. It has no effect on other platforms.
 211     long? interfaceId;
 212   };
 213
 214   dictionary DevicePromptOptions {
 215     // Allow the user to select multiple devices.
 216     boolean? multiple;
 217     // Filter the list of devices presented to the user. If multiple filters are
 218     // provided devices matching any filter will be displayed.
 219     DeviceFilter[]? filters;
 220   };
 221
 222   callback VoidCallback = void ();
 223   callback GetDevicesCallback = void (Device[] devices);
 224   callback RequestAccessCallback = void (boolean success);
 225   callback OpenDeviceCallback = void (ConnectionHandle handle);
 226   callback FindDevicesCallback = void (ConnectionHandle[] handles);
 227   callback GetConfigurationCallback = void (ConfigDescriptor config);
 228   callback ListInterfacesCallback = void (InterfaceDescriptor[] descriptors);
 229   callback CloseDeviceCallback = void ();
 230   callback TransferCallback = void (TransferResultInfo info);
 231   callback ResetDeviceCallback = void(boolean success);
 232
 233   interface Functions {
 234     // Enumerates connected USB devices.
 235     // |options|: The properties to search for on target devices.
 236     static void getDevices(EnumerateDevicesOptions options,
 237                            GetDevicesCallback callback);
 238
 239     // Presents a device picker to the user and returns the $(ref:Device)s
 240     // selected.
 241     // If the user cancels the picker devices will be empty. A user gesture
 242     // is required for the dialog to display. Without a user gesture, the
 243     // callback will run as though the user cancelled.
 244     // |options|: Configuration of the device picker dialog box.
 245     // |callback|: Invoked with a list of chosen $(ref:Device)s.
 246     static void getUserSelectedDevices(DevicePromptOptions options,
 247                                        GetDevicesCallback callback);
 248
 249     // Requests access from the permission broker to a device claimed by
 250     // Chrome OS if the given interface on the device is not claimed.
 251     //
 252     // |device|: The $(ref:Device) to request access to.
 253     // |interfaceId|: The particular interface requested.
 254     [deprecated="This function was Chrome OS specific and calling it on other
 255     platforms would fail. This operation is now implicitly performed as part of
 256     $(ref:openDevice) and this function will return <code>true</code> on all
 257     platforms."]
 258     static void requestAccess(Device device,
 259                               long interfaceId,
 260                               RequestAccessCallback callback);
 261
 262     // Opens a USB device returned by $(ref:getDevices).
 263     // |device|: The $(ref:Device) to open.
 264     static void openDevice(Device device, OpenDeviceCallback callback);
 265
 266     // Finds USB devices specified by the vendor, product and (optionally)
 267     // interface IDs and if permissions allow opens them for use.
 268     //
 269     // If the access request is rejected or the device fails to be opened a
 270     // connection handle will not be created or returned.
 271     //
 272     // Calling this method is equivalent to calling $(ref:getDevices) followed
 273     // by $(ref:openDevice) for each device.
 274     //
 275     // |options|: The properties to search for on target devices.
 276     static void findDevices(EnumerateDevicesAndRequestAccessOptions options,
 277                             FindDevicesCallback callback);
 278
 279     // Closes a connection handle. Invoking operations on a handle after it
 280     // has been closed is a safe operation but causes no action to be taken.
 281     // |handle|: The $(ref:ConnectionHandle) to close.
 282     static void closeDevice(ConnectionHandle handle,
 283                             optional CloseDeviceCallback callback);
 284
 285     // Select a device configuration.
 286     //
 287     // This function effectively resets the device by selecting one of the
 288     // device's available configurations. Only configuration values greater
 289     // than <code>0</code> are valid however some buggy devices have a working
 290     // configuration <code>0</code> and so this value is allowed.
 291     // |handle|: An open connection to the device.
 292     static void setConfiguration(ConnectionHandle handle,
 293                                  long configurationValue,
 294                                  VoidCallback callback);
 295
 296     // Gets the configuration descriptor for the currently selected
 297     // configuration.
 298     // |handle|: An open connection to the device.
 299     static void getConfiguration(ConnectionHandle handle,
 300                                  GetConfigurationCallback callback);
 301
 302     // Lists all interfaces on a USB device.
 303     // |handle|: An open connection to the device.
 304     static void listInterfaces(ConnectionHandle handle,
 305                                ListInterfacesCallback callback);
 306
 307     // Claims an interface on a USB device.
 308     // Before data can be transfered to an interface or associated endpoints the
 309     // interface must be claimed. Only one connection handle can claim an
 310     // interface at any given time. If the interface is already claimed, this
 311     // call will fail.
 312     //
 313     // $(ref:releaseInterface) should be called when the interface is no longer
 314     // needed.
 315     //
 316     // |handle|: An open connection to the device.
 317     // |interfaceNumber|: The interface to be claimed.
 318     static void claimInterface(ConnectionHandle handle, long interfaceNumber,
 319                                VoidCallback callback);
 320
 321     // Releases a claimed interface.
 322     // |handle|: An open connection to the device.
 323     // |interfaceNumber|: The interface to be released.
 324     static void releaseInterface(ConnectionHandle handle, long interfaceNumber,
 325                                  VoidCallback callback);
 326
 327     // Selects an alternate setting on a previously claimed interface.
 328     // |handle|: An open connection to the device where this interface has been
 329     //     claimed.
 330     // |interfaceNumber|: The interface to configure.
 331     // |alternateSetting|: The alternate setting to configure.
 332     static void setInterfaceAlternateSetting(ConnectionHandle handle,
 333                                              long interfaceNumber,
 334                                              long alternateSetting,
 335                                              VoidCallback callback);
 336
 337     // Performs a control transfer on the specified device.
 338     //
 339     // Control transfers refer to either the device, an interface or an
 340     // endpoint. Transfers to an interface or endpoint require the interface to
 341     // be claimed.
 342     //
 343     // |handle|: An open connection to the device.
 344     static void controlTransfer(ConnectionHandle handle,
 345                                 ControlTransferInfo transferInfo,
 346                                 TransferCallback callback);
 347
 348     // Performs a bulk transfer on the specified device.
 349     // |handle|: An open connection to the device.
 350     // |transferInfo|: The transfer parameters.
 351     static void bulkTransfer(ConnectionHandle handle,
 352                              GenericTransferInfo transferInfo,
 353                              TransferCallback callback);
 354
 355     // Performs an interrupt transfer on the specified device.
 356     // |handle|: An open connection to the device.
 357     // |transferInfo|: The transfer parameters.
 358     static void interruptTransfer(ConnectionHandle handle,
 359                                   GenericTransferInfo transferInfo,
 360                                   TransferCallback callback);
 361
 362     // Performs an isochronous transfer on the specific device.
 363     // |handle|: An open connection to the device.
 364     static void isochronousTransfer(ConnectionHandle handle,
 365                                     IsochronousTransferInfo transferInfo,
 366                                     TransferCallback callback);
 367
 368     // Tries to reset the USB device.
 369     // If the reset fails, the given connection handle will be closed and the
 370     // USB device will appear to be disconnected then reconnected.
 371     // In this case $(ref:getDevices) or $(ref:findDevices) must be called again
 372     // to acquire the device.
 373     //
 374     // |handle|: A connection handle to reset.
 375     static void resetDevice(ConnectionHandle handle,
 376                             ResetDeviceCallback callback);
 377   };
 378
 379   interface Events {
 380     // Event generated when a device is added to the system. Events are only
 381     // broadcast to apps and extensions that have permission to access the
 382     // device. Permission may have been granted at install time, when the user
 383     // accepted an optional permission (see $(ref:permissions.request)), or
 384     // through $(ref:getUserSelectedDevices).
 385     static void onDeviceAdded(Device device);
 386
 387     // Event generated when a device is removed from the system. See
 388     // $(ref:onDeviceAdded) for which events are delivered.
 389     static void onDeviceRemoved(Device device);
 390   };
 391 };