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. 12namespace 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 }; 35 36 dictionary ConnectionHandle { 37 // An opaque handle representing this connection to the USB device and all 38 // associated claimed interfaces and pending transfers. A new handle is 39 // created each time the device is opened. The connection handle is 40 // different from $(ref:Device.device). 41 long handle; 42 // The device vendor ID. 43 long vendorId; 44 // The product ID. 45 long productId; 46 }; 47 48 [noinline_doc] dictionary EndpointDescriptor { 49 // Endpoint address. 50 long address; 51 // Transfer type. 52 TransferType type; 53 // Transfer direction. 54 Direction direction; 55 // Maximum packet size. 56 long maximumPacketSize; 57 // Transfer synchronization mode (isochronous only). 58 SynchronizationType? synchronization; 59 // Endpoint usage hint. 60 UsageType? usage; 61 // Polling interval (interrupt and isochronous only). 62 long? pollingInterval; 63 // Extra descriptor data associated with this endpoint. 64 ArrayBuffer extra_data; 65 }; 66 67 [noinline_doc] dictionary InterfaceDescriptor { 68 // The interface number. 69 long interfaceNumber; 70 // The interface alternate setting number (defaults to <code>0</code). 71 long alternateSetting; 72 // The USB interface class. 73 long interfaceClass; 74 // The USB interface sub-class. 75 long interfaceSubclass; 76 // The USB interface protocol. 77 long interfaceProtocol; 78 // Description of the interface. 79 DOMString? description; 80 // Available endpoints. 81 EndpointDescriptor[] endpoints; 82 // Extra descriptor data associated with this interface. 83 ArrayBuffer extra_data; 84 }; 85 86 [noinline_doc] dictionary ConfigDescriptor { 87 // The configuration number. 88 long configurationValue; 89 // Description of the configuration. 90 DOMString? description; 91 // The device is self-powered. 92 boolean selfPowered; 93 // The device supports remote wakeup. 94 boolean remoteWakeup; 95 // The maximum power needed by this device in milliamps (mA). 96 long maxPower; 97 // Available interfaces. 98 InterfaceDescriptor[] interfaces; 99 // Extra descriptor data associated with this configuration. 100 ArrayBuffer extra_data; 101 }; 102 103 dictionary ControlTransferInfo { 104 // The transfer direction (<code>"in"</code> or <code>"out"</code>). 105 Direction direction; 106 107 // The transfer target. The target given by <code>index</code> must be 108 // claimed if <code>"interface"</code> or <code>"endpoint"</code>. 109 Recipient recipient; 110 111 // The request type. 112 RequestType requestType; 113 114 // The <code>bRequest</code> field, see <i>Universal Serial Bus Specification 115 // Revision 1.1</i> § 9.3. 116 long request; 117 // The <code>wValue</code> field, see <i>Ibid</i>. 118 long value; 119 // The <code>wIndex</code> field, see <i>Ibid</i>. 120 long index; 121 122 // The amount of data to receive (required only by input transfers). 123 long? length; 124 125 // The data to transmit (required only by output transfers). 126 ArrayBuffer? data; 127 }; 128 129 dictionary GenericTransferInfo { 130 // The transfer direction (<code>"in"</code> or <code>"out"</code>). 131 Direction direction; 132 133 // The target endpoint address. The interface containing this endpoint must 134 // be claimed. 135 long endpoint; 136 137 // The amount of data to receive (required only by input transfers). 138 long? length; 139 140 // The data to transmit (required only by output transfers). 141 ArrayBuffer? data; 142 }; 143 144 dictionary IsochronousTransferInfo { 145 // Transfer parameters. The transfer length or data buffer specified in this 146 // parameter block is split along <code>packetLength</code> boundaries to 147 // form the individual packets of the transfer. 148 GenericTransferInfo transferInfo; 149 150 // The total number of packets in this transfer. 151 long packets; 152 153 // The length of each of the packets in this transfer. 154 long packetLength; 155 }; 156 157 dictionary TransferResultInfo { 158 // A value of <code>0</code> indicates that the transfer was a success. 159 // Other values indicate failure. 160 long? resultCode; 161 162 // The data returned by an input transfer. <code>undefined</code> for output 163 // transfers. 164 ArrayBuffer? data; 165 }; 166 167 [noinline_doc] dictionary DeviceFilter { 168 // Device vendor ID. 169 long? vendorId; 170 // Device product ID, checked only if the vendor ID matches. 171 long? productId; 172 // USB interface class, matches any interface on the device. 173 long? interfaceClass; 174 // USB interface sub-class, checked only if the interface class matches. 175 long? interfaceSubclass; 176 // USB interface protocol, checked only if the interface sub-class matches. 177 long? interfaceProtocol; 178 }; 179 180 dictionary EnumerateDevicesOptions { 181 [deprecated="Equivalent to setting $(ref:DeviceFilter.vendorId)."] 182 long? vendorId; 183 [deprecated="Equivalent to setting $(ref:DeviceFilter.productId)."] 184 long? productId; 185 // A device matching any given filter will be returned. An empty filter list 186 // will return all devices the app has permission for. 187 DeviceFilter[]? filters; 188 }; 189 190 dictionary EnumerateDevicesAndRequestAccessOptions { 191 // The device vendor ID. 192 long vendorId; 193 // The product ID. 194 long productId; 195 // The interface ID to request access to. 196 // Only available on ChromeOS. It has no effect on other platforms. 197 long? interfaceId; 198 }; 199 200 callback VoidCallback = void (); 201 callback GetDevicesCallback = void (Device[] devices); 202 callback RequestAccessCallback = void (boolean success); 203 callback OpenDeviceCallback = void (ConnectionHandle handle); 204 callback FindDevicesCallback = void (ConnectionHandle[] handles); 205 callback GetConfigurationCallback = void (ConfigDescriptor config); 206 callback ListInterfacesCallback = void (InterfaceDescriptor[] descriptors); 207 callback CloseDeviceCallback = void (); 208 callback TransferCallback = void (TransferResultInfo info); 209 callback ResetDeviceCallback = void(boolean success); 210 211 interface Functions { 212 // Enumerates connected USB devices. 213 // |options|: The properties to search for on target devices. 214 static void getDevices(EnumerateDevicesOptions options, 215 GetDevicesCallback callback); 216 217 // Requests access from the permission broker to a device claimed by 218 // ChromeOS if the given interface on the device is not claimed. 219 // 220 // <b>Note:</b> This method is ChromeOS specific. Calling this method on 221 // other platforms will fail. 222 // 223 // |device|: The $(ref:Device) to request access to. 224 // |interfaceId|: The particular interface requested. 225 static void requestAccess(Device device, 226 long interfaceId, 227 RequestAccessCallback callback); 228 229 // Opens a USB device returned by $(ref:getDevices). 230 // |device|: The $(ref:Device) to open. 231 static void openDevice(Device device, OpenDeviceCallback callback); 232 233 // Finds USB devices specified by the vendor, product and (optionally) 234 // interface IDs and if permissions allow opens them for use. 235 // 236 // On Chrome OS, you can specify the interface ID. In that case the method 237 // will request access from permission broker in the same way as 238 // $(ref:requestAccess). 239 // 240 // If the access request is rejected or the device fails to be opened a 241 // connection handle will not be created or returned. 242 // 243 // Calling this method is equivalent to calling $(ref:getDevices followed by 244 // $(ref:requestAccess) (if it is on ChromeOS) and $(ref:openDevice) for 245 // each device. 246 // 247 // |options|: The properties to search for on target devices. 248 static void findDevices(EnumerateDevicesAndRequestAccessOptions options, 249 FindDevicesCallback callback); 250 251 // Closes a connection handle. Invoking operations on a handle after it 252 // has been closed is a safe operation but causes no action to be taken. 253 // |handle|: The $(ref:ConnectionHandle) to close. 254 static void closeDevice(ConnectionHandle handle, 255 optional CloseDeviceCallback callback); 256 257 // Gets the configuration descriptor for the currently selected 258 // configuration. 259 // |handle|: An open connection to the device. 260 static void getConfiguration(ConnectionHandle handle, 261 GetConfigurationCallback callback); 262 263 // Lists all interfaces on a USB device. 264 // |handle|: An open connection to the device. 265 static void listInterfaces(ConnectionHandle handle, 266 ListInterfacesCallback callback); 267 268 // Claims an interface on a USB device. 269 // Before data can be transfered to an interface or associated endpoints the 270 // interface must be claimed. Only one connection handle can claim an 271 // interface at any given time. If the interface is already claimed, this 272 // call will fail. 273 // 274 // $(ref:releaseInterface) should be called when the interface is no longer 275 // needed. 276 // 277 // |handle|: An open connection to the device. 278 // |interfaceNumber|: The interface to be claimed. 279 static void claimInterface(ConnectionHandle handle, long interfaceNumber, 280 VoidCallback callback); 281 282 // Releases a claimed interface. 283 // |handle|: An open connection to the device. 284 // |interfaceNumber|: The interface to be released. 285 static void releaseInterface(ConnectionHandle handle, long interfaceNumber, 286 VoidCallback callback); 287 288 // Selects an alternate setting on a previously claimed interface. 289 // |handle|: An open connection to the device where this interface has been 290 // claimed. 291 // |interfaceNumber|: The interface to configure. 292 // |alternateSetting|: The alternate setting to configure. 293 static void setInterfaceAlternateSetting(ConnectionHandle handle, 294 long interfaceNumber, 295 long alternateSetting, 296 VoidCallback callback); 297 298 // Performs a control transfer on the specified device. 299 // 300 // Control transfers refer to either the device, an interface or an 301 // endpoint. Transfers to an interface or endpoint require the interface to 302 // be claimed. 303 // 304 // |handle|: An open connection to the device. 305 static void controlTransfer(ConnectionHandle handle, 306 ControlTransferInfo transferInfo, 307 TransferCallback callback); 308 309 // Performs a bulk transfer on the specified device. 310 // |handle|: An open connection to the device. 311 // |transferInfo|: The transfer parameters. 312 static void bulkTransfer(ConnectionHandle handle, 313 GenericTransferInfo transferInfo, 314 TransferCallback callback); 315 316 // Performs an interrupt transfer on the specified device. 317 // |handle|: An open connection to the device. 318 // |transferInfo|: The transfer parameters. 319 static void interruptTransfer(ConnectionHandle handle, 320 GenericTransferInfo transferInfo, 321 TransferCallback callback); 322 323 // Performs an isochronous transfer on the specific device. 324 // |handle|: An open connection to the device. 325 static void isochronousTransfer(ConnectionHandle handle, 326 IsochronousTransferInfo transferInfo, 327 TransferCallback callback); 328 329 // Tries to reset the USB device. 330 // If the reset fails, the given connection handle will be closed and the 331 // USB device will appear to be disconnected then reconnected. 332 // In this case $(ref:getDevices) or $(ref:findDevices) must be called again 333 // to acquire the device. 334 // 335 // |handle|: A connection handle to reset. 336 static void resetDevice(ConnectionHandle handle, 337 ResetDeviceCallback callback); 338 }; 339}; 340