chrome.usb

Descrizione

Utilizza l'API chrome.usb per interagire con i dispositivi USB connessi. Questa API consente di accedere alle operazioni USB dall'interno di un'app. Utilizzando questa API, le app possono fungere da 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 normali del callback 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 la riattivazione remota.

  • selfPowered

    booleano

    Il dispositivo è autoalimentato.

ConnectionHandle

Proprietà

  • handle

    numero

    Un handle opaco che rappresenta questa connessione al dispositivo USB e tutte le interfacce dichiarate associate e i trasferimenti in attesa. Ogni volta che apri il dispositivo viene creato un nuovo handle. L'handle di 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 (richiesti solo per i trasferimenti di output).

  • 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 Revisione 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 nessun timeout.

  • valore

    numero

    Il campo wValue, vedi 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 del 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 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 dispositivo, controllato solo se l'ID fornitore corrisponde.

  • vendorId

    numero facoltativo

    ID del 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

    numero 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 degli endpoint.

EnumerateDevicesAndRequestAccessOptions

Proprietà

  • interfaceId

    numero facoltativo

    L'ID interfaccia per 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 corrispondente a un determinato filtro. Un elenco di filtri vuoto restituirà tutti i dispositivi per cui l'app è autorizzata.

  • productId

    numero facoltativo

    Obsoleta

    Equivale all'impostazione DeviceFilter.productId.

  • vendorId

    numero facoltativo

    Obsoleta

    Equivale all'impostazione DeviceFilter.vendorId.

GenericTransferInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

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

  • direction

    Direzione

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

  • endpoint

    numero

    L'indirizzo dell'endpoint di destinazione. È necessario rivendicare l'interfaccia contenente questo endpoint.

  • lunghezza

    numero facoltativo

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

  • timeout

    numero facoltativo

    Chrome 43 e versioni successive .

    Timeout richiesta (in millisecondi). Il valore predefinito 0 indica nessun timeout.

InterfaceDescriptor

Proprietà

  • alternateSetting

    numero

    Il numero di 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

    Parametri di trasferimento. 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

"dispositivo"

"interfaccia"

"endpoint"

"altro"

RequestType

Enum

"standard"

"classe"

"fornitore"

"prenotato"

SynchronizationType

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

Enum

"asincrono"

"adattiva"

"sincrono"

TransferResultInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

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

  • resultCode

    numero facoltativo

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

TransferType

Enum

"control"

"interrupt"

"isocrono"

"collettivo"

UsageType

Enum

"dati"

"feedback"

"explicitFeedback"

"periodic"

"notifica"

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, è necessario rivendicare l'interfaccia. Un solo 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 dovrebbe essere chiamato quando l'interfaccia non è più necessaria.

Parametri

  • Una connessione aperta al dispositivo.

  • interfaceNumber

    numero

    L'interfaccia da rivendicare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<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. Chiamare operazioni su un handle dopo averlo chiuso è un'operazione sicura, ma non comporta alcuna azione.

Parametri

Resi

  • Promesso<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()

Promesso .
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,
)

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

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

  • 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.

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()

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

Sono elencati i dispositivi USB connessi.

Parametri

  • Le proprietà da cercare sui dispositivi di destinazione.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (devices: Device[]) => void

Resi

  • Prometti <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()

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

Presenta un selettore dispositivo all'utente e restituisce i Device selezionati. Se l'utente annulla l'operazione, i dispositivi di selezione saranno vuoti. Per visualizzare la 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 dispositivo.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (devices: Device[]) => void

Resi

  • Prometti <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()

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

Viene eseguito un trasferimento sincrono sul dispositivo specifico.

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.

listInterfaces()

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

Elenca tutte le interfacce presenti in un dispositivo USB.

Parametri

Resi

  • Promise&lt;InterfaceDescriptor[]&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.

openDevice()

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

Apre un dispositivo USB restituito da getDevices.

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.

releaseInterface()

Promesso .
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

  • Promesso<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 di ChromeOS e non sarebbe possibile chiamarla su altre piattaforme. Questa operazione ora viene eseguita implicitamente come parte di openDevice e questa funzione restituirà true su tutte le piattaforme.

Richiedi l'accesso dal broker di autorizzazioni a un dispositivo rivendicato da Chrome OS se l'interfaccia specificata sul dispositivo non è stata rivendicata.

Parametri

  • dispositivo

    Dispositivo

    Il Device per cui richiedere l'accesso.

  • interfaceId

    numero

    La specifica 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,
)

Tenta di reimpostare il dispositivo USB. Se il ripristino non va a buon fine, l'handle di 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 di connessione da reimpostare.

  • 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.

setConfiguration()

Promesso .
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

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<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

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<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 soltanto 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. Vedi onDeviceAdded per sapere quali eventi vengono pubblicati.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (device: Device) => void