chrome.usb

Descrizione

Usa l'API chrome.usb per interagire con i dispositivi USB connessi. Questa API consente di accedere alle operazioni USB dal contesto di un'app. Grazie all'API, le app possono fungere da driver per dispositivi hardware. Gli errori generati da questa API vengono segnalati impostando runtime.lastError ed eseguendo il callback normale della funzione. In questo caso, i parametri normali del callback non saranno definiti.

Autorizzazioni

usb

Tipi

ConfigDescriptor

Proprietà

  • attivo

    boolean

    Chrome 47 e versioni successive

    È la configurazione attiva?

  • configurationValue

    numero

    Il numero della configurazione.

  • descrizione

    stringa facoltativo

    Descrizione della configurazione.

  • extra_data

    ArrayBuffer

    Dati del descrittore aggiuntivi associati a questa configurazione.

  • interfacce

    InterfaceDescriptor[]

    Interfacce disponibili.

  • maxPower

    numero

    La potenza massima necessaria a questo dispositivo in milliampere (mA).

  • remoteWakeup

    boolean

    Il dispositivo supporta la riattivazione remota.

  • selfPowered

    boolean

    Il dispositivo è alimentato autonomamente.

ConnectionHandle

Proprietà

  • handle

    numero

    Un punto di manipolazione opaco che rappresenta questa connessione al dispositivo USB e a tutte le interfacce rivendicate associate e ai trasferimenti in attesa. Ogni volta che il dispositivo viene aperto, viene creato un nuovo handle. L'handle della connessione è diverso da Device.device.

  • productId

    numero

    L'ID prodotto.

  • vendorId

    numero

    L'ID del fornitore del dispositivo.

ControlTransferInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

    I dati da trasmettere (necessari solo per i trasferimenti di output).

  • direction

    Direzione

    La direzione di trasferimento ("in" o "out").

  • indice

    numero

    Per il campo wIndex, consulta la sezione Ibid.

  • length

    numero facoltativo

    Il numero massimo di byte da ricevere (richiesto solo dai trasferimenti di input).

  • destinatario

    Destinatario

    La destinazione del trasferimento. Il target specificato da index deve essere rivendicato se "interface" o "endpoint".

  • richiesta

    numero

    Il campo bRequest, vedere Universal Serial Bus Specification Revision 1.1 § 9.3.

  • requestType

    RequestType

    Il tipo di richiesta.

  • timeout

    numero facoltativo

    Chrome 43 e versioni successive

    Timeout richiesta (in millisecondi). Il valore predefinito 0 indica l'assenza di timeout.

  • valore

    numero

    Per il campo wValue, consulta la sezione Ibid.

Device

Proprietà

  • dispositivo

    numero

    Un ID opaco per il dispositivo USB. Rimane invariato fino a quando il dispositivo non viene scollegato.

  • manufacturerName

    stringa

    Chrome 46 e versioni successive

    La stringa iManufacturer letta dal dispositivo, se disponibile.

  • productId

    numero

    L'ID prodotto.

  • productName

    stringa

    Chrome 46 e versioni successive

    La stringa iProduct letta dal dispositivo, se disponibile.

  • serialNumber

    stringa

    Chrome 46 e versioni successive

    La stringa iSerialNumber letta dal dispositivo, se disponibile.

  • vendorId

    numero

    L'ID del fornitore del dispositivo.

  • versione

    numero

    Chrome 51 e versioni successive

    La versione del dispositivo (campo bcdDevice).

DeviceFilter

Proprietà

  • interfaceClass

    numero facoltativo

    Classe interfaccia USB, corrisponde a qualsiasi interfaccia del dispositivo.

  • interfaceProtocol

    numero facoltativo

    Protocollo di interfaccia USB, selezionato solo se la sottoclasse dell'interfaccia corrisponde.

  • interfaceSubclass

    numero facoltativo

    Sottoclasse dell'interfaccia USB, selezionata solo se la classe dell'interfaccia corrisponde.

  • productId

    numero facoltativo

    ID prodotto dispositivo, selezionato solo se l'ID fornitore corrisponde.

  • vendorId

    numero facoltativo

    ID del fornitore del dispositivo.

DevicePromptOptions

Proprietà

  • filtri

    DeviceFilter[] facoltativo

    Filtra l'elenco dei dispositivi presentato all'utente. Se vengono forniti più filtri, verranno visualizzati i dispositivi corrispondenti a qualsiasi filtro.

  • multiple

    booleano facoltativo

    Consenti all'utente di selezionare più dispositivi.

Direction

Direction, Recipient, RequestType e TransferType vengono tutti mappati ai loro nomi all'interno della specifica USB.

Enum

"in"

"out"

EndpointDescriptor

Proprietà

  • indirizzo

    numero

    Indirizzo endpoint.

  • direction

    Direzione

    Direzione di trasferimento.

  • extra_data

    ArrayBuffer

    Dati descrittori aggiuntivi associati a questo endpoint.

  • maximumPacketSize

    numero

    Dimensione massima del pacchetto.

  • pollingInterval

    numero facoltativo

    Intervallo di polling (solo interruzioni e sincrone).

  • dei sottotitoli codificati

    Facoltativo SynchronizationType

    Modalità di sincronizzazione dei trasferimenti (solo sincronizzazione temporale).

  • Tipo di trasferimento.

  • utilizzo

    Facoltativo UsageType

    Suggerimento per l'utilizzo degli endpoint.

EnumerateDevicesAndRequestAccessOptions

Proprietà

  • interfaceId

    numero facoltativo

    L'ID interfaccia a cui richiedere l'accesso. Disponibile solo su ChromeOS. Non ha alcun effetto su altre piattaforme.

  • productId

    numero

    L'ID prodotto.

  • vendorId

    numero

    L'ID del fornitore del dispositivo.

EnumerateDevicesOptions

Proprietà

  • filtri

    DeviceFilter[] facoltativo

    Verrà restituito un dispositivo corrispondente a un determinato filtro. Un elenco di filtri vuoto restituirà tutti i dispositivi per i quali l'app è autorizzata.

  • productId

    numero facoltativo

    Deprecato

    Equivale all'impostazione DeviceFilter.productId.

  • vendorId

    numero facoltativo

    Deprecato

    Equivale all'impostazione DeviceFilter.vendorId.

GenericTransferInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

    I dati da trasmettere (necessari solo per i trasferimenti di output).

  • direction

    Direzione

    La direzione di trasferimento ("in" o "out").

  • endpoint

    numero

    L'indirizzo dell'endpoint di destinazione. L'interfaccia contenente questo endpoint deve essere rivendicata.

  • length

    numero facoltativo

    Il numero massimo di byte da ricevere (richiesto solo dai trasferimenti di input).

  • timeout

    numero facoltativo

    Chrome 43 e versioni successive

    Timeout richiesta (in millisecondi). Il valore predefinito 0 indica l'assenza di timeout.

InterfaceDescriptor

Proprietà

  • alternateSetting

    numero

    Il numero dell'impostazione alternativa dell'interfaccia (il valore predefinito è 0

  • descrizione

    stringa facoltativo

    Descrizione dell'interfaccia.

  • endpoints

    EndpointDescriptor[]

    Endpoint disponibili.

  • extra_data

    ArrayBuffer

    Dati descrittori aggiuntivi associati a questa interfaccia.

  • interfaceClass

    numero

    La classe dell'interfaccia USB.

  • interfaceNumber

    numero

    Il numero dell'interfaccia.

  • interfaceProtocol

    numero

    Il protocollo dell'interfaccia USB.

  • interfaceSubclass

    numero

    La sottoclasse dell'interfaccia USB.

IsochronousTransferInfo

Proprietà

  • packetLength

    numero

    La lunghezza di ciascuno dei pacchetti inclusi in questo trasferimento.

  • pacchetti

    numero

    Il numero totale di pacchetti in questo trasferimento.

  • transferInfo

    GenericTransferInfo

    Parametri di trasferimento. La lunghezza del trasferimento o il buffer dei dati specificato in questo blocco di parametri è diviso lungo i limiti di packetLength per formare i singoli pacchetti del trasferimento.

Recipient

Enum

"endpoint"

RequestType

Enum

"standard"

SynchronizationType

Per le modalità di interruzione e di sincro, SynchronizationType e UsageType vengono mappate ai loro nomi all'interno delle specifiche USB.

Enum

TransferResultInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

    I dati restituiti da un trasferimento di input. undefined per i trasferimenti dell'output.

  • resultCode

    numero facoltativo

    Il valore 0 indica che il trasferimento è stato eseguito correttamente. Altri valori indicano un errore.

TransferType

Enum

UsageType

Enum

"feedback"

Metodi

bulkTransfer()

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

Esegue un trasferimento collettivo sul dispositivo specificato.

Parametri

Ritorni

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

claimInterface()

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

Rivendica un'interfaccia su un dispositivo USB. Prima che i dati possano essere trasferiti a un'interfaccia o agli endpoint associati, è necessario richiedere la proprietà dell'interfaccia. Un solo handle di connessione può rivendicare un'interfaccia alla volta. Se l'interfaccia è già stata rivendicata, questa chiamata avrà esito negativo.

Quando l'interfaccia non è più necessaria, è necessario chiamare releaseInterface.

Parametri

  • Una connessione aperta al dispositivo.

  • interfaceNumber

    numero

    L'interfaccia da rivendicare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

closeDevice()

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

Chiude un handle di connessione. Richiamare le operazioni su un handle dopo che è stato chiuso è un'operazione sicura, ma impedisce l'esecuzione di alcuna azione.

Parametri

Ritorni

  • Promise<void>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

controlTransfer()

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

Esegue un trasferimento di controllo sul dispositivo specificato.

I trasferimenti dei controlli si riferiscono al dispositivo, a un'interfaccia o a un endpoint. Per i trasferimenti a un'interfaccia o a un endpoint è necessario rivendicare l'interfaccia.

Parametri

Ritorni

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

findDevices()

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

Trova i dispositivi USB specificati dal fornitore, dal prodotto e (facoltativamente) dagli ID delle interfacce e, se le autorizzazioni lo consentono, li aprono per l'uso.

Se la richiesta di accesso viene rifiutata o se il dispositivo non si apre, non verrà creato né restituito un handle della connessione.

Chiamare questo metodo equivale a chiamare il numero getDevices seguito da openDevice per ogni dispositivo.

Parametri

Ritorni

  • Promise<ConnectionHandle[]>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

getConfiguration()

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

Consente di acquisire il descrittore di configurazione per la configurazione attualmente selezionata.

Parametri

Ritorni

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

getConfigurations()

Promessa Chrome 47 e versioni successive 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

Restituisce il set completo di descrittori di configurazione del dispositivo.

Parametri

Ritorni

  • Promise<ConfigDescriptor[]>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

getDevices()

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

Enumera i dispositivi USB connessi.

Parametri

  • Le proprietà da cercare sui dispositivi target.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (devices: Device[])=>void

Ritorni

  • Promessa<Dispositivo[]>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

getUserSelectedDevices()

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

Presenta un selettore dispositivo all'utente e restituisce i Device selezionati. Se l'utente annulla, i dispositivi di selezione saranno vuoti. Per visualizzare la finestra di dialogo è necessario un gesto dell'utente. Senza un gesto dell'utente, il callback viene eseguito come se l'utente annullasse.

Parametri

  • Configurazione della finestra di dialogo del selettore dispositivo.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (devices: Device[])=>void

Ritorni

  • Promessa<Dispositivo[]>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

interruptTransfer()

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

Esegue un trasferimento di interruzione sul dispositivo specificato.

Parametri

Ritorni

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

isochronousTransfer()

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

Esegue un trasferimento in sincronismo di tempo sul dispositivo specifico.

Parametri

Ritorni

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

listInterfaces()

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

Elenca tutte le interfacce su un dispositivo USB.

Parametri

Ritorni

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

openDevice()

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

Apre un dispositivo USB restituito da getDevices.

Parametri

Ritorni

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

releaseInterface()

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

Rilascia un'interfaccia rivendicata.

Parametri

  • Una connessione aperta al dispositivo.

  • interfaceNumber

    numero

    L'interfaccia da rilasciare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

requestAccess()

Promessa Deprecata
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

Questa funzione era specifica per ChromeOS e la chiamata su altre piattaforme non andrebbe a buon fine. Questa operazione ora viene eseguita implicitamente come parte di openDevice e la funzione restituirà true su tutte le piattaforme.

Richiede l'accesso dall'intermediario delle autorizzazioni a un dispositivo rivendicato da ChromeOS se l'interfaccia specificata sul dispositivo non viene rivendicata.

Parametri

  • dispositivo

    Dispositivo

    Il Device a cui richiedere l'accesso.

  • interfaceId

    numero

    L'interfaccia specifica richiesta.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (success: boolean)=>void

    • operazione riuscita

      boolean

Ritorni

  • Promise<boolean>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

resetDevice()

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

Tenta di reimpostare il dispositivo USB. Se il ripristino non va a buon fine, il punto di manipolazione della connessione specificato verrà chiuso e il dispositivo USB risulterà disconnesso e poi ricollegato. In questo caso, è necessario chiamare di nuovo getDevices o findDevices per acquisire il dispositivo.

Parametri

  • Un handle della connessione da reimpostare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (success: boolean)=>void

    • operazione riuscita

      boolean

Ritorni

  • Promise<boolean>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

setConfiguration()

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

Seleziona una configurazione dispositivo.

Questa funzione reimposta il dispositivo selezionando una delle configurazioni disponibili. Solo i valori di configurazione superiori a 0 sono validi, tuttavia alcuni dispositivi con bug hanno una configurazione funzionante 0 e questo valore è consentito.

Parametri

  • Una connessione aperta al dispositivo.

  • configurationValue

    numero

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

setInterfaceAlternateSetting()

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

Consente di selezionare un'impostazione alternativa su un'interfaccia rivendicata in precedenza.

Parametri

  • Una connessione aperta al dispositivo su cui è stata rivendicata questa interfaccia.

  • interfaceNumber

    numero

    L'interfaccia da configurare.

  • alternateSetting

    numero

    L'impostazione alternativa da configurare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

Eventi

onDeviceAdded

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

Evento generato quando un dispositivo viene aggiunto al sistema. Gli eventi vengono trasmessi solo alle app e alle estensioni che dispongono dell'autorizzazione per accedere al dispositivo. L'autorizzazione potrebbe essere stata concessa al momento dell'installazione, quando l'utente ha accettato un'autorizzazione facoltativa (vedi permissions.request) o tramite getUserSelectedDevices.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (device: Device)=>void

onDeviceRemoved

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

Evento generato quando un dispositivo viene rimosso dal sistema. Consulta la sezione onDeviceAdded per sapere quali eventi vengono pubblicati.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (device: Device)=>void