Add more generic filters to the chrome.usb.getDevices API.

extensions/common/api/usb.idl

Index: extensions/common/api/usb.idl
diff --git a/extensions/common/api/usb.idl b/extensions/common/api/usb.idl
index 278171e4b6e5dff9f3ea17f9cbfd4b676a2f8ff9..e1f53c23676c54415822fb7d960321cb4cb51dd3 100644
--- a/extensions/common/api/usb.idl
+++ b/extensions/common/api/usb.idl
@@ -5,6 +5,10 @@
 // Use the <code>chrome.usb</code> API to interact with connected USB
 // devices. This API provides access to USB operations from within the context
 // of an app. Using this API, apps can function as drivers for hardware devices.
+//
+// Errors generated by this API are reported by setting
+// $(ref:runtime.lastError) and executing the function's regular callback. The
+// callback's regular parameters will be undefined in this case.
 namespace usb {
 
   // Direction, Recipient, RequestType, and TransferType all map to their
@@ -19,110 +23,107 @@ namespace usb {
   enum SynchronizationType {asynchronous, adaptive, synchronous};
   enum UsageType {data, feedback, explicitFeedback};
 
-  // Returned by |getDevices| to identify a connected USB device.
   dictionary Device {
-    // The id of the USB device. It remains unchanged until the device is
+    // An opaque ID for the USB device. It remains unchanged until the device is
     // unplugged.
     long device;
+    // The device vendor ID.
     long vendorId;
+    // The product ID.
     long productId;
   };
 
-  // Returned by |openDevice| to be used for USB communication.
-  // Every time a device is opened, a new connection handle is created.
-  //
-  // A connection handle represents the underlying data structure that contains
-  // all the data we need to communicate with a USB device, including the status
-  // of interfaces, the pending transfers, the descriptors, and etc. A connectin
-  // handle id is different from a USB device id.
-  //
-  // All connection handles can work together if the device allows it.
-  // The connection handle will be automatically closed when the app is reloaded
-  // or suspended.
-  //
-  // When a connection handle is closed, all the interfaces it claimed will be
-  // released and all the transfers in progress will be canceled immediately.
   dictionary ConnectionHandle {
-    // The id of the USB connection handle.
+    // An opaque handle representing this connection to the USB device and all
+    // associated claimed interfaces and pending transfers. A new handle is
+    // created each time the device is opened. The connection handle is
+    // different from $(ref:Device.device).
     long handle;
+    // The device vendor ID.
     long vendorId;
+    // The product ID.
     long productId;
   };
 
-  dictionary EndpointDescriptor {
+  [noinline_doc] dictionary EndpointDescriptor {
+    // Endpoint address.
     long address;
+    // Transfer type.
     TransferType type;
+    // Transfer direction.
     Direction direction;
+    // Maximum packet size.
     long maximumPacketSize;
-
-    // Used for isochronous mode.
+    // Transfer synchronization mode (isochronous only).
     SynchronizationType? synchronization;
+    // Endpoint usage hint.
     UsageType? usage;
-
-    // If this is an interrupt endpoint, this will be 1-255.
+    // Polling interval (interrupt and isochronous only).
     long? pollingInterval;
   };
 
-  dictionary InterfaceDescriptor {
+  [noinline_doc] dictionary InterfaceDescriptor {
+    // The interface number.
     long interfaceNumber;
+    // The interface alternate setting number (defaults to <code>0</code).
     long alternateSetting;
+    // The USB interface class.
     long interfaceClass;
+    // The USB interface sub-class.
     long interfaceSubclass;
+    // The USB interface protocol.
     long interfaceProtocol;
+    // Description of the interface.
     DOMString? description;
+    // Available endpoints.
     EndpointDescriptor[] endpoints;
   };
 
-  // ControlTransferInfo represents that parameters to a single USB control
-  // transfer.
   dictionary ControlTransferInfo {
-    // The direction of this transfer.
+    // The transfer direction (<code>"in"</code> or <code>"out"</code>).
     Direction direction;
 
-    // The intended recipient for this transfer.
+    // The transfer target. The target given by <code>index</code> must be
+    // claimed if <code>"interface"</code> or <code>"endpoint"</code>.
     Recipient recipient;
 
-    // The type of this request.
+    // The request type.
     RequestType requestType;
 
+    // The <code>bRequest</code> field, see <i>Universal Serial Bus Specification
+    // Revision 1.1</i> &sect; 9.3.
     long request;
+    // The <code>wValue</code> field, see <i>Ibid</i>.
     long value;
+    // The <code>wIndex</code> field, see <i>Ibid</i>.
     long index;
 
-    // If this transfer is an input transfer, then this field must be set to
-    // indicate the expected data length. If this is an output transfer, then
-    // this field is ignored.
+    // The amount of data to receive (required only by input transfers).
     long? length;
 
-    // The data payload carried by this transfer. If this is an output transfer
-    // then this field must be set.
+    // The data to transmit (required only by output transfers).
     ArrayBuffer? data;
   };
 
-  // GenericTransferInfo is used by both bulk and interrupt transfers to
-  // specify the parameters of the transfer.
   dictionary GenericTransferInfo {
-    // The direction of this transfer.
+    // The transfer direction (<code>"in"</code> or <code>"out"</code>).
     Direction direction;
 
+    // The target endpoint address. The interface containing this endpoint must
+    // be claimed.
     long endpoint;
 
-    // If this is an input transfer then this field indicates the size of the
-    // input buffer. If this is an output transfer then this field is ignored.
+    // The amount of data to receive (required only by input transfers).
     long? length;
 
-    // If this is an output transfer then this field must be populated.
-    // Otherwise, it will be ignored.
+    // The data to transmit (required only by output transfers).
     ArrayBuffer? data;
   };
 
-  // IsochronousTransferInfo describes a single multi-packet isochronous
-  // transfer.
   dictionary IsochronousTransferInfo {
-    // All of the normal transfer parameters are encapsulated in the
-    // transferInfo parameters. Note that the data specified in this parameter
-    // block is split along packetLength boundaries to form the individual
-    // packets of the transfer.
+    // Transfer parameters. The transfer length or data buffer specified in this
+    // parameter block is split along <code>packetLength</code> boundaries to
+    // form the individual packets of the transfer.
     GenericTransferInfo transferInfo;
 
     // The total number of packets in this transfer.
@@ -133,174 +134,176 @@ namespace usb {
   };
 
   dictionary TransferResultInfo {
-    // A value of 0 indicates that the transfer was a success. Other values
-    // indicate failure.
+    // A value of <code>0</code> indicates that the transfer was a success.
+    // Other values indicate failure.
     long? resultCode;
 
-    // If the transfer was an input transfer then this field will contain all
-    // of the input data requested.
+    // The data returned by an input transfer. <code>undefined</code> for output
+    // transfers.
     ArrayBuffer? data;
   };
 
-  // Describes the properties of devices which are found via |getDevices|.
+  [noinline_doc] dictionary DeviceFilter {
+    // Device vendor ID.
+    long? vendorId;
+    // Device product ID, checked only if the vendor ID matches.
+    long? productId;
+    // USB interface class, matches any interface on the device.
+    long? interfaceClass;
+    // USB interface sub-class, checked only if the interface class matches.
+    long? interfaceSubclass;
+    // USB interface protocol, checked only if the interface sub-class matches.
+    long? interfaceProtocol;
+  };
+
   dictionary EnumerateDevicesOptions {
-    long vendorId;
-    long productId;
+    [deprecated="Equivalent to setting $(ref:DeviceFilter.vendorId)."]
+    long? vendorId;
+    [deprecated="Equivalent to setting $(ref:DeviceFilter.productId)."]
+    long? productId;
+    // A device matching any given filter will be returned. An empty filter list
+    // will return all devices the app has permission for.
+    DeviceFilter[]? filters;
   };
   
-  // Describes the properties of devices which are found via |findDevices|.
   dictionary EnumerateDevicesAndRequestAccessOptions {
+    // The device vendor ID.
     long vendorId;
+    // The product ID.
     long productId;
-    // The interface id to request access against.
+    // The interface ID to request access to.
     // Only available on ChromeOS. It has no effect on other platforms.
     long? interfaceId;
   };
 
   callback VoidCallback = void ();
   callback GetDevicesCallback = void (Device[] devices);
-  callback RequestAccessCallback = void (boolean sucess);
+  callback RequestAccessCallback = void (boolean success);
   callback OpenDeviceCallback = void (ConnectionHandle handle);
   callback FindDevicesCallback = void (ConnectionHandle[] handles);
   callback ListInterfacesCallback = void (InterfaceDescriptor[] descriptors);
   callback CloseDeviceCallback = void ();
   callback TransferCallback = void (TransferResultInfo info);
-  callback ResetDeviceCallback = void(boolean result);
+  callback ResetDeviceCallback = void(boolean success);
 
   interface Functions {
-    // Lists USB devices specified by vendorId/productId/interfaceId tuple.
+    // Enumerate connected USB devices.
     // |options|: The properties to search for on target devices.
-    // |callback|: Invoked with a list of |Device|s on complete.
     static void getDevices(EnumerateDevicesOptions options,
                            GetDevicesCallback callback);
 
     // This method is ChromeOS specific. Calling this method on other platforms
     // will fail.
-    // Requests access from the permission broker to an OS claimed device if the
-    // given interface on the device is not claimed.
+    // Requests access from the permission broker to a device claimed by
+    // ChromeOS if the given interface on the device is not claimed.
     //
-    // |device|: The device to request access to.
-    // |interfaceId|: 
+    // |device|: The $(ref:Device) to request access to.
+    // |interfaceId|: The particular interface requested.
     static void requestAccess(Device device,
                               long interfaceId,
                               RequestAccessCallback callback);
 
-    // Opens a USB device returned by |getDevices|.
-    // |device|: The device to open.
-    // |callback|: Invoked with the created ConnectionHandle on complete.
+    // Opens a USB device returned by $(ref:getDevices).
+    // |device|: The $(ref:Device) to open.
     static void openDevice(Device device, OpenDeviceCallback callback);
 
-    // Finds USB devices specified by the vendorId/productId/interfaceId tuple
-    // and, if permissions allow, opens them for use.
+    // Finds USB devices specified by the vendor, product and (optionally)
+    // interface IDs and if permissions allow opens them for use.
     //
-    // On Chrome OS, you can specify the interfaceId. In that case the method
-    // will request access from permission broker in the same way as in
-    // |requestUsbAcess|.
+    // On Chrome OS, you can specify the interface ID. In that case the method
+    // will request access from permission broker in the same way as
+    // $(ref:requestUsbAccess).
     //
-    // If the access request is rejected, or the device is failed to be opened,
-    // its connection handle will not be created or returned.
+    // If the access request is rejected or the device fails to be opened a
+    // connection handle will not be created or returned.
     //
-    // Calling this method is equivalent to calling |getDevices| followed by
-    // a series of |requestAccess| (if it is on ChromeOs) and |openDevice|
-    // calls, and returning all the successfully opened connection handles.
+    // Calling this method is equivalent to calling $(ref:getDevices followed by
+    // $(ref:requestAccess) (if it is on ChromeOS) and $(ref:openDevice) for
+    // each device.
     //
     // |options|: The properties to search for on target devices.
-    // |callback|: Invoked with the opened ConnectionHandle on complete.
     static void findDevices(EnumerateDevicesAndRequestAccessOptions options,
                             FindDevicesCallback callback);
 
-    // Closes a connection handle. Invoking operations on a device after it
-    // has been closed is a safe operation, but causes no action to be taken.
-    // |handle|: The connection handle to close.
-    // |callback|: The callback to invoke once the device is closed.
+    // Closes a connection handle. Invoking operations on a handle after it
+    // has been closed is a safe operation but causes no action to be taken.
+    // |handle|: The $(ref:ConnectionHandle) to close.
     static void closeDevice(ConnectionHandle handle,
                             optional CloseDeviceCallback callback);
 
-    // Lists all the interfaces on the USB device.
-    // |handle|: The device from which the interfaces should be listed.
-    // |callback|: The callback to invoke when the interfaces are enumerated.
+    // Lists all interfaces on a USB device.
+    // |handle|: An open connection to the device.
     static void listInterfaces(ConnectionHandle handle,
                                ListInterfacesCallback callback);
 
-    // Claims an interface on the specified USB device.
-    // Before you can transfer data with endpoints, you must claim their parent
-    // interfaces. Only one connection handle on the same host can claim each
-    // interface. If the interface is already claimed, this call will fail.
+    // Claims an interface on a USB device.
+    // Before data can be transfered to an interface or associated endpoints the
+    // interface must be claimed. Only one connection handle can claim an
+    // interface at any given time. If the interface is already claimed, this
+    // call will fail.
     //
-    // You shall call releaseInterface when the interface is not needed anymore.
+    // $(ref:releaseInterface) should be called when the interface is no longer
+    // needed.
     //
-    // |handle|: The device on which the interface is to be claimed.
-    // |interface|: The interface number to be claimed.
-    // |callback|: The callback to invoke once the interface is claimed.
+    // |handle|: An open connection to the device.
+    // |interfaceNumber|: The interface to be claimed.
     static void claimInterface(ConnectionHandle handle, long interfaceNumber,
                                VoidCallback callback);
 
-    // Releases a claim to an interface on the provided device.
-    // |handle|: The device on which the interface is to be released.
-    // |interface|: The interface number to be released.
-    // |callback|: The callback to invoke once the interface is released.
+    // Releases a claimed interface.
+    // |handle|: An open connection to the device.
+    // |interfaceNumber|: The interface to be released.
     static void releaseInterface(ConnectionHandle handle, long interfaceNumber,
                                  VoidCallback callback);
 
-    // Selects an alternate setting on a previously claimed interface on a
-    // device.
-    // |handle|: The device on which the interface settings are to be set.
-    // |interface|: The interface number to be set.
-    // |alternateSetting|: The alternate setting to set.
-    // |callback|: The callback to invoke once the interface setting is set.
+    // Selects an alternate setting on a previously claimed interface.
+    // |handle|: An open connection to the device where this interface has been
+    //     claimed.
+    // |interfaceNumber|: The interface to configure.
+    // |alternateSetting|: The alternate setting to configure.
     static void setInterfaceAlternateSetting(ConnectionHandle handle,
                                              long interfaceNumber,
                                              long alternateSetting,
                                              VoidCallback callback);
 
-    // Performs a control transfer on the specified device. See the
-    // ControlTransferInfo structure for the parameters required to make a
-    // transfer.
+    // Performs a control transfer on the specified device.
     //
-    // Conceptually control transfer talks to the device itself. You do not need
-    // to claim interface 0 to perform a control transfer.
+    // Control transfers refer to either the device, an interface or an
+    // endpoint. Transfers to an interface or endpoint require the interface to
+    // be claimed.
     //
-    // |handle|: A connection handle to make the transfer on.
-    // |transferInfo|: The parameters to the transfer. See ControlTransferInfo.
-    // |callback|: Invoked once the transfer has completed.
+    // |handle|: An open connection to the device.
     static void controlTransfer(ConnectionHandle handle,
                                 ControlTransferInfo transferInfo,
                                 TransferCallback callback);
 
     // Performs a bulk transfer on the specified device.
-    // |handle|: A connection handle to make the transfer on.
-    // |transferInfo|: The parameters to the transfer. See GenericTransferInfo.
-    // |callback|: Invoked once the transfer has completed.
+    // |handle|: An open connection to the device.
+    // |transferInfo|: The transfer parameters.
     static void bulkTransfer(ConnectionHandle handle,
                              GenericTransferInfo transferInfo,
                              TransferCallback callback);
 
     // Performs an interrupt transfer on the specified device.
-    // |handle|: A connection handle to make the transfer on.
-    // |transferInfo|: The parameters to the transfer. See GenericTransferInfo.
-    // |callback|: Invoked once the transfer has completed.
+    // |handle|: An open connection to the device.
+    // |transferInfo|: The transfer parameters.
     static void interruptTransfer(ConnectionHandle handle,
                                   GenericTransferInfo transferInfo,
                                   TransferCallback callback);
 
     // Performs an isochronous transfer on the specific device.
-    // |handle|: A connection handle to make the transfer on.
-    // |transferInfo|: The parameters to the transfer. See
-    // IsochronousTransferInfo.
-    // |callback|: Invoked once the transfer has been completed.
+    // |handle|: An open connection to the device.
     static void isochronousTransfer(ConnectionHandle handle,
                                     IsochronousTransferInfo transferInfo,
                                     TransferCallback callback);
 
-    // Tries to reset the USB device and restores it to the previous status.
+    // Try to reset the USB device.

[Ken Rockot(use gerrit already), 2014/09/02 21:25:38]

Please make the tense of these overview descriptions consistent (i.e., either
all "tries"/"performs" or "try"/"perform"). I forget which is standard.

[Reilly Grant (use Gerrit), 2014/09/02 22:03:35]

Done. Function comments are descriptive.

     // If the reset fails, the given connection handle will be closed and the 
     // USB device will appear to be disconnected then reconnected. 
-    // In that case you must call |getDevices| or |findDevices| again to acquire
-    // the device.
+    // In this case $(ref:getDevices) or $(ref:findDevices) must be called again
+    // to acquire the device.
     //
     // |handle|: A connection handle to reset.
-    // |callback|: Invoked once the device is reset with a boolean indicating
-    // whether the reset is completed successfully.
     static void resetDevice(ConnectionHandle handle,
                             ResetDeviceCallback callback);
   };