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 depuis le contexte d'une application. Grâce à cette API, les applications peuvent fonctionner comme des pilotes pour les périphériques 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 standard de la fonction. Dans ce cas, les paramètres standards du rappel ne seront pas définis.

Autorisations

usb

Disponibilité

ChromeOS uniquement

Types

ConfigDescriptor

Propriétés

  • actif

    booléen

    Chrome 47 ou version ultérieure

    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 la sortie de veille à distance.

  • selfPowered

    booléen

    L'appareil est auto-alimenté.

ConnectionHandle

Propriétés

  • handle

    nombre

    Un handle opaque représentant cette connexion à l'appareil USB, ainsi que toutes les interfaces revendiquées et tous les transferts en attente associés. Un handle est créé chaque fois que l'appareil est ouvert. Le handle de connexion est différent de Device.device.

  • productId

    nombre

    L'ID du produit.

  • vendorId

    nombre

    ID du fournisseur de l'appareil.

ControlTransferInfo

Propriétés

  • données

    ArrayBuffer facultatif

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

  • direction

    Sens

    La direction du transfert ("in" ou "out").

  • index

    nombre

    Pour le champ wIndex, consultez Ibid.

  • longueur

    number facultatif

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

  • destinataire

    Destinataire

    La cible du transfert. La cible donnée par index doit être revendiquée si "interface" ou "endpoint".

  • request

    nombre

    Pour le champ bRequest, consultez la section 9.3 de la spécification Universal Serial Bus, révision 1.1.

  • requestType

    RequestType

    Type de requête.

  • délai avant expiration

    number facultatif

    Chrome 43 ou version ultérieure

    Délai avant 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 de l'appareil 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, si elle est disponible.

  • productId

    nombre

    L'ID du produit.

  • productName

    chaîne

    Chrome 46 ou version ultérieure

    Chaîne iProduct lue à partir de l'appareil, si disponible.

  • serialNumber

    chaîne

    Chrome 46 ou version ultérieure

    Chaîne iSerialNumber lue à partir de l'appareil, si elle est disponible.

  • 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 d'interface correspond.

  • interfaceSubclass

    number facultatif

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

  • productId

    number facultatif

    ID produit de l'appareil, vérifié uniquement si l'ID 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 plusieurs filtres sont fournis, les appareils correspondant à l'un d'eux seront affichés.

  • plusieurs

    boolean facultatif

    Autorisez l'utilisateur à sélectionner plusieurs appareils.

Direction

"Direction", "Recipient", "RequestType" et "TransferType" correspondent tous à leurs homonymes 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 pour laquelle vous souhaitez demander l'accès. Disponible uniquement sur ChromeOS. Cela n'a aucune incidence sur les autres plates-formes.

  • productId

    nombre

    L'ID du produit.

  • vendorId

    nombre

    ID du fournisseur de l'appareil.

EnumerateDevicesOptions

Propriétés

  • filtres

    DeviceFilter[] facultatif

    Un appareil correspondant à l'un des filtres indiqués sera 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 (obligatoire uniquement pour les transferts de sortie).

  • direction

    Sens

    La direction 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 pour les transferts d'entrée).

  • délai avant expiration

    number facultatif

    Chrome 43 ou version ultérieure

    Délai avant 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 de paramètre alternatif de l'interface (par défaut : 0)

  • description

    chaîne facultatif

    Description de l'interface.

  • points de terminaison

    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 de l'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é selon les 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 sont mappés à leurs homonymes 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()

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

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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

claimInterface()

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

Revendique une interface sur un appareil USB. Avant de pouvoir transférer des données vers une interface ou des points de terminaison associés, l'interface doit être revendiquée. Un seul handle de connexion peut revendiquer une interface à un moment donné. 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.

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

closeDevice()

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

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

Paramètres

Renvoie

  • Promise<void>

    Chrome 116 ou version ultérieure

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

controlTransfer()

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

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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

findDevices()

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

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

Si la demande d'accès est refusée ou si l'appareil ne peut pas être ouvert, aucun handle de connexion n'est créé ni renvoyé.

Appeler cette méthode équivaut à appeler getDevices, puis 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getConfiguration()

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

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 les 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,
): Promise<ConfigDescriptor[]>

Renvoie l'ensemble 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getDevices()

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

Énumère les appareils USB connectés.

Paramètres

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

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getUserSelectedDevices()

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

Présente un sélecteur d'appareils à l'utilisateur et renvoie les Device sélectionnés. Si l'utilisateur annule le sélecteur, la liste des appareils sera vide. Un geste de l'utilisateur est requis pour afficher la boîte de dialogue. Sans geste de l'utilisateur, le rappel s'exécutera comme si l'utilisateur avait annulé.

Paramètres

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

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

interruptTransfer()

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

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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

isochronousTransfer()

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

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

Paramètres

Renvoie

  • Chrome 116 ou version ultérieure

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

listInterfaces()

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

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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

openDevice()

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

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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

releaseInterface()

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

Libère une interface revendiquée.

Paramètres

  • Une connexion ouverte à l'appareil.

  • interfaceNumber

    nombre

    Interface à libérer.

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

requestAccess()

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

Cette fonction était spécifique à ChromeOS, et son appel sur d'autres plates-formes échouait. Cette opération est désormais effectuée de manière implicite dans le cadre de openDevice, et cette fonction renvoie true sur toutes les plates-formes.

Demande l'accès à un appareil revendiqué par Chrome OS auprès de l'agent d'autorisation si l'interface donnée sur l'appareil n'est pas revendiquée.

Paramètres

  • appareil

    Appareil

    Device pour lequel vous souhaitez demander l'accès.

  • interfaceId

    nombre

    L'interface spécifique demandée.

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

resetDevice()

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

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

Paramètres

  • Un handle de connexion à réinitialiser.

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setConfiguration()

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

Sélectionnez une configuration d'appareil.

Cette fonction réinitialise l'appareil en sélectionnant l'une de ses configurations disponibles. Seules les valeurs de configuration supérieures à 0 sont valides. Toutefois, certains appareils défectueux ont une configuration 0 qui fonctionne, et cette valeur est donc autorisée.

Paramètres

  • Une connexion ouverte à l'appareil.

  • configurationValue

    nombre

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setInterfaceAlternateSetting()

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

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

Paramètres

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

  • interfaceNumber

    nombre

    Interface à configurer.

  • alternateSetting

    nombre

    Le paramètre alternatif à configurer.

  • callback

    function 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 les 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 qu'aux applications et 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

  • callback

    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 savoir quels événements sont diffusés.

Paramètres

  • callback

    fonction

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

    (device: Device) => void