Experimental USB API

chrome/common/extensions/api/experimental.usb.idl

Index: chrome/common/extensions/api/experimental.usb.idl
diff --git a/chrome/common/extensions/api/experimental.usb.idl b/chrome/common/extensions/api/experimental.usb.idl
new file mode 100644
index 0000000000000000000000000000000000000000..4912b9331a3c762eb6676fe87ba36cb83fdb993b
--- /dev/null
+++ b/chrome/common/extensions/api/experimental.usb.idl
@@ -0,0 +1,134 @@
+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// TODO(gdk): The string-style enumerations are temporary, and will be removed
+// once full enumeration support is added. Also, the array-of-longs are
+// temporary and will be removed once there is full ArrayBuffer support.
+
+[nodoc] namespace experimental.usb {
+
+  // A Device encapsulates everything that is needed to communicate with a USB
+  // device. They are returned by findDevice calls and have all of their
+  // fields populated before being returned.
+  dictionary Device {
+    long handle;
+    long vendorId;
+    long productId;
+  };
+
+  // ControlTransferInfo represents that parameters to a single USB control
+  // transfer.
+  dictionary ControlTransferInfo {
+    // The direction of this transfer. Must be one of either in or out.
+    DOMString direction;

[miket_OOO, 2012/04/25 23:10:37]

A little vertical whitespace would be helpful for readability.

[Garret Kelly, 2012/04/26 20:13:44]

Done.

+    // The intended recipient for this transfer. Must be one of device,
+    // interface, endpoint, or other.
+    DOMString recipient;
+    // The type of this request. Must be one of standard, class, vendor,
+    // or reserved.
+    DOMString requestType;
+    long request;
+    long value;
+    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.
+    long? length;
+    long[]? data;
+  };
+
+  // GenericTransferInfo is used by both bulk and interrupt transfers to
+  // specify the parameters of the transfer.
+  dictionary GenericTransferInfo {
+    // The direction of this transfer. Must be one of in or out.
+    DOMString direction;
+    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.
+    long? length;
+    Blob? data;
+    // If this is an output transfer then this field must be populated.
+    // Otherwise, it will be ignored.
+    long[]? data;
+  };
+
+  // When a USB event occurs the event handler specified in findDevice will

[asargent_no_longer_on_chrome, 2012/04/26 21:21:45]

Can you clarify here that it's the onEvent property of the DeviceOptions
parameter to findDevice? (I was initially confused that it might be the
FindDeviceCallback)

[Garret Kelly, 2012/04/27 00:32:34]

Done.

+  // have a UsbEvent delivered to it which will contain the result of a
+  // trasnsfer, including returned data.

[miket_OOO, 2012/04/25 23:10:37]

spelling

[Garret Kelly, 2012/04/26 20:13:44]

Done.

+  dictionary UsbEvent {
+    // A string indicating the type of the event. Currently will only contain
+    // the value 'transferResult'.
+    DOMString type;
+    // A value of 1 indicates that the transfer was a success. Other values

[miket_OOO, 2012/04/25 23:10:37]

This feels nonstandard. Could zero indicate success instead, so that a boolean
test can distinguish success from failure? Push back if I'm misunderstanding
your model.

[Garret Kelly, 2012/04/26 20:13:44]

Done.

+    // indicate faliure.

[miket_OOO, 2012/04/25 23:10:37]

spelling

[Garret Kelly, 2012/04/26 20:13:44]

Done.

+    long? resultCode;
+    // If the transfer was an input transfer then this field will contain all
+    // of the input data requested.
+    long[]? data;
+
+    // The following fields are used for internal event routing and can be
+    // ignored.
+    [nodoc] boolean isFinalEvent;
+    [nodoc] long srcId;
+  };
+
+  callback OnEventCallback = void (UsbEvent event);
+
+  dictionary DeviceOptions {
+    // The schema generator does not support dictionaries with only events.
+    // Ignore this field.
+    [nodoc] long? dummyValue;
+    // Invoked by the extension API whenever an event occurs the device(s)

[miket_OOO, 2012/04/25 23:10:37]

occurs for? with?

[Garret Kelly, 2012/04/26 20:13:44]

Done.

+    // that this DeviceOptions is associated with.
+    OnEventCallback? onEvent;
+  };
+
+  callback FindDeviceCallback = void (optional Device device);
+  callback TransferCallback = void ();
+
+  interface Functions {
+    // Finds the first instance of the USB device specified by the vendorId/
+    // productId pair and, if permissions allow, opens it for use.
+    // If the device is successfully opened, invokes the provided callback with
+    // the Device object.

[asargent_no_longer_on_chrome, 2012/04/26 21:21:45]

comment nit: The FindDeviceCallback should fire on either success or failure -
it's just that the device is null in the failure case.

[Garret Kelly, 2012/04/27 00:32:34]

Quite right. It actually does, and this comment is incorrect. Fixed!

+    // |vendorId|: The vendor ID of the USB device to find.
+    // |productId|: The product ID of the USB device to find.
+    // |callback|: Invoked with the opened Device on success.
+    static void findDevice(long vendorId, long productId,
+        DeviceOptions options, FindDeviceCallback callback);
+
+    // Closes an open device instance. Invoking operations on a device after it
+    // has been closed is a safe operation, but causes no action to be taken.
+    // |device|: The device to close. 
+    static void closeDevice(Device device);
+
+    // Performs a control transfer on the specified device. See the
+    // ControlTransferInfo structure for the parameters required to make a
+    // transfer.
+    // |device|: An open device to make the transfer on.
+    // |transferInfo|: The parameters to the transfer. See ControlTransferInfo.
+    // |callback|: Invoked once the transfer has completed.
+    static void controlTransfer(Device device,
+        ControlTransferInfo transferInfo, optional TransferCallback callback);
+
+    // Performs a bulk transfer on the specified device.
+    // |device|: An open device to make the transfer on.
+    // |transferInfo|: The paramters to the transfer. See GenericTransferInfo.
+    // |callback|: Invoked once the transfer has completed.
+    static void bulkTransfer(Device device, GenericTransferInfo transferInfo,
+        optional TransferCallback callback);
+
+    // Performs a control transfer on the specified device.

[asargent_no_longer_on_chrome, 2012/04/26 21:21:45]

nit: Should this say "Performs an interrupt transfer ..." ?

[Garret Kelly, 2012/04/27 00:32:34]

D'oh! Done.

+    // |device|: An open device to make the transfer on.
+    // |transferInfo|: The paramters to the transfer. See GenericTransferInfo.
+    // |callback|: Invoked once the transfer has completed.
+    static void interruptTransfer(Device device,
+        GenericTransferInfo transferInfo, optional TransferCallback callback);
+  };
+
+  interface Events {
+    static void onEvent(UsbEvent event);
+  };
+
+};