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 une application. Grâce à cette API, les applications peuvent servir de 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 habituels du rappel ne seront pas définis.

Autorisations

usb

Types

ConfigDescriptor

Propriétés

  • actif

    booléen

    Chrome 47 et versions ultérieures

    Est-ce la configuration active ?

  • configurationValue

    Total

    Numéro de configuration.

  • description

    chaîne facultative

    Description de la configuration.

  • extra_data

    ArrayBuffer

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

  • interfaces

    InterfaceDescriptor[]

    Interfaces disponibles.

  • maxPower

    Total

    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

    Total

    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 handle est créé chaque fois que l'appareil est ouvert. Le handle de connexion est différent de Device.device.

  • productId

    Total

    ID du produit.

  • vendorId

    Total

    ID du fournisseur de l'appareil.

ControlTransferInfo

Propriétés

  • données

    ArrayBuffer facultatif

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

  • direction

    Sens

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

  • index

    Total

    Champ wIndex, voir Ibid.

  • longueur

    number facultatif

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

  • destinataire

    Destinataire

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

  • request

    Total

    Le champ bRequest, voir Universal Serial Bus Specification Revision 1.1 § 9.3.

  • requestType

    RequestType

    Type de demande.

  • délai avant expiration

    number facultatif

    Chrome 43 et versions ultérieures

    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

    Total

    Champ wValue, voir Ibid.

Device

Propriétés

  • appareil

    Total

    ID opaque pour le périphérique USB. Elle reste inchangée jusqu'à ce que l'appareil soit débranché.

  • manufacturerName

    chaîne

    Chrome 46 et versions ultérieures

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

  • productId

    Total

    ID du produit.

  • productName

    chaîne

    Chrome 46 et versions ultérieures

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

  • serialNumber

    chaîne

    Chrome 46 et versions ultérieures

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

  • vendorId

    Total

    ID du fournisseur de l'appareil.

  • version

    Total

    Chrome 51 et versions ultérieures

    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, coché uniquement si la sous-classe de l'interface correspond.

  • interfaceSubclass

    number facultatif

    Sous-classe de l'interface USB, cochée uniquement si la classe de l'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 s'affichent.

  • plusieurs

    booléen facultatif

    Autorisez l'utilisateur à sélectionner plusieurs appareils.

Direction

Les champs "Direction", "Recipient", "RequestType" et "TransferType" correspondent à leurs équivalents dans la spécification USB.

Énumération

"in"

"out"

EndpointDescriptor

Propriétés

  • adresse

    Total

    Adresse du point de terminaison.

  • direction

    Sens

    Direction du transfert.

  • extra_data

    ArrayBuffer

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

  • maximumPacketSize

    Total

    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

    Indication 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

    Total

    ID du produit.

  • vendorId

    Total

    ID du fournisseur de l'appareil.

EnumerateDevicesOptions

Propriétés

  • filtres

    DeviceFilter[] facultatif

    Un appareil correspondant à un filtre donné 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 (obligatoires uniquement pour les transferts de sortie).

  • direction

    Sens

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

  • point de terminaison

    Total

    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 et versions ultérieures

    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

    Total

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

  • description

    chaîne facultative

    Description de l'interface.

  • endpoints

    EndpointDescriptor[]

    Points de terminaison disponibles.

  • extra_data

    ArrayBuffer

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

  • interfaceClass

    Total

    Classe d'interface USB.

  • interfaceNumber

    Total

    Numéro de l'interface.

  • interfaceProtocol

    Total

    Protocole de l'interface USB.

  • interfaceSubclass

    Total

    Sous-classe de l'interface USB.

IsochronousTransferInfo

Propriétés

  • packetLength

    Total

    Longueur de chacun des paquets de ce transfert.

  • paquets

    Total

    Nombre total de paquets dans ce transfert.

  • transferInfo

    GenericTransferInfo

    Paramètres de transfert. La longueur du transfert ou le tampon de données spécifiés dans ce bloc de paramètres sont divisés 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 correspondent à leurs noms 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

    Une valeur de 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 et versions ultérieures

    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, vous devez revendiquer l'interface. 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

    Total

    Interface à revendiquer.

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 116 et versions ultérieures

    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 et versions ultérieures

    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 et versions ultérieures

    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 périphériques USB spécifiés par les ID de fournisseur, de produit et (facultativement) 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, un handle de connexion ne sera pas créé ni renvoyé.

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

Paramètres

Renvoie

  • Promise<ConnectionHandle[]>

    Chrome 116 et versions ultérieures

    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>

Obtient le descripteur de configuration pour la configuration actuellement sélectionnée.

Paramètres

Renvoie

  • Chrome 116 et versions ultérieures

    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 complet des descripteurs de configuration de l'appareil.

Paramètres

Renvoie

  • Promise<ConfigDescriptor[]>

    Chrome 116 et versions ultérieures

    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 périphériques 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 et versions ultérieures

    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, les appareils seront vides. Un geste de l'utilisateur est requis pour que la boîte de dialogue s'affiche. Sans geste de l'utilisateur, le rappel s'exécute comme si l'utilisateur avait annulé.

Paramètres

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

  • callback

    function facultatif

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

    (devices: Device[]) => void

Renvoie

  • Promise<Device[]>

    Chrome 116 et versions ultérieures

    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 et versions ultérieures

    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écifique.

Paramètres

Renvoie

  • Chrome 116 et versions ultérieures

    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[]>

Liste toutes les interfaces d'un périphérique USB.

Paramètres

Renvoie

  • Chrome 116 et versions ultérieures

    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 périphérique USB renvoyé par getDevices.

Paramètres

Renvoie

  • Chrome 116 et versions ultérieures

    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

    Total

    Interface à libérer.

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 116 et versions ultérieures

    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 openDevice. Cette fonction renvoie true sur toutes les plates-formes.

Demande l'accès au broker d'autorisations à 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 souhaitez demander l'accès.

  • interfaceId

    Total

    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 et versions ultérieures

    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 le périphérique USB. Si la réinitialisation échoue, le handle de connexion donné sera fermé et l'appareil USB semblera déconnecté, puis reconnecté. Dans ce cas, getDevices ou findDevices doivent être appelés à nouveau pour acquérir l'appareil.

Paramètres

  • 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 et versions ultérieures

    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 efficacement 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 fonctionnelle 0. Cette valeur est donc autorisée.

Paramètres

  • Une connexion ouverte à l'appareil.

  • configurationValue

    Total

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 116 et versions ultérieures

    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 revendiquée précédemment.

Paramètres

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

  • interfaceNumber

    Total

    Interface à configurer.

  • alternateSetting

    Total

    Paramètre alternatif à configurer.

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 116 et versions ultérieures

    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 lors 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 transmis.

Paramètres

  • callback

    fonction

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

    (device: Device) => void