diff options
Diffstat (limited to 'chromium/extensions/common/api/usb.idl')
| -rw-r--r-- | chromium/extensions/common/api/usb.idl | 403 |
1 files changed, 403 insertions, 0 deletions
diff --git a/chromium/extensions/common/api/usb.idl b/chromium/extensions/common/api/usb.idl new file mode 100644 index 00000000000..f0d42eb8de5 --- /dev/null +++ b/chromium/extensions/common/api/usb.idl @@ -0,0 +1,403 @@ +// Copyright 2014 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. + +// 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 + // namesakes within the USB specification. + enum Direction {in, out}; + enum Recipient {device, _interface, endpoint, other}; + enum RequestType {standard, class, vendor, reserved}; + enum TransferType {control, interrupt, isochronous, bulk}; + + // For isochronous mode, SynchronizationType and UsageType map to their + // namesakes within the USB specification. + enum SynchronizationType {asynchronous, adaptive, synchronous}; + enum UsageType {data, feedback, explicitFeedback}; + + dictionary Device { + // 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; + // The device version (bcdDevice field). + long version; + // The iProduct string read from the device, if available. + DOMString productName; + // The iManufacturer string read from the device, if available. + DOMString manufacturerName; + // The iSerialNumber string read from the device, if available. + DOMString serialNumber; + }; + + dictionary ConnectionHandle { + // 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; + }; + + [noinline_doc] dictionary EndpointDescriptor { + // Endpoint address. + long address; + // Transfer type. + TransferType type; + // Transfer direction. + Direction direction; + // Maximum packet size. + long maximumPacketSize; + // Transfer synchronization mode (isochronous only). + SynchronizationType? synchronization; + // Endpoint usage hint. + UsageType? usage; + // Polling interval (interrupt and isochronous only). + long? pollingInterval; + // Extra descriptor data associated with this endpoint. + ArrayBuffer extra_data; + }; + + [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; + // Extra descriptor data associated with this interface. + ArrayBuffer extra_data; + }; + + [noinline_doc] dictionary ConfigDescriptor { + // Is this the active configuration? + boolean active; + // The configuration number. + long configurationValue; + // Description of the configuration. + DOMString? description; + // The device is self-powered. + boolean selfPowered; + // The device supports remote wakeup. + boolean remoteWakeup; + // The maximum power needed by this device in milliamps (mA). + long maxPower; + // Available interfaces. + InterfaceDescriptor[] interfaces; + // Extra descriptor data associated with this configuration. + ArrayBuffer extra_data; + }; + + dictionary ControlTransferInfo { + // The transfer direction (<code>"in"</code> or <code>"out"</code>). + Direction direction; + + // The transfer target. The target given by <code>index</code> must be + // claimed if <code>"interface"</code> or <code>"endpoint"</code>. + Recipient recipient; + + // The request type. + RequestType requestType; + + // The <code>bRequest</code> field, see <i>Universal Serial Bus + // Specification Revision 1.1</i> § 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; + + // The maximum number of bytes to receive (required only by input + // transfers). + long? length; + + // The data to transmit (required only by output transfers). + ArrayBuffer? data; + + // Request timeout (in milliseconds). The default value <code>0</code> + // indicates no timeout. + long? timeout; + }; + + dictionary GenericTransferInfo { + // 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; + + // The maximum number of bytes to receive (required only by input + // transfers). + long? length; + + // The data to transmit (required only by output transfers). + ArrayBuffer? data; + + // Request timeout (in milliseconds). The default value <code>0</code> + // indicates no timeout. + long? timeout; + }; + + dictionary IsochronousTransferInfo { + // 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. + long packets; + + // The length of each of the packets in this transfer. + long packetLength; + }; + + dictionary TransferResultInfo { + // A value of <code>0</code> indicates that the transfer was a success. + // Other values indicate failure. + long? resultCode; + + // The data returned by an input transfer. <code>undefined</code> for output + // transfers. + ArrayBuffer? data; + }; + + [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 { + [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; + }; + + dictionary EnumerateDevicesAndRequestAccessOptions { + // The device vendor ID. + long vendorId; + // The product ID. + long productId; + // The interface ID to request access to. + // Only available on Chrome OS. It has no effect on other platforms. + long? interfaceId; + }; + + dictionary DevicePromptOptions { + // Allow the user to select multiple devices. + boolean? multiple; + // Filter the list of devices presented to the user. If multiple filters are + // provided devices matching any filter will be displayed. + DeviceFilter[]? filters; + }; + + callback VoidCallback = void (); + callback GetDevicesCallback = void (Device[] devices); + callback GetConfigurationsCallback = void (ConfigDescriptor[] configs); + callback RequestAccessCallback = void (boolean success); + callback OpenDeviceCallback = void (ConnectionHandle handle); + callback FindDevicesCallback = void (ConnectionHandle[] handles); + callback GetConfigurationCallback = void (ConfigDescriptor config); + callback ListInterfacesCallback = void (InterfaceDescriptor[] descriptors); + callback CloseDeviceCallback = void (); + callback TransferCallback = void (TransferResultInfo info); + callback ResetDeviceCallback = void(boolean success); + + interface Functions { + // Enumerates connected USB devices. + // |options|: The properties to search for on target devices. + static void getDevices(EnumerateDevicesOptions options, + GetDevicesCallback callback); + + // Presents a device picker to the user and returns the $(ref:Device)s + // selected. + // If the user cancels the picker devices will be empty. A user gesture + // is required for the dialog to display. Without a user gesture, the + // callback will run as though the user cancelled. + // |options|: Configuration of the device picker dialog box. + // |callback|: Invoked with a list of chosen $(ref:Device)s. + static void getUserSelectedDevices(DevicePromptOptions options, + GetDevicesCallback callback); + + // Returns the full set of device configuration descriptors. + // |device|: The $(ref:Device) to fetch descriptors from. + static void getConfigurations(Device device, + GetConfigurationsCallback callback); + + // Requests access from the permission broker to a device claimed by + // Chrome OS if the given interface on the device is not claimed. + // + // |device|: The $(ref:Device) to request access to. + // |interfaceId|: The particular interface requested. + [deprecated="This function was Chrome OS specific and calling it on other + platforms would fail. This operation is now implicitly performed as part of + $(ref:openDevice) and this function will return <code>true</code> on all + platforms."] + static void requestAccess(Device device, + long interfaceId, + RequestAccessCallback callback); + + // 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 vendor, product and (optionally) + // interface IDs and if permissions allow opens them for use. + // + // 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 $(ref:getDevices) followed + // by $(ref:openDevice) for each device. + // + // |options|: The properties to search for on target devices. + static void findDevices(EnumerateDevicesAndRequestAccessOptions options, + FindDevicesCallback callback); + + // 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); + + // Select a device configuration. + // + // This function effectively resets the device by selecting one of the + // device's available configurations. Only configuration values greater + // than <code>0</code> are valid however some buggy devices have a working + // configuration <code>0</code> and so this value is allowed. + // |handle|: An open connection to the device. + static void setConfiguration(ConnectionHandle handle, + long configurationValue, + VoidCallback callback); + + // Gets the configuration descriptor for the currently selected + // configuration. + // |handle|: An open connection to the device. + static void getConfiguration(ConnectionHandle handle, + GetConfigurationCallback callback); + + // 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 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. + // + // $(ref:releaseInterface) should be called when the interface is no longer + // needed. + // + // |handle|: An open connection to the device. + // |interfaceNumber|: The interface to be claimed. + static void claimInterface(ConnectionHandle handle, long interfaceNumber, + VoidCallback callback); + + // 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. + // |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. + // + // 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|: An open connection to the device. + static void controlTransfer(ConnectionHandle handle, + ControlTransferInfo transferInfo, + TransferCallback callback); + + // Performs a bulk transfer on the specified device. + // |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|: 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|: An open connection to the device. + static void isochronousTransfer(ConnectionHandle handle, + IsochronousTransferInfo transferInfo, + TransferCallback callback); + + // Tries to reset the USB device. + // If the reset fails, the given connection handle will be closed and the + // USB device will appear to be disconnected then reconnected. + // In this case $(ref:getDevices) or $(ref:findDevices) must be called again + // to acquire the device. + // + // |handle|: A connection handle to reset. + static void resetDevice(ConnectionHandle handle, + ResetDeviceCallback callback); + }; + + interface Events { + // Event generated when a device is added to the system. Events are only + // broadcast to apps and extensions that have permission to access the + // device. Permission may have been granted at install time, when the user + // accepted an optional permission (see $(ref:permissions.request)), or + // through $(ref:getUserSelectedDevices). + static void onDeviceAdded(Device device); + + // Event generated when a device is removed from the system. See + // $(ref:onDeviceAdded) for which events are delivered. + static void onDeviceRemoved(Device device); + }; +}; |