chrome.usb

Beschreibung

Mit der chrome.usb API können Sie mit verbundenen USB-Geräten interagieren. Diese API bietet Zugriff auf USB-Vorgänge im Kontext einer App. Mit dieser API können Apps als Treiber für Hardwaregeräte fungieren. Fehler, die von dieser API generiert werden, werden gemeldet, indem runtime.lastError festgelegt und der reguläre Callback der Funktion ausgeführt wird. Die regulären Parameter des Rückrufs sind in diesem Fall nicht definiert.

Berechtigungen

usb

Typen

ConfigDescriptor

Attribute

  • Aktiv

    boolean

    Chrome 47 und höher

    Ist dies die aktive Konfiguration?

  • configurationValue

    Zahl

    Die Konfigurationsnummer.

  • Beschreibung

    String optional

    Beschreibung der Konfiguration.

  • extra_data

    ArrayBuffer

    Zusätzliche Deskriptordaten, die mit dieser Konfiguration verknüpft sind.

  • Schnittstellen

    InterfaceDescriptor[]

    Verfügbare Oberflächen.

  • maxPower

    Zahl

    Die maximale Leistungsaufnahme dieses Geräts in Milliampere (mA).

  • remoteWakeup

    boolean

    Das Gerät unterstützt das Remote-Aufwecken.

  • selfPowered

    boolean

    Das Gerät wird über eine eigene Stromquelle betrieben.

ConnectionHandle

Attribute

  • Handle (der)

    Zahl

    Ein undurchsichtiges Handle, das diese Verbindung zum USB-Gerät und alle zugehörigen beanspruchten Schnittstellen und ausstehenden Übertragungen darstellt. Bei jedem Öffnen des Geräts wird ein neuer Handle erstellt. Der Verbindungshandle unterscheidet sich von Device.device.

  • productId

    Zahl

    Die Produkt-ID.

  • vendorId

    Zahl

    Die Geräteanbieter-ID.

ControlTransferInfo

Attribute

  • Daten

    ArrayBuffer optional

    Die zu übertragenden Daten (nur bei Ausgabetransfers erforderlich).

  • direction

    Richtung

    Die Übertragungsrichtung ("in" oder "out").

  • Index

    Zahl

    Das Feld wIndex, siehe Ibid.

  • Länge

    number optional

    Die maximale Anzahl der zu empfangenden Bytes (nur für Eingabeübertragungen erforderlich).

  • Empfänger

    Empfänger

    Das Übertragungsziel. Das durch index angegebene Ziel muss beansprucht werden, wenn "interface" oder "endpoint".

  • Anfrage

    Zahl

    Das Feld bRequest, siehe Universal Serial Bus Specification Revision 1.1, § 9.3.

  • requestType

    RequestType

    Der Anfragetyp.

  • Zeitüberschreitung

    number optional

    Chrome 43 und höher

    Zeitlimit für Anfragen (in Millisekunden). Der Standardwert 0 gibt kein Zeitlimit an.

  • Wert

    Zahl

    Das Feld wValue, siehe Ibid.

Device

Attribute

  • Gerät

    Zahl

    Eine intransparente ID für das USB-Gerät. Sie bleibt unverändert, bis das Gerät vom Stromnetz getrennt wird.

  • manufacturerName

    String

    Chrome 46 und höher

    Der iManufacturer-String, der vom Gerät gelesen wird, sofern verfügbar.

  • productId

    Zahl

    Die Produkt-ID.

  • productName (Produktname)

    String

    Chrome 46 und höher

    Der iProduct-String, der vom Gerät gelesen wird, sofern verfügbar.

  • serialNumber

    String

    Chrome 46 und höher

    Der iSerialNumber-String, der vom Gerät gelesen wird, sofern verfügbar.

  • vendorId

    Zahl

    Die Geräteanbieter-ID.

  • Version

    Zahl

    Chrome 51 und höher

    Die Geräteversion (Feld „bcdDevice“).

DeviceFilter

Attribute

  • interfaceClass

    number optional

    USB-Schnittstellenklasse, die mit jeder Schnittstelle auf dem Gerät übereinstimmt.

  • interfaceProtocol

    number optional

    USB-Schnittstellenprotokoll, wird nur geprüft, wenn die Schnittstellenunterklasse übereinstimmt.

  • interfaceSubclass

    number optional

    Unterklasse der USB-Schnittstelle, wird nur geprüft, wenn die Schnittstellenklasse übereinstimmt.

  • productId

    number optional

    Produkt-ID des Geräts, wird nur geprüft, wenn die Anbieter-ID übereinstimmt.

  • vendorId

    number optional

    Gerätehersteller-ID.

DevicePromptOptions

Attribute

  • Filter

    DeviceFilter[] optional

    Filtern Sie die Liste der Geräte, die dem Nutzer präsentiert werden. Wenn mehrere Filter angegeben werden, werden Geräte angezeigt, die mit einem der Filter übereinstimmen.

  • mehrere

    boolean optional

    Der Nutzer kann mehrere Geräte auswählen.

Direction

„Direction“, „Recipient“, „RequestType“ und „TransferType“ entsprechen ihren Namensvettern in der USB-Spezifikation.

Enum

"in"

"out"

EndpointDescriptor

Attribute

  • Adresse

    Zahl

    Endpunktadresse.

  • direction

    Richtung

    Richtung der Übertragung.

  • extra_data

    ArrayBuffer

    Zusätzliche Deskriptordaten, die mit diesem Endpunkt verknüpft sind.

  • maximumPacketSize

    Zahl

    Maximale Paketgröße.

  • pollingInterval

    number optional

    Abfrageintervall (nur Interrupt und isochron).

  • Synchronisierung

    SynchronizationType optional

    Synchronisationsmodus für die Übertragung (nur isochron).

  • Art der Anrufweiterleitung

  • Verwendung

    UsageType optional

    Hinweis zur Endpunktnutzung.

EnumerateDevicesAndRequestAccessOptions

Attribute

  • interfaceId

    number optional

    Die Schnittstellen-ID, für die der Zugriff angefordert werden soll. Nur unter ChromeOS verfügbar. Auf anderen Plattformen hat das keine Auswirkungen.

  • productId

    Zahl

    Die Produkt-ID.

  • vendorId

    Zahl

    Die Geräteanbieter-ID.

EnumerateDevicesOptions

Attribute

  • Filter

    DeviceFilter[] optional

    Es wird ein Gerät zurückgegeben, das einem der angegebenen Filter entspricht. Bei einer leeren Filterliste werden alle Geräte zurückgegeben, für die die App eine Berechtigung hat.

  • productId

    number optional

    Eingestellt

    Entspricht dem Festlegen von DeviceFilter.productId.

  • vendorId

    number optional

    Eingestellt

    Entspricht dem Festlegen von DeviceFilter.vendorId.

GenericTransferInfo

Attribute

  • Daten

    ArrayBuffer optional

    Die zu übertragenden Daten (nur bei Ausgabetransfers erforderlich).

  • direction

    Richtung

    Die Übertragungsrichtung ("in" oder "out").

  • Endpunkt

    Zahl

    Die Zielendpunktadresse. Die Schnittstelle mit diesem Endpunkt muss beansprucht werden.

  • Länge

    number optional

    Die maximale Anzahl der zu empfangenden Bytes (nur für Eingabeübertragungen erforderlich).

  • Zeitüberschreitung

    number optional

    Chrome 43 und höher

    Zeitlimit für Anfragen (in Millisekunden). Der Standardwert 0 gibt kein Zeitlimit an.

InterfaceDescriptor

Attribute

  • alternateSetting

    Zahl

    Die Nummer der alternativen Einstellung der Schnittstelle (Standardwert: 0

  • Beschreibung

    String optional

    Beschreibung der Schnittstelle.

  • Endpunkte

    EndpointDescriptor[]

    Verfügbare Endpunkte

  • extra_data

    ArrayBuffer

    Zusätzliche Deskriptordaten, die mit dieser Schnittstelle verknüpft sind.

  • interfaceClass

    Zahl

    Die USB-Schnittstellenklasse.

  • interfaceNumber

    Zahl

    Die Schnittstellennummer.

  • interfaceProtocol

    Zahl

    Das USB-Schnittstellenprotokoll.

  • interfaceSubclass

    Zahl

    Die Unterklasse der USB-Schnittstelle.

IsochronousTransferInfo

Attribute

  • packetLength

    Zahl

    Die Länge der einzelnen Pakete bei dieser Übertragung.

  • Pakete

    Zahl

    Die Gesamtzahl der Pakete bei dieser Übertragung.

  • transferInfo

    GenericTransferInfo

    Übertragungsparameter. Die in diesem Parameterblock angegebene Übertragungslänge oder der Datenpuffer wird entlang der packetLength-Grenzen aufgeteilt, um die einzelnen Pakete der Übertragung zu bilden.

Recipient

Enum

"device"

"interface"

"endpoint"

"other"

RequestType

Enum

„standard“

"class"

„vendor“

"reserved"

SynchronizationType

Im Interrupt- und isochronen Modus entsprechen SynchronizationType und UsageType ihren Namensvettern in der USB-Spezifikation.

Enum

„asynchron“

"adaptive"

"synchronous"

TransferResultInfo

Attribute

  • Daten

    ArrayBuffer optional

    Die von einer Eingabeübertragung zurückgegebenen Daten. undefined für Ausgabetransfers.

  • resultCode

    number optional

    Der Wert 0 gibt an, dass die Übertragung erfolgreich war. Andere Werte weisen auf einen Fehler hin.

TransferType

Enum

„control“

"interrupt"

„isochronous“

"bulk"

UsageType

Enum

"data"

„feedback“

"explicitFeedback"

"periodic"

„Benachrichtigung“

Methoden

bulkTransfer()

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

Führt eine Bulk-Übertragung auf dem angegebenen Gerät durch.

Parameter

Ausgabe

  • Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

claimInterface()

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

Fordert eine Schnittstelle auf einem USB-Gerät an. Bevor Daten an eine Schnittstelle oder zugehörige Endpunkte übertragen werden können, muss die Schnittstelle beansprucht werden. Jeweils nur ein Verbindungshandle kann eine Schnittstelle beanspruchen. Wenn die Schnittstelle bereits beansprucht wurde, schlägt dieser Aufruf fehl.

releaseInterface sollte aufgerufen werden, wenn die Schnittstelle nicht mehr benötigt wird.

Parameter

  • Handle (der)

    ConnectionHandle

    Eine offene Verbindung zum Gerät.

  • interfaceNumber

    Zahl

    Die Schnittstelle, die beansprucht werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

closeDevice()

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

Schließt ein Verbindungshandle. Das Aufrufen von Vorgängen für ein Handle, nachdem es geschlossen wurde, ist ein sicherer Vorgang, führt aber zu keiner Aktion.

Parameter

Ausgabe

  • Promise<void>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

controlTransfer()

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

Führt eine Steuerungsübergabe auf dem angegebenen Gerät durch.

Die Übertragung der Steuerung bezieht sich entweder auf das Gerät, eine Schnittstelle oder einen Endpunkt. Für Übertragungen an eine Schnittstelle oder einen Endpunkt muss die Schnittstelle beansprucht werden.

Parameter

Ausgabe

  • Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

findDevices()

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

Sucht nach USB-Geräten, die durch die Anbieter-, Produkt- und (optional) Schnittstellen-IDs angegeben werden, und öffnet sie, sofern die Berechtigungen dies zulassen.

Wenn die Zugriffsanfrage abgelehnt wird oder das Gerät keine Verbindung öffnen kann, wird kein Verbindungshandle erstellt oder zurückgegeben.

Das Aufrufen dieser Methode entspricht dem Aufrufen von getDevices gefolgt von openDevice für jedes Gerät.

Parameter

Ausgabe

  • Promise<ConnectionHandle[]>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getConfiguration()

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

Ruft den Konfigurationsdeskriptor für die aktuell ausgewählte Konfiguration ab.

Parameter

Ausgabe

  • Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getConfigurations()

Promise Chrome 47 und höher 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

Gibt den vollständigen Satz von Gerätekonfigurationsdeskriptoren zurück.

Parameter

Ausgabe

  • Promise<ConfigDescriptor[]>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getDevices()

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

Listet verbundene USB-Geräte auf.

Parameter

  • Die Eigenschaften, nach denen auf Zielgeräten gesucht werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (devices: Device[]) => void

Ausgabe

  • Promise<Device[]>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getUserSelectedDevices()

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

Zeigt dem Nutzer eine Geräteauswahl an und gibt die ausgewählten Devices zurück. Wenn der Nutzer den Picker schließt, sind die Geräte leer. Für die Anzeige des Dialogfelds ist eine Nutzeraktion erforderlich. Ohne Nutzeraktion wird der Callback so ausgeführt, als hätte der Nutzer die Aktion abgebrochen.

Parameter

  • Konfiguration des Dialogfelds für die Geräteauswahl.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (devices: Device[]) => void

Ausgabe

  • Promise<Device[]>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

interruptTransfer()

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

Führt eine Interrupt-Übertragung auf dem angegebenen Gerät durch.

Parameter

Ausgabe

  • Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

isochronousTransfer()

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

Führt eine isochrone Übertragung auf dem angegebenen Gerät durch.

Parameter

Ausgabe

  • Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

listInterfaces()

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

Listet alle Schnittstellen auf einem USB-Gerät auf.

Parameter

Ausgabe

  • Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

openDevice()

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

Öffnet ein USB-Gerät, das von getDevices zurückgegeben wurde.

Parameter

Ausgabe

  • Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

releaseInterface()

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

Gibt eine beanspruchte Schnittstelle frei.

Parameter

  • Handle (der)

    ConnectionHandle

    Eine offene Verbindung zum Gerät.

  • interfaceNumber

    Zahl

    Die freizugebende Schnittstelle.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

requestAccess()

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

Diese Funktion war spezifisch für ChromeOS und der Aufruf auf anderen Plattformen würde fehlschlagen. Dieser Vorgang wird jetzt implizit als Teil von openDevice ausgeführt und diese Funktion gibt auf allen Plattformen true zurück.

Fordert Zugriff vom Berechtigungsbroker auf ein Gerät an, das von ChromeOS beansprucht wird, wenn die angegebene Schnittstelle auf dem Gerät nicht beansprucht wird.

Parameter

  • Gerät

    Gerät

    Die Device, für die Zugriff angefordert werden soll.

  • interfaceId

    Zahl

    Die angeforderte Schnittstelle.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (success: boolean) => void

    • Erfolg

      boolean

Ausgabe

  • Promise<boolean>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

resetDevice()

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

Versucht, das USB-Gerät zurückzusetzen. Wenn das Zurücksetzen fehlschlägt, wird das angegebene Verbindungshandle geschlossen und das USB-Gerät wird getrennt und dann wieder verbunden. In diesem Fall muss getDevices oder findDevices noch einmal aufgerufen werden, um das Gerät zu erhalten.

Parameter

  • Handle (der)

    ConnectionHandle

    Ein Verbindungshandle, das zurückgesetzt werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (success: boolean) => void

    • Erfolg

      boolean

Ausgabe

  • Promise<boolean>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

setConfiguration()

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

Wählen Sie eine Gerätekonfiguration aus.

Mit dieser Funktion wird das Gerät effektiv zurückgesetzt, indem eine der verfügbaren Konfigurationen des Geräts ausgewählt wird. Nur Konfigurationswerte, die größer als 0 sind, sind gültig. Einige fehlerhafte Geräte haben jedoch eine funktionierende Konfiguration 0. Daher ist dieser Wert zulässig.

Parameter

  • Handle (der)

    ConnectionHandle

    Eine offene Verbindung zum Gerät.

  • configurationValue

    Zahl

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

setInterfaceAlternateSetting()

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

Wählt eine alternative Einstellung für eine zuvor beanspruchte Schnittstelle aus.

Parameter

  • Handle (der)

    ConnectionHandle

    Eine offene Verbindung zu dem Gerät, auf dem diese Schnittstelle beansprucht wurde.

  • interfaceNumber

    Zahl

    Die zu konfigurierende Schnittstelle.

  • alternateSetting

    Zahl

    Die alternative Einstellung, die konfiguriert werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 116 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onDeviceAdded

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

Ereignis, das generiert wird, wenn dem System ein Gerät hinzugefügt wird. Ereignisse werden nur an Apps und Erweiterungen übertragen, die die Berechtigung haben, auf das Gerät zuzugreifen. Die Berechtigung wurde möglicherweise bei der Installation erteilt, als der Nutzer eine optionale Berechtigung akzeptiert hat (siehe permissions.request), oder über getUserSelectedDevices.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (device: Device) => void

onDeviceRemoved

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

Ereignis, das generiert wird, wenn ein Gerät aus dem System entfernt wird. Unter onDeviceAdded finden Sie Informationen dazu, welche Ereignisse bereitgestellt werden.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (device: Device) => void