chrome.usb

Важно! Этот API работает только в ChromeOS.

Описание

Используйте API chrome.usb для взаимодействия с подключенными USB-устройствами. Этот API предоставляет доступ к операциям USB в контексте приложения. С помощью этого API приложения могут работать как драйверы для аппаратных устройств. Ошибки, созданные этим API, регистрируются путем настройки runtime.lastError и выполнения обычного обратного вызова функции. В этом случае обычные параметры обратного вызова не будут определены.

Разрешения

usb

Доступность

Только для ChromeOS

Типы

ConfigDescriptor

Свойства

• активно

  Логическое значение

  Chrome 47 и более поздних версий;

  Это активная конфигурация?

• configurationValue

  число

  Номер конфигурации.

• описание

  Строка (необязательно)

  Описание конфигурации.

• extra_data

  ArrayBuffer

  Дополнительные данные дескриптора, связанные с этой конфигурацией.

• интерфейсы

  InterfaceDescriptor[]

  Доступные интерфейсы.

• maxPower

  число

  Максимальная мощность, необходимая для работы устройства, в миллиамперах (мА).

• remoteWakeup

  Логическое значение

  Устройство поддерживает удаленное пробуждение.

• selfPowered

  Логическое значение

  Устройство имеет собственный источник питания.

ConnectionHandle

Свойства

• дескриптор

  число

  Непрозрачный дескриптор, представляющий это подключение к USB-устройству и все связанные с ним заявленные интерфейсы и ожидающие передачи. Новый дескриптор создается каждый раз, когда устройство открывается. Идентификатор подключения отличается от Device.device.

• идентификаторТовара

  число

  Идентификатор товара.

• vendorId

  число

  Идентификатор поставщика устройства.

ControlTransferInfo

Свойства

• делал.

  ArrayBuffer (необязательно)

  Данные для передачи (требуются только для исходящих передач).

• direction

  Направление

  Направление переноса ("in" или "out").

• индекс

  число

  Поле wIndex. См. Ibid.

• длина

  number (необязательно)

  Максимальное количество байтов, которое можно получить (требуется только для входящих передач).

• получатель

  Recipient

  Целевой объект переноса. Целевой ресурс, указанный в index, должен быть заявлен, если "interface" или "endpoint".

• запрос

  число

  Поле bRequest. См. спецификацию универсальной последовательной шины, версия 1.1, раздел 9.3.

• requestType

  RequestType

  Тип запроса.

• Тайм-аут

  number (необязательно)

  Chrome 43 и более поздних версий;

  Время ожидания запроса (в миллисекундах). Значение по умолчанию 0 указывает на отсутствие времени ожидания.

• value

  число

  Поле wValue. См. Ibid.

Device

Свойства

• устройство

  число

  Непрозрачный идентификатор USB-устройства. Оно не изменится, пока устройство не будет отключено.

• manufacturerName

  string

  Chrome 46 и более поздних версий;

  Строка iManufacturer, считанная с устройства (если доступна).

• идентификаторТовара

  число

  Идентификатор товара.

• названиеТовара

  string

  Chrome 46 и более поздних версий;

  Строка iProduct, считанная с устройства (если доступна).

• serialNumber

  string

  Chrome 46 и более поздних версий;

  Строка iSerialNumber, считанная с устройства (если доступна).

• vendorId

  число

  Идентификатор поставщика устройства.

• version

  число

  Chrome 51 и более поздних версий;

  Версия устройства (поле bcdDevice).

DeviceFilter

Свойства

• interfaceClass

  number (необязательно)

  Класс интерфейса USB, соответствующий любому интерфейсу на устройстве.

• interfaceProtocol

  number (необязательно)

  Протокол интерфейса USB. Проверяется, только если подкласс интерфейса совпадает.

• interfaceSubclass

  number (необязательно)

  Подкласс интерфейса USB. Проверяется, только если класс интерфейса совпадает.

• идентификаторТовара

  number (необязательно)

  Идентификатор продукта устройства. Проверяется, только если совпадает идентификатор производителя.

• vendorId

  number (необязательно)

  Идентификатор поставщика устройства.

DevicePromptOptions

Свойства

• фильтры

  DeviceFilter[] необязательный

  Фильтровать список устройств, которые видит пользователь. Если указано несколько фильтров, будут показаны устройства, соответствующие любому из них.

• Несколько

  Логическое значение (необязательно)

  Пользователь может выбрать несколько устройств.

Direction

Direction, Recipient, RequestType и TransferType соответствуют одноименным параметрам в спецификации USB.

Перечисление

"in"

"out"

EndpointDescriptor

Свойства

• Обращаться (к определенному вопросу)

  число

  Адрес конечной точки.

• direction

  Направление

  Направление переноса.

• extra_data

  ArrayBuffer

  Дополнительные данные дескриптора, связанные с этой конечной точкой.

• maximumPacketSize

  число

  Максимальный размер пакета.

• pollingInterval

  number (необязательно)

  Интервал опроса (только для прерывания и изохронной передачи).

• синхронизация

  SynchronizationType необязательный

  Режим синхронизации передачи (только изохронный).

• тип

  TransferType

  Тип переноса.

• использование

  UsageType необязательный

  Подсказка по использованию конечной точки.

EnumerateDevicesAndRequestAccessOptions

Свойства

• interfaceId

  number (необязательно)

  Идентификатор интерфейса, к которому запрашивается доступ. Доступно только в ChromeOS. На другие платформы это не влияет.

• идентификаторТовара

  число

  Идентификатор товара.

• vendorId

  число

  Идентификатор поставщика устройства.

EnumerateDevicesOptions

Свойства

• фильтры

  DeviceFilter[] необязательный

  Будут возвращены устройства, соответствующие любому из заданных фильтров. Если список фильтров пуст, будут возвращены все устройства, для которых у приложения есть разрешение.

• идентификаторТовара

  number (необязательно)

  Поддержка прекращена

  Эквивалентно настройке DeviceFilter.productId.

• vendorId

  number (необязательно)

  Поддержка прекращена

  Эквивалентно настройке DeviceFilter.vendorId.

GenericTransferInfo

Свойства

• делал.

  ArrayBuffer (необязательно)

  Данные для передачи (требуются только для исходящих передач).

• direction

  Направление

  Направление переноса ("in" или "out").

• конечная точка

  число

  Адрес целевой конечной точки. Интерфейс, содержащий эту конечную точку, должен быть заявлен.

• длина

  number (необязательно)

  Максимальное количество байтов, которое можно получить (требуется только для входящих переносов).

• Тайм-аут

  number (необязательно)

  Chrome 43 и более поздних версий;

  Время ожидания запроса (в миллисекундах). Значение по умолчанию 0 указывает на отсутствие времени ожидания.

InterfaceDescriptor

Свойства

• alternateSetting

  число

  Номер альтернативной настройки интерфейса (по умолчанию 0

• описание

  Строка (необязательно)

  Описание интерфейса.

• конечные точки

  EndpointDescriptor[]

  Доступные конечные точки.

• extra_data

  ArrayBuffer

  Дополнительные данные дескриптора, связанные с этим интерфейсом.

• interfaceClass

  число

  Класс интерфейса USB.

• interfaceNumber

  число

  Номер интерфейса.

• interfaceProtocol

  число

  Протокол интерфейса USB.

• interfaceSubclass

  число

  Подкласс интерфейса USB.

IsochronousTransferInfo

Свойства

• packetLength

  число

  Длина каждого пакета в этой передаче.

• пакеты

  число

  Общее количество пакетов в этом запросе на перенос.

• transferInfo

  GenericTransferInfo

  Параметры переноса. Длина передачи или буфер данных, указанные в этом блоке параметров, разделяются по границам packetLength, чтобы сформировать отдельные пакеты передачи.

Recipient

Перечисление

"device"

"interface"

"endpoint"

"other"

RequestType

Перечисление

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

Для режимов прерывания и изохронного режима SynchronizationType и UsageType сопоставляются с одноименными параметрами в спецификации USB.

Перечисление

"asynchronous"

"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>

Выполняет массовую передачу данных на указанном устройстве.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• transferInfo

  GenericTransferInfo

  Параметры переноса.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (info: TransferResultInfo) => void

  • информация

    TransferResultInfo

Возвраты

• Promise<TransferResultInfo>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

claimInterface()

Promise

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

Запрашивает интерфейс на USB-устройстве. Прежде чем передавать данные в интерфейс или связанные конечные точки, необходимо заявить права на интерфейс. В каждый момент времени только один дескриптор подключения может запрашивать интерфейс. Если интерфейс уже занят, вызов не будет выполнен.

releaseInterface – вызывается, когда интерфейс больше не нужен.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• interfaceNumber

  число

  Интерфейс, который нужно запросить.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Promise<void>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

closeDevice()

Promise

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

Закрывает дескриптор подключения. Вызов операций с дескриптором после его закрытия безопасен, но не приводит к каким-либо действиям.

Параметры

• дескриптор

  ConnectionHandle

  ConnectionHandle, чтобы закрыть.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Promise<void>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

controlTransfer()

Promise

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

Выполняет передачу управления на указанном устройстве.

Управляющие передачи относятся к устройству, интерфейсу или конечной точке. Для передачи данных на интерфейс или конечную точку необходимо заявить права на интерфейс.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• transferInfo

  ControlTransferInfo

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (info: TransferResultInfo) => void

  • информация

    TransferResultInfo

Возвраты

• Promise<TransferResultInfo>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

findDevices()

Promise

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

Находит USB-устройства, указанные поставщиком, продуктом и (необязательно) идентификаторами интерфейса, и, если позволяют разрешения, открывает их для использования.

Если запрос на доступ отклонен или устройство не удалось открыть, дескриптор подключения не будет создан или возвращен.

Вызов этого метода эквивалентен вызову getDevices, а затем openDevice для каждого устройства.

Параметры

• Параметры

  EnumerateDevicesAndRequestAccessOptions

  Свойства, которые нужно найти на целевых устройствах.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (handles: ConnectionHandle[]) => void

  • псевдонимы

    ConnectionHandle[]

Возвраты

• Promise<ConnectionHandle[]>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getConfiguration()

Promise

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

Получает дескриптор конфигурации для выбранной конфигурации.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (config: ConfigDescriptor) => void

  • config

    ConfigDescriptor

Возвраты

• Promise<ConfigDescriptor>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getConfigurations()

Promise Chrome 47 и более поздние версии

chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

Возвращает полный набор дескрипторов конфигурации устройства.

Параметры

• устройство

  Устройство

  Device, из которого нужно получить дескрипторы.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (configs: ConfigDescriptor[]) => void

  • конфигурации

    ConfigDescriptor[]

Возвраты

• Promise<ConfigDescriptor[]>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getDevices()

Promise

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

Перечисляет подключенные USB-устройства.

Параметры

• Параметры

  EnumerateDevicesOptions

  Свойства, которые нужно найти на целевых устройствах.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (devices: Device[]) => void

  • устройства

    Устройство[]

Возвраты

• Promise<Device[]>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getUserSelectedDevices()

Promise

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

Показывает пользователю окно выбора устройства и возвращает выбранные объекты Device. Если пользователь отменит выбор, список устройств будет пустым. Для показа диалогового окна требуется жест пользователя. Если жеста пользователя не будет, обратный вызов будет выполнен так, как если бы пользователь отменил действие.

Параметры

• Параметры

  DevicePromptOptions

  Настройка диалогового окна выбора устройства.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (devices: Device[]) => void

  • устройства

    Устройство[]

Возвраты

• Promise<Device[]>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

interruptTransfer()

Promise

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

Выполняет передачу прерывания на указанном устройстве.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• transferInfo

  GenericTransferInfo

  Параметры переноса.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (info: TransferResultInfo) => void

  • информация

    TransferResultInfo

Возвраты

• Promise<TransferResultInfo>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

isochronousTransfer()

Promise

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

Выполняет изохронную передачу на указанном устройстве.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• transferInfo

  IsochronousTransferInfo

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (info: TransferResultInfo) => void

  • информация

    TransferResultInfo

Возвраты

• Promise<TransferResultInfo>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

listInterfaces()

Promise

chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
): Promise<InterfaceDescriptor[]>

Выводит список всех интерфейсов на USB-устройстве.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (descriptors: InterfaceDescriptor[]) => void

  • дескрипторы

    InterfaceDescriptor[]

Возвраты

• Promise<InterfaceDescriptor[]>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

openDevice()

Promise

chrome.usb.openDevice(
  device: Device,
  callback?: function,
): Promise<ConnectionHandle>

Открывает USB-устройство, возвращенное getDevices.

Параметры

• устройство

  Устройство

  Device, который нужно открыть.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (handle: ConnectionHandle) => void

  • дескриптор

    ConnectionHandle

Возвраты

• Promise<ConnectionHandle>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

releaseInterface()

Promise

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

Освобождает заявленный интерфейс.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• interfaceNumber

  число

  Интерфейс, который нужно освободить.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Promise<void>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

requestAccess()

Promise Поддержка прекращена

chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
): Promise<boolean>

Эта функция была предназначена только для ChromeOS, и ее вызов на других платформах приводил к ошибке. Теперь эта операция неявно выполняется в рамках openDevice, и функция возвращает true на всех платформах.

Запрашивает у брокера разрешений доступ к устройству, заявленному Chrome OS, если указанный интерфейс на устройстве не заявлен.

Параметры

• устройство

  Устройство

  Device, к которому запрашивается доступ.

• interfaceId

  число

  Запрошенный интерфейс.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • выполнено

    Логическое значение

Возвраты

• Promise<boolean>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

resetDevice()

Promise

chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
): Promise<boolean>

Попытка сбросить настройки USB-устройства. Если сброс не удастся, дескриптор подключения будет закрыт, а USB-устройство будет отключено и снова подключено. В этом случае для получения устройства необходимо снова вызвать getDevices или findDevices.

Параметры

• дескриптор

  ConnectionHandle

  Дескриптор подключения, который нужно сбросить.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • выполнено

    Логическое значение

Возвраты

• Promise<boolean>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setConfiguration()

Promise

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

Выберите конфигурацию устройства.

Эта функция позволяет сбросить настройки устройства, выбрав одну из доступных конфигураций. Допустимы только значения конфигурации больше 0, однако на некоторых устройствах с ошибками работает конфигурация 0, поэтому это значение разрешено.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству.

• configurationValue

  число

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Promise<void>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setInterfaceAlternateSetting()

Promise

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

Выбирает альтернативную настройку для ранее заявленного интерфейса.

Параметры

• дескриптор

  ConnectionHandle

  Открытое подключение к устройству, на котором был запрошен этот интерфейс.

• interfaceNumber

  число

  Интерфейс, который нужно настроить.

• alternateSetting

  число

  Альтернативная настройка, которую нужно задать.

• обратный вызов

  function необязательно

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Promise<void>

  Chrome 116 и более поздних версий

  Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onDeviceAdded

chrome.usb.onDeviceAdded.addListener(
  callback: function,
)

Событие, которое генерируется при добавлении устройства в систему. События передаются только приложениям и расширениям, у которых есть разрешение на доступ к устройству. Разрешение может быть предоставлено во время установки, когда пользователь принял необязательное разрешение (см. permissions.request), или через getUserSelectedDevices.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (device: Device) => void

  • устройство

    Устройство

onDeviceRemoved

chrome.usb.onDeviceRemoved.addListener(
  callback: function,
)

Событие, которое создается при удалении устройства из системы. Подробнее о том, какие события доставляютсяonDeviceAdded…

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (device: Device) => void

  • устройство

    Устройство