chrome.usb

说明

使用 chrome.usb API 与已连接的 USB 设备互动。此 API 可在应用上下文中提供对 USB 操作的访问权限。借助此 API，应用可以充当硬件设备的驱动程序。此 API 生成的错误通过设置 runtime.lastError 并执行函数的常规回调来报告。在这种情况下，回调的常规参数将处于未定义状态。

权限

usb

可用性

仅限 ChromeOS

类型

ConfigDescriptor

属性

  • 活跃

    布尔值

    Chrome 47 及更高版本

    相应配置是否处于有效状态？

  • configurationValue

    数值

    配置编号。

  • 说明

    字符串 可选

    配置的说明。

  • extra_data

    ArrayBuffer

    与此配置相关联的额外描述符数据。

  • 接口

    InterfaceDescriptorInterfaceDescriptor[]

    可用的界面。

  • maxPower

    数值

    相应设备所需的最大功率（以毫安 [mA] 为单位）。

  • remoteWakeup

    布尔值

    设备支持远程唤醒。

  • selfPowered

    布尔值

    设备由自身供电。

ConnectionHandle

属性

  • 句柄

    数值

    一个不透明的句柄，用于表示与 USB 设备的连接以及所有关联的已声明接口和待处理的传输。每次打开设备时，系统都会创建一个新的句柄。连接句柄与 Device.device 不同。

  • productId

    数值

    商品 ID。

  • vendorId

    数值

    设备供应商 ID。

ControlTransferInfo

属性

  • 数据

    ArrayBuffer 可选

    要传输的数据（仅输出传输需要）。

  • 方向

    方向

    转移方向（"in" 或 "out"）。

  • 索引

    数值

    wIndex 字段，请参阅 Ibid。

  • 长度

    number 可选

    要接收的字节数上限（仅输入转移需要）。

  • 收件人

    收件人

    转移目标。如果值为 "interface" 或 "endpoint"，则必须声明 index 给定的目标。

  • request

    数值

    bRequest 字段，请参阅《通用串行总线规范修订版 1.1》第 9.3 节。

  • requestType

    RequestType

    请求类型。

  • 超时

    number 可选

    Chrome 43 及更高版本

    请求超时时间（以毫秒为单位）。默认值 0 表示无超时。

  • 值

    数值

    wValue 字段，请参阅 Ibid。

Device

属性

  • 设备

    数值

    USB 设备的不透明 ID。在设备拔下之前，该设置保持不变。

  • manufacturerName

    字符串

    Chrome 46 及更高版本

    从设备读取的 iManufacturer 字符串（如有）。

  • productId

    数值

    商品 ID。

  • productName

    字符串

    Chrome 46 及更高版本

    从设备读取的 iProduct 字符串（如果有）。

  • serialNumber

    字符串

    Chrome 46 及更高版本

    从设备读取的 iSerialNumber 字符串（如有）。

  • vendorId

    数值

    设备供应商 ID。

  • 版本

    数值

    Chrome 51 及更高版本

    设备版本（bcdDevice 字段）。

DeviceFilter

属性

  • interfaceClass

    number 可选

    USB 接口类，与设备上的任何接口匹配。

  • interfaceProtocol

    number 可选

    USB 接口协议，仅在接口子类匹配时检查。

  • interfaceSubclass

    number 可选

    USB 接口子类，仅在接口类匹配时检查。

  • productId

    number 可选

    设备产品 ID，仅在供应商 ID 匹配时进行检查。

  • vendorId

    number 可选

    设备供应商 ID。

DevicePromptOptions

属性

  • 过滤器

    DeviceFilter[] 可选

    过滤向用户显示的设备列表。如果提供了多个过滤条件，系统将显示与任何过滤条件匹配的设备。

  • 多个

    布尔值 （可选）

    允许用户选择多个设备。

Direction

Direction、Recipient、RequestType 和 TransferType 都映射到 USB 规范中的同名属性。

枚举

"in"

"out"

EndpointDescriptor

属性

  • 地址

    数值

    端点地址。

  • 方向

    方向

    转移方向。

  • extra_data

    ArrayBuffer

    与此端点关联的额外描述符数据。

  • maximumPacketSize

    数值

    数据包大小上限。

  • pollingInterval

    number 可选

    轮询间隔（仅限中断和等时）。

  • 同步

    SynchronizationType 可选

    传输同步模式（仅限等时）。

  • 类型

    TransferType

    转移类型。

  • 使用量

    UsageType（可选）

    端点使用情况提示。

EnumerateDevicesAndRequestAccessOptions

属性

  • interfaceId

    number 可选

    要请求访问权限的接口 ID。仅适用于 ChromeOS。对其他平台没有影响。

  • productId

    数值

    商品 ID。

  • vendorId

    数值

    设备供应商 ID。

EnumerateDevicesOptions

属性

  • 过滤器

    DeviceFilter[] 可选

    系统将返回与任何给定过滤条件匹配的设备。如果过滤条件列表为空，则会返回应用有权访问的所有设备。

  • productId

    number 可选

    已弃用

    相当于设置 DeviceFilter.productId。

  • vendorId

    number 可选

    已弃用

    相当于设置 DeviceFilter.vendorId。

GenericTransferInfo

属性

  • 数据

    ArrayBuffer 可选

    要传输的数据（仅输出传输需要）。

  • 方向

    方向

    转移方向（"in" 或 "out"）。

  • endpoint

    数值

    目标端点地址。包含此端点的接口必须已声明。

  • 长度

    number 可选

    要接收的字节数上限（仅输入转移需要）。

  • 超时

    number 可选

    Chrome 43 及更高版本

    请求超时时间（以毫秒为单位）。默认值 0 表示无超时。

InterfaceDescriptor

属性

  • alternateSetting

    数值

    接口替代设置编号（默认为 0

  • 说明

    字符串 可选

    界面说明。

  • endpoints

    EndpointDescriptorEndpointDescriptor[]

    可用的端点。

  • extra_data

    ArrayBuffer

    与此接口关联的额外描述符数据。

  • interfaceClass

    数值

    USB 接口类。

  • interfaceNumber

    数值

    接口编号。

  • interfaceProtocol

    数值

    USB 接口协议。

  • interfaceSubclass

    数值

    USB 接口子类。

IsochronousTransferInfo

属性

  • packetLength

    数值

    相应转移中每个数据包的长度。

  • 数据包

    数值

    相应转移中的数据包总数。

  • transferInfo

    GenericTransferInfo

    转移参数。此形参块中指定的转移长度或数据缓冲区沿 packetLength 边界拆分，以形成转移的各个数据包。

Recipient

枚举

"device"

"interface"

“endpoint”

"other"

RequestType

枚举

"standard"

“class”

“供应商”

“reserved”

SynchronizationType

对于中断模式和同步模式，SynchronizationType 和 UsageType 会映射到 USB 规范中的同名属性。

枚举

“异步”

"adaptive"

"synchronous"

TransferResultInfo

属性

  • 数据

    ArrayBuffer 可选

    输入转移返回的数据。undefined（用于输出转移）。

  • resultCode

    number 可选

    值 0 表示转移成功。其他值表示失败。

TransferType

枚举

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

枚举

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

方法

bulkTransfer()

Promise 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

在指定设备上执行批量转移。

参数

返回

  • Chrome 116 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

claimInterface()

Promise 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
): Promise<void>

声明 USB 设备上的接口。在将数据传输到接口或关联的端点之前，必须先声明接口。在任何给定时间，只能有一个连接句柄声明接口。如果接口已被声明，则此调用将失败。

当不再需要相应接口时，应调用 releaseInterface。

参数

  • 与设备的开放连接。

  • interfaceNumber

    数值

    要声明的接口。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 116 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

closeDevice()

Promise 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
): Promise<void>

关闭连接句柄。在句柄关闭后对其调用操作是安全的操作，但不会导致采取任何操作。

参数

返回

  • Promise<void>

    Chrome 116 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

controlTransfer()

Promise 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

在指定设备上执行控制传输。

控制传输是指传输到设备、接口或端点。转移到接口或端点需要声明接口。

参数

返回

  • Chrome 116 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

findDevices()

Promise 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
): Promise<ConnectionHandle[]>

查找由供应商、产品和（可选）接口 ID 指定的 USB 设备，并在权限允许的情况下打开这些设备以供使用。

如果访问请求被拒绝或设备无法打开，则不会创建或返回连接句柄。

调用此方法等同于先针对每个设备调用 getDevices，然后再调用 openDevice。

参数

返回

  • Promise<ConnectionHandle[]>

    Chrome 116 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getConfiguration()

Promise 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
): Promise<ConfigDescriptor>

获取当前所选配置的配置描述符。

参数

返回

  • Chrome 116 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getConfigurations()

Promise Chrome 47 及更高版本 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

返回完整的设备配置描述符集。

参数

返回

  • Promise<ConfigDescriptor[]>

    Chrome 116 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getDevices()

Promise 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
): Promise<Device[]>

枚举已连接的 USB 设备。

参数

  • 要在目标设备上搜索的属性。

  • callback

    函数 可选

    callback 参数如下所示： 

    (devices: Device[]) => void