chrome.usb

Descrizione

Utilizza l'API chrome.usb per interagire con i dispositivi USB collegati. Questa API fornisce l'accesso alle operazioni USB dal contesto di un'app. Tramite questa API, le app possono funzionare come driver per i dispositivi hardware. Gli errori generati da questa API vengono segnalati impostando runtime.lastError ed eseguendo il normale callback della funzione. In questo caso, i parametri regolari della chiamata di ritorno non saranno definiti.

Autorizzazioni

usb

Tipi

ConfigDescriptor

Proprietà

  • attivo

    booleano

    Chrome 47 e versioni successive

    Questa è la configurazione attiva?

  • configurationValue

    numero

    Il numero di configurazione.

  • descrizione

    stringa facoltativo

    Descrizione della configurazione.

  • extra_data

    ArrayBuffer

    Dati dei descrittori aggiuntivi associati a questa configurazione.

  • interfacce

    InterfaceDescriptor[]

    Interfacce disponibili.

  • maxPower

    numero

    La potenza massima richiesta da questo dispositivo in milliampere (mA).

  • remoteWakeup

    booleano

    Il dispositivo supporta l'attivazione da remoto.

  • selfPowered

    booleano

    Il dispositivo è autoalimentato.

ConnectionHandle

Proprietà

  • handle

    numero

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

  • productId

    numero

    L'ID del prodotto.

  • vendorId

    numero

    L'ID del fornitore del dispositivo.

ControlTransferInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

    I dati da trasmettere (obbligatorio solo per i trasferimenti in uscita).

  • direction

    Direzione

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

  • indice

    numero

    Il campo wIndex, vedi Ibid.

  • lunghezza

    numero facoltativo

    Il numero massimo di byte da ricevere (richiesto solo per i 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, vedi Universal Serial Bus Specification Revision 1.1 § 9.3.

  • requestType

    RequestType

    Il tipo di richiesta.

  • timeout

    number facoltativo

    Chrome 43 e versioni successive

    Timeout richiesta (in millisecondi). Il valore predefinito 0 indica che non è impostato alcun timeout.

  • valore

    numero

    Il campo wValue, consulta Ibid.

Device

Proprietà

  • dispositivo

    numero

    Un ID opaco per il dispositivo USB. e rimane invariata finché il dispositivo non viene scollegato dall'alimentazione.

  • 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

    number facoltativo

    Classe di interfaccia USB, corrisponde a qualsiasi interfaccia sul dispositivo.

  • interfaceProtocol

    numero facoltativo

    Protocollo di interfaccia USB, controllato 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 del dispositivo, controllato solo se l'ID fornitore corrisponde.

  • vendorId

    numero facoltativo

    ID fornitore del dispositivo.

DevicePromptOptions

Proprietà

  • filtri

    DeviceFilter[] facoltativo

    Filtra l'elenco dei dispositivi presentati all'utente. Se sono disponibili più filtri, verranno visualizzati i dispositivi che corrispondono a un filtro qualsiasi.

  • multiple

    booleano facoltativo

    Consenti all'utente di selezionare più dispositivi.

Direction

Direction, Recipient, RequestType e TransferType corrispondono tutti ai rispettivi nomi all'interno della specifica USB.

Enum

"in"

"out"

EndpointDescriptor

Proprietà

  • indirizzo

    numero

    Indirizzo endpoint.

  • direction

    Direzione

    Direzione di trasferimento.

  • extra_data

    ArrayBuffer

    Dati dei descrittori aggiuntivi associati a questo endpoint.

  • maximumPacketSize

    numero

    Dimensione massima del pacchetto.

  • pollingInterval

    number facoltativo

    Intervallo di polling (solo interrupt e incrono).

  • dell'audiodescrizione

    SynchronizationType facoltativo

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

  • Tipo di trasferimento.

  • utilizzo

    UsageType facoltativo

    Suggerimento per l'utilizzo dell'endpoint.

EnumerateDevicesAndRequestAccessOptions

Proprietà

  • interfaceId

    numero facoltativo

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

  • productId

    numero

    L'ID del prodotto.

  • vendorId

    numero

    L'ID del fornitore del dispositivo.

EnumerateDevicesOptions

Proprietà

  • filtri

    DeviceFilter[] facoltativo

    Verrà restituito un dispositivo che corrisponde a qualsiasi filtro specificato. Un elenco di filtri vuoto restituirà tutti i dispositivi per cui l'app ha l'autorizzazione.

  • productId

    numero facoltativo

    Obsoleto

    Equivalente all'impostazione DeviceFilter.productId.

  • vendorId

    number facoltativo

    Obsoleta

    Equivalente all'impostazione DeviceFilter.vendorId.

GenericTransferInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

    I dati da trasmettere (obbligatorio solo per i trasferimenti in uscita).

  • direction

    Direzione

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

  • endpoint

    numero

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

  • lunghezza

    numero facoltativo

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

  • timeout

    number facoltativo

    Chrome 43 e versioni successive

    Timeout richiesta (in millisecondi). Il valore predefinito 0 indica che non è impostato alcun 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 dei descrittori aggiuntivi associati a questa interfaccia.

  • interfaceClass

    numero

    La classe dell'interfaccia USB.

  • interfaceNumber

    numero

    Il numero di 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 in questo trasferimento.

  • pacchetti

    numero

    Il numero totale di pacchetti in questo trasferimento.

  • transferInfo

    GenericTransferInfo

    Trasferisci i parametri. La lunghezza di trasferimento o il buffer di dati specificati in questo blocco di parametri sono suddivisi lungo i limiti di packetLength per formare i singoli pacchetti del trasferimento.

Recipient

Enum

"endpoint"

RequestType

Enum

"standard"

"vendor"

SynchronizationType

Per le modalità di interruzione e di sincronizzazione, SynchronizationType e UsageType mappano ai rispettivi nomi all'interno della specifica USB.

Enum

"adattabile"

"synchronous"

TransferResultInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

    I dati restituiti da un trasferimento di input. undefined per i trasferimenti in uscita.

  • resultCode

    numero facoltativo

    Un valore 0 indica che il trasferimento è andato a buon fine. Altri valori indicano un errore.

TransferType

Enum

UsageType

Enum

"data"

"explicitFeedback"

"periodic"

"notification"

Metodi

bulkTransfer()

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

Esegue un trasferimento collettivo sul dispositivo specificato.

Parametri

Resi

  • Promise<TransferResultInfo>

    Chrome 116 e versioni successive

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

claimInterface()

Promesso 
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, l'interfaccia deve essere rivendicata. Solo un handle di connessione può rivendicare un'interfaccia in un determinato momento. Se l'interfaccia è già stata rivendicata, questa chiamata non andrà a buon fine.

releaseInterface deve essere chiamato quando l'interfaccia non è più necessaria.

Parametri

  • Una connessione aperta al dispositivo.

  • interfaceNumber

    numero

    L'interfaccia da rivendicare.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 116 e versioni successive

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

closeDevice()

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

Chiude un handle di connessione. L'invocazione di operazioni su un handle dopo la sua chiusura è un'operazione sicura, ma non comporta alcuna azione.

Parametri

Resi

  • Promise<void>

    Chrome 116 e versioni successive

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

controlTransfer()

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

Esegue un trasferimento del controllo sul dispositivo specificato.

Per trasferimenti di controllo si intendono il dispositivo, un'interfaccia o un endpoint. I trasferimenti a un'interfaccia o a un endpoint richiedono la rivendicazione dell'interfaccia.

Parametri

Resi

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 e versioni successive

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

findDevices()

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

Individua i dispositivi USB specificati dal fornitore, dal prodotto e (facoltativamente) dagli ID interfaccia e, se le autorizzazioni lo consentono, li apre per l'utilizzo.

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

Questo metodo equivale a chiamare getDevices seguito da openDevice per ogni dispositivo.

Parametri

Resi

  • Promise&lt;ConnectionHandle[]&gt;

    Chrome 116 e versioni successive

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

getConfiguration()

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

Recupera il descrittore di configurazione per la configurazione attualmente selezionata.

Parametri

Resi

  • Chrome 116 e versioni successive

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

getConfigurations()

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

Restituisce l'insieme completo dei descrittori di configurazione del dispositivo.

Parametri

Resi

  • Promise&lt;ConfigDescriptor[]&gt;

    Chrome 116 e versioni successive

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

getDevices()

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

Elenca 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

Resi

  • Promesso<Dispositivo[]>

    Chrome 116 e versioni successive

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

getUserSelectedDevices()

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

Mostra all'utente un selettore di dispositivi e restituisce i Device selezionati. Se l'utente annulla l'operazione, i dispositivi di selezione saranno vuoti. Per la visualizzazione della finestra di dialogo è necessario un gesto dell'utente. Senza un gesto dell'utente, il callback verrà eseguito come se l'utente avesse annullato.

Parametri

  • Configurazione della finestra di dialogo del selettore di dispositivi.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (devices: Device[]) => void

Resi

  • Promesso<Dispositivo[]>

    Chrome 116 e versioni successive

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

interruptTransfer()

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

Esegue un trasferimento di interruzione sul dispositivo specificato.

Parametri

Resi

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 e versioni successive

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

isochronousTransfer()

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

Esegue un trasferimento isocrono sul dispositivo specifico.

Parametri

Resi

  • Chrome 116 e versioni successive

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

listInterfaces()

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

Elenca tutte le interfacce presenti in un dispositivo USB.

Parametri

Resi

  • Chrome 116 e versioni successive

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

openDevice()

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

Apre un dispositivo USB restituito da getDevices.

Parametri

Resi

  • Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le 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

Resi

  • Promise<void>

    Chrome 116 e versioni successive

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

requestAccess()

Promesso Deprecato
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

Questa funzione era specifica per ChromeOS e la sua chiamata su altre piattaforme non andava a buon fine. Ora questa operazione viene eseguita implicitamente nell'ambito di openDevice e questa funzione restituirà true su tutte le piattaforme.

Richiede l'accesso dal broker delle autorizzazioni a un dispositivo rivendicato da ChromeOS se l'interfaccia specificata sul dispositivo non è rivendicata.

Parametri

  • dispositivo

    Dispositivo

    Il Device per cui richiedere l'accesso.

  • interfaceId

    numero

    La particolare interfaccia richiesta.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (success: boolean) => void

    • operazione riuscita

      booleano

Resi

  • Promise&lt;boolean&gt;

    Chrome 116 e versioni successive

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

resetDevice()

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

Prova a reimpostare il dispositivo USB. Se il ripristino non riesce, l'handle di connessione specificato verrà chiuso e il dispositivo USB sembrerà essere disconnesso e poi ricollegato. In questo caso, è necessario chiamare di nuovo getDevices o findDevices per acquisire il dispositivo.

Parametri

  • Un handle di connessione da reimpostare.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (success: boolean) => void

    • operazione riuscita

      booleano

Resi

  • Promise&lt;boolean&gt;

    Chrome 116 e versioni successive

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

setConfiguration()

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

Seleziona una configurazione del dispositivo.

Questa funzione reimposta il dispositivo in modo efficace selezionando una delle configurazioni disponibili del dispositivo. Solo i valori di configurazione maggiori di 0 sono validi, tuttavia alcuni dispositivi con bug presentano una configurazione funzionante (0), pertanto questo valore è consentito.

Parametri

  • Una connessione aperta al dispositivo.

  • configurationValue

    numero

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 116 e versioni successive

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

setInterfaceAlternateSetting()

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

seleziona un'impostazione alternativa in 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

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 116 e versioni successive

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le 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 hanno l'autorizzazione ad 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 onDeviceAdded per scoprire quali eventi vengono pubblicati.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (device: Device) => void