chrome.usb

Description

Utilisez l'API chrome.usb pour interagir avec les appareils USB connectés. Cette API permet d'accéder aux opérations USB dans le contexte d'une application. Grâce à cette API, les applications peuvent fonctionner comme pilotes pour les appareils matériels. Les erreurs générées par cette API sont signalées en définissant runtime.lastError et en exécutant le rappel régulier de la fonction. Dans ce cas, les paramètres normaux du rappel ne sont pas définis.

Autorisations

usb

Types

ConfigDescriptor

Propriétés

  • actif

    booléen

    Chrome 47 et versions ultérieures

    S'agit-il de la configuration active ?

  • configurationValue

    Nombre

    Numéro de configuration.

  • description

    chaîne facultatif

    Description de la configuration.

  • extra_data

    ArrayBuffer

    Données de descripteur supplémentaires associées à cette configuration.

  • interfaces

    InterfaceDescriptor[]

    Interfaces disponibles.

  • maxPower

    Nombre

    Puissance maximale requise par cet appareil en milliampères (mA).

  • remoteWakeup

    booléen

    L'appareil est compatible avec le réveil à distance.

  • selfPowered

    booléen

    L'appareil est autoalimenté.

ConnectionHandle

Propriétés

  • handle

    Nombre

    Handle opaque représentant cette connexion à l'appareil USB, ainsi que toutes les interfaces revendiquées et les transferts en attente associés. Un nouveau gestionnaire est créé chaque fois que l'appareil est ouvert. La poignée de connexion est différente de Device.device.

  • productId

    Nombre

    ID du produit.

  • vendorId

    Nombre

    ID du fournisseur de l'appareil.

ControlTransferInfo

Propriétés

  • données

    ArrayBuffer facultatif

    Données à transmettre (requises uniquement pour les transferts de sortie).

  • direction

    Sens

    Sens du transfert ("in" ou "out").

  • index

    Nombre

    Pour le champ wIndex, consultez Ibid.

  • longueur

    number facultatif

    Nombre maximal d'octets à recevoir (requis uniquement par les transferts d'entrée).

  • destinataire

    Destinataire

    Cible du transfert. La cible indiquée par index doit être revendiquée si elle est "interface" ou "endpoint".

  • request

    Nombre

    Pour le champ bRequest, consultez la section 9.3 de la spécification USB 1.1.

  • requestType

    RequestType

    Type de requête.

  • délai avant expiration

    number facultatif

    Chrome 43 ou version ultérieure

    Délai d'expiration de la requête (en millisecondes). La valeur par défaut 0 indique l'absence de délai d'expiration.

  • valeur

    Nombre

    Pour le champ wValue, consultez Ibid.

Device

Propriétés

  • appareil

    Nombre

    ID opaque du périphérique USB. Il reste inchangé jusqu'à ce que l'appareil soit débranché.

  • manufacturerName

    chaîne

    Chrome 46 ou version ultérieure

    Chaîne iManufacturer lue à partir de l'appareil, le cas échéant.

  • productId

    Nombre

    ID du produit.

  • productName

    chaîne

    Chrome 46 ou version ultérieure

    Chaîne iProduct lue à partir de l'appareil, le cas échéant.

  • serialNumber

    chaîne

    Chrome 46 ou version ultérieure

    Chaîne iSerialNumber lue à partir de l'appareil, le cas échéant.

  • vendorId

    Nombre

    ID du fournisseur de l'appareil.

  • version

    Nombre

    Chrome 51 ou version ultérieure

    Version de l'appareil (champ bcdDevice).

DeviceFilter

Propriétés

  • interfaceClass

    number facultatif

    Classe d'interface USB, correspond à n'importe quelle interface de l'appareil.

  • interfaceProtocol

    number facultatif

    Protocole d'interface USB, vérifié uniquement si la sous-classe de l'interface correspond.

  • interfaceSubclass

    number facultatif

    Sous-classe de l'interface USB, vérifiée uniquement si la classe de l'interface correspond.

  • productId

    number facultatif

    ID produit de l'appareil, vérifié uniquement si l'ID du fournisseur correspond.

  • vendorId

    number facultatif

    ID du fournisseur de l'appareil.

DevicePromptOptions

Propriétés

  • filtres

    DeviceFilter[] facultatif

    Filtrer la liste des appareils présentés à l'utilisateur Si vous fournissez plusieurs filtres, les appareils correspondant à l'un d'eux s'affichent.

  • plusieurs

    booléen facultatif

    Autorisez l'utilisateur à sélectionner plusieurs appareils.

Direction

Les valeurs Direction, Recipient, RequestType et TransferType correspondent toutes à leurs homologues dans la spécification USB.

Énumération

"in"

"out"

EndpointDescriptor

Propriétés

  • adresse

    Nombre

    Adresse du point de terminaison.

  • direction

    Sens

    Direction du transfert.

  • extra_data

    ArrayBuffer

    Données de descripteur supplémentaires associées à ce point de terminaison.

  • maximumPacketSize

    Nombre

    Taille maximale des paquets.

  • pollingInterval

    number facultatif

    Intervalle d'interrogation (interruption et isochrone uniquement).

  • synchronisation

    SynchronizationType facultatif

    Mode de synchronisation du transfert (isochrone uniquement).

  • Type de transfert.

  • utilisation

    UsageType facultatif

    Conseil d'utilisation du point de terminaison.

EnumerateDevicesAndRequestAccessOptions

Propriétés

  • interfaceId

    number facultatif

    ID de l'interface à laquelle demander l'accès. Disponible uniquement sur ChromeOS. Cela n'a aucun impact sur les autres plates-formes.

  • productId

    Nombre

    ID du produit.

  • vendorId

    Nombre

    ID du fournisseur de l'appareil.

EnumerateDevicesOptions

Propriétés

  • filtres

    DeviceFilter[] facultatif

    Un appareil correspondant à un filtre donné est renvoyé. Une liste de filtres vide renvoie tous les appareils pour lesquels l'application dispose d'une autorisation.

  • productId

    number facultatif

    Obsolète

    Équivaut à définir DeviceFilter.productId.

  • vendorId

    number facultatif

    Obsolète

    Équivaut à définir DeviceFilter.vendorId.

GenericTransferInfo

Propriétés

  • données

    ArrayBuffer facultatif

    Données à transmettre (requises uniquement pour les transferts de sortie).

  • direction

    Sens

    Sens du transfert ("in" ou "out").

  • point de terminaison

    Nombre

    Adresse du point de terminaison cible. L'interface contenant ce point de terminaison doit être revendiquée.

  • longueur

    number facultatif

    Nombre maximal d'octets à recevoir (requis uniquement par les transferts d'entrée).

  • délai avant expiration

    number facultatif

    Chrome 43 ou version ultérieure

    Délai d'expiration de la requête (en millisecondes). La valeur par défaut 0 indique l'absence de délai d'expiration.

InterfaceDescriptor

Propriétés

  • alternateSetting

    Nombre

    Numéro du paramètre alternatif de l'interface (par défaut : 0

  • description

    chaîne facultatif

    Description de l'interface.

  • endpoints

    EndpointDescriptor[]

    Points de terminaison disponibles.

  • extra_data

    ArrayBuffer

    Données de descripteur supplémentaires associées à cette interface.

  • interfaceClass

    Nombre

    Classe d'interface USB.

  • interfaceNumber

    Nombre

    Numéro de l'interface.

  • interfaceProtocol

    Nombre

    Protocole d'interface USB.

  • interfaceSubclass

    Nombre

    Sous-classe de l'interface USB.

IsochronousTransferInfo

Propriétés

  • packetLength

    Nombre

    Longueur de chacun des paquets de ce transfert.

  • paquets

    Nombre

    Nombre total de paquets dans ce transfert.

  • transferInfo

    GenericTransferInfo

    Paramètres de transfert. La longueur de transfert ou le tampon de données spécifié dans ce bloc de paramètres est divisé en fonction des limites packetLength pour former les paquets individuels du transfert.

Recipient

Énumération

"device"

"interface"

"endpoint"

"other"

RequestType

Énumération

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

Pour les modes d'interruption et isochrone, SynchronizationType et UsageType correspondent à leurs homologues dans la spécification USB.

Énumération

"asynchronous"

"adaptive"

"synchronous"

TransferResultInfo

Propriétés

  • données

    ArrayBuffer facultatif

    Données renvoyées par un transfert d'entrée. undefined pour les transferts de sortie.

  • resultCode

    number facultatif

    La valeur 0 indique que le transfert a réussi. Les autres valeurs indiquent un échec.

TransferType

Énumération

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

Énumération

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Méthodes

bulkTransfer()

Promesse 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

Effectue un transfert groupé sur l'appareil spécifié.

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

claimInterface()

Promesse 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

Réclame une interface sur un appareil USB. Avant que les données puissent être transférées vers une interface ou des points de terminaison associés, l'interface doit être revendiquée. Une seule poignée de connexion peut revendiquer une interface à la fois. Si l'interface est déjà revendiquée, cet appel échouera.

releaseInterface doit être appelé lorsque l'interface n'est plus nécessaire.

Paramètres

  • Une connexion ouverte à l'appareil.

  • interfaceNumber

    Nombre

    Interface à revendiquer.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

closeDevice()

Promesse 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
)

Ferme un descripteur de connexion. L'appel d'opérations sur un gestionnaire après sa fermeture est une opération sécurisée, mais aucune action n'est effectuée.

Paramètres

Renvoie

  • Promise<void>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

controlTransfer()

Promesse 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
)

Effectue un transfert de contrôle sur l'appareil spécifié.

Les transferts de contrôle font référence à l'appareil, à une interface ou à un point de terminaison. Les transferts vers une interface ou un point de terminaison nécessitent que l'interface soit revendiquée.

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

findDevices()

Promesse 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
)

Recherche les appareils USB spécifiés par les ID de fournisseur, de produit et (facultatif) d'interface, et les ouvre pour les utiliser si les autorisations le permettent.

Si la requête d'accès est refusée ou si l'appareil ne parvient pas à s'ouvrir, aucun gestionnaire de connexion n'est créé ni renvoyé.

Appeler cette méthode équivaut à appeler getDevices suivi de openDevice pour chaque appareil.

Paramètres

Renvoie

  • Promise<ConnectionHandle[]>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getConfiguration()

Promesse 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
)

Récupère le descripteur de configuration pour la configuration actuellement sélectionnée.

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getConfigurations()

Promise Chrome 47 et versions ultérieures 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

Renvoie l'ensemble complet des descripteurs de configuration de l'appareil.

Paramètres

Renvoie

  • Promise<ConfigDescriptor[]>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getDevices()

Promesse 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
)

Énumère les appareils USB connectés.

Paramètres

  • Propriétés à rechercher sur les appareils cibles.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (devices: Device[]) => void

Renvoie

  • Promise<Device[]>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getUserSelectedDevices()

Promesse 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
)

Présente un sélecteur d'appareil à l'utilisateur et renvoie les Device sélectionnés. Si l'utilisateur annule la sélection, les appareils du sélecteur seront vides. Un geste utilisateur est requis pour que la boîte de dialogue s'affiche. Sans geste utilisateur, le rappel s'exécute comme si l'utilisateur avait annulé.

Paramètres

  • Configuration de la boîte de dialogue de sélecteur d'appareils.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (devices: Device[]) => void

Renvoie

  • Promise<Device[]>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

interruptTransfer()

Promesse 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

Effectue un transfert d'interruption sur l'appareil spécifié.

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

isochronousTransfer()

Promesse 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
)

Effectue un transfert isochrone sur l'appareil spécifique.

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

listInterfaces()

Promesse 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
)

Répertorie toutes les interfaces d'un appareil USB.

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

openDevice()

Promesse 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
)

Ouvre un appareil USB renvoyé par getDevices.

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

releaseInterface()

Promesse 
chrome.usb.releaseInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

Libère une interface revendiquée.

Paramètres

  • Une connexion ouverte à l'appareil.

  • interfaceNumber

    Nombre

    Interface à publier.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

requestAccess()

Promise Obsolète
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

Cette fonction était spécifique à ChromeOS. L'appeler sur d'autres plates-formes échouait. Cette opération est désormais effectuée implicitement dans le cadre de openDevice, et cette fonction renvoie true sur toutes les plates-formes.

Demande au courtier d'autorisations l'accès à un appareil revendiqué par ChromeOS si l'interface donnée sur l'appareil n'est pas revendiquée.

Paramètres

  • appareil

    Appareil

    Device pour lequel vous demandez l'accès.

  • interfaceId

    Nombre

    Interface spécifique demandée.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (success: boolean) => void

    • success

      booléen

Renvoie

  • Promise<boolean>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

resetDevice()

Promesse 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
)

Tentative de réinitialisation de l'appareil USB. Si la réinitialisation échoue, le gestionnaire de connexion donné sera fermé et l'appareil USB semblera être déconnecté, puis reconnecté. Dans ce cas, getDevices ou findDevices doivent être appelés à nouveau pour acquérir l'appareil.

Paramètres

  • Un gestionnaire de connexion à réinitialiser.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (success: boolean) => void

    • success

      booléen

Renvoie

  • Promise<boolean>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setConfiguration()

Promesse 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
)

Sélectionnez une configuration d'appareil.

Cette fonction réinitialise l'appareil en sélectionnant l'une des configurations disponibles. Seules les valeurs de configuration supérieures à 0 sont valides. Toutefois, certains appareils présentant des bugs ont une configuration 0 fonctionnelle, et cette valeur est donc autorisée.

Paramètres

  • Une connexion ouverte à l'appareil.

  • configurationValue

    Nombre

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setInterfaceAlternateSetting()

Promesse 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
)

Sélectionne un autre paramètre sur une interface précédemment revendiquée.

Paramètres

  • Connexion ouverte à l'appareil sur lequel cette interface a été revendiquée.

  • interfaceNumber

    Nombre

    Interface à configurer.

  • alternateSetting

    Nombre

    Paramètre de remplacement à configurer.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onDeviceAdded

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

Événement généré lorsqu'un appareil est ajouté au système. Les événements ne sont diffusés que vers les applications et les extensions autorisées à accéder à l'appareil. L'autorisation peut avoir été accordée au moment de l'installation, lorsque l'utilisateur a accepté une autorisation facultative (voir permissions.request) ou via getUserSelectedDevices.

Paramètres

  • rappel

    fonction

    Le paramètre callback se présente comme suit : 

    (device: Device) => void

onDeviceRemoved

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

Événement généré lorsqu'un appareil est supprimé du système. Consultez onDeviceAdded pour connaître les événements envoyés.

Paramètres

  • rappel

    fonction

    Le paramètre callback se présente comme suit : 

    (device: Device) => void