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. Utilizzando 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 del callback non saranno definiti.

Autorizzazioni

usb

Tipi

ConfigDescriptor

Proprietà

  • attivo

    booleano

    Chrome 47+

    È la configurazione attiva?

  • configurationValue

    numero

    Il numero di configurazione.

  • descrizione

    stringa facoltativa

    Descrizione della configurazione.

  • extra_data

    ArrayBuffer

    Dati descrittori aggiuntivi associati a questa configurazione.

  • interfacce

    InterfaceDescriptor[]

    Interfacce disponibili.

  • maxPower

    numero

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

  • remoteWakeup

    booleano

    Il dispositivo supporta la riattivazione 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 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 fornitore del dispositivo.

ControlTransferInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

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

  • direction

    Direzione

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

  • indice

    numero

    Il campo wIndex, vedi Ibid.

  • lunghezza

    number (facoltativo)

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

  • destinatario

    Destinatario

    La destinazione del trasferimento. Il target fornito 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 o versioni successive

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

  • valore

    numero

    Il campo wValue, vedi Ibid.

Device

Proprietà

  • dispositivo

    numero

    Un ID opaco per il dispositivo USB. Rimane invariato finché il dispositivo non viene scollegato.

  • manufacturerName

    stringa

    Chrome 46 o versioni successive

    La stringa iManufacturer letta dal dispositivo, se disponibile.

  • productId

    numero

    L'ID prodotto.

  • productName

    stringa

    Chrome 46 o versioni successive

    La stringa iProduct letta dal dispositivo, se disponibile.

  • serialNumber

    stringa

    Chrome 46 o versioni successive

    La stringa iSerialNumber letta dal dispositivo, se disponibile.

  • vendorId

    numero

    L'ID fornitore del dispositivo.

  • versione

    numero

    Chrome 51+

    La versione del dispositivo (campo bcdDevice).

DeviceFilter

Proprietà

  • interfaceClass

    number (facoltativo)

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

  • interfaceProtocol

    number (facoltativo)

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

  • interfaceSubclass

    number (facoltativo)

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

  • productId

    number (facoltativo)

    ID prodotto del dispositivo, controllato solo se l'ID fornitore corrisponde.

  • vendorId

    number (facoltativo)

    ID fornitore del dispositivo.

DevicePromptOptions

Proprietà

  • filtri

    DeviceFilter[] facoltativo

    Filtra l'elenco dei dispositivi presentati all'utente. Se vengono forniti più filtri, verranno visualizzati i dispositivi che corrispondono a uno qualsiasi dei filtri.

  • multiple

    booleano facoltativo

    Consenti all'utente di selezionare più dispositivi.

Direction

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

Enum

"in"

"out"

EndpointDescriptor

Proprietà

  • indirizzo

    numero

    Indirizzo endpoint.

  • direction

    Direzione

    Direzione del trasferimento.

  • extra_data

    ArrayBuffer

    Dati descrittori aggiuntivi associati a questo endpoint.

  • maximumPacketSize

    numero

    Dimensione massima del pacchetto.

  • pollingInterval

    number (facoltativo)

    Intervallo di polling (solo interrupt e isocrono).

  • sincronizzazione

    SynchronizationType facoltativo

    Modalità di sincronizzazione del trasferimento (solo isocrona).

  • Tipo di trasferimento.

  • utilizzo

    UsageType facoltativo

    Suggerimento sull'utilizzo dell'endpoint.

EnumerateDevicesAndRequestAccessOptions

Proprietà

  • interfaceId

    number (facoltativo)

    L'ID dell'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 fornitore del dispositivo.

EnumerateDevicesOptions

Proprietà

  • filtri

    DeviceFilter[] facoltativo

    Verrà restituito un dispositivo corrispondente a un filtro specificato. Un elenco di filtri vuoto restituirà tutti i dispositivi per cui l'app dispone dell'autorizzazione.

  • productId

    number (facoltativo)

    Obsoleto

    Equivalente all'impostazione DeviceFilter.productId.

  • vendorId

    number (facoltativo)

    Obsoleto

    Equivalente all'impostazione DeviceFilter.vendorId.

GenericTransferInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

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

  • 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

    number (facoltativo)

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

  • timeout

    number (facoltativo)

    Chrome 43 o versioni successive

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

InterfaceDescriptor

Proprietà

  • alternateSetting

    numero

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

  • descrizione

    stringa facoltativa

    Descrizione dell'interfaccia.

  • endpoints

    EndpointDescriptor[]

    Endpoint disponibili.

  • extra_data

    ArrayBuffer

    Dati descrittori aggiuntivi associati a questa interfaccia.

  • interfaceClass

    numero

    La classe di 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 ciascun pacchetto in questo trasferimento.

  • pacchetti

    numero

    Il numero totale di pacchetti in questo trasferimento.

  • transferInfo

    GenericTransferInfo

    Trasferisci i parametri. La lunghezza del trasferimento o il buffer di dati specificato in questo blocco di parametri viene suddiviso lungo i limiti di packetLength per formare i singoli pacchetti del trasferimento.

Recipient

Enum

"device"

"interfaccia"

"endpoint"

"other"

RequestType

Enum

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

Per le modalità di interruzione e isocrona, SynchronizationType e UsageType corrispondono ai rispettivi omonimi all'interno della specifica USB.

Enum

"asynchronous"

"adaptive"

"synchronous"

TransferResultInfo

Proprietà

  • dati

    ArrayBuffer facoltativo

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

  • resultCode

    number (facoltativo)

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

TransferType

Enum

"control"

"interrompi"

"isocrono"

"bulk"

UsageType

Enum

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Metodi

bulkTransfer()

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

Esegue un trasferimento collettivo sul dispositivo specificato.

Parametri

Resi

  • Chrome 116+

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

claimInterface()

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

Rivendica un'interfaccia su un dispositivo USB. Prima che i dati possano essere trasferiti a un'interfaccia o a endpoint associati, l'interfaccia deve essere rivendicata. Un solo handle di connessione può rivendicare un'interfaccia in un dato momento. Se l'interfaccia è già stata rivendicata, la 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

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 116+

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

closeDevice()

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

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

Parametri

Resi

  • Promise<void>

    Chrome 116+

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

controlTransfer()

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

Esegue un trasferimento del controllo sul dispositivo specificato.

I trasferimenti di controllo si riferiscono al dispositivo, a un'interfaccia o a un endpoint. I trasferimenti a un'interfaccia o a un endpoint richiedono che l'interfaccia venga rivendicata.

Parametri

Resi

  • Chrome 116+

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

findDevices()

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

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 non è possibile aprire una connessione al dispositivo, non verrà creato o restituito un handle di connessione.

La chiamata a questo metodo equivale alla chiamata a getDevices seguita da openDevice per ogni dispositivo.

Parametri

Resi

  • Promise<ConnectionHandle[]>

    Chrome 116+

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

getConfiguration()

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

Ottiene il descrittore di configurazione per la configurazione attualmente selezionata.

Parametri

Resi

  • Chrome 116+

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

getConfigurations()

Promise Chrome 47+ 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

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

Parametri

Resi

  • Promise<ConfigDescriptor[]>

    Chrome 116+

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

getDevices()

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

Elenca 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

  • Promise<Device[]>

    Chrome 116+

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

getUserSelectedDevices()

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

Mostra all'utente un selettore di dispositivi e restituisce gli Device selezionati. Se l'utente annulla la selezione, i dispositivi di prelievo 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 l'operazione.

Parametri

  • Configurazione della finestra di dialogo del selettore di dispositivi.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (devices: Device[]) => void

Resi

  • Promise<Device[]>

    Chrome 116+

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

interruptTransfer()

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

Esegue un trasferimento di interruzione sul dispositivo specificato.

Parametri

Resi

  • Chrome 116+

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

isochronousTransfer()

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

Esegue un trasferimento isocrono sul dispositivo specifico.

Parametri

Resi

  • Chrome 116+

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

listInterfaces()

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

Elenca tutte le interfacce di un dispositivo USB.

Parametri

Resi

  • Chrome 116+

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

openDevice()

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

Apre un dispositivo USB restituito da getDevices.

Parametri

Resi

  • Chrome 116+

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

releaseInterface()

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

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+

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

requestAccess()

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

Questa funzione era specifica di ChromeOS e la sua chiamata su altre piattaforme non andava a buon fine. Questa operazione viene ora 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 Chrome OS se l'interfaccia specificata sul dispositivo non è rivendicata.

Parametri

  • dispositivo

    Dispositivo

    L'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

      booleano

Resi

  • Promise<boolean>

    Chrome 116+

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

resetDevice()

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

Tenta di ripristinare il dispositivo USB. Se il ripristino non riesce, l'handle di connessione specificato verrà chiuso e il dispositivo USB sembrerà disconnesso e poi riconnesso. 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<boolean>

    Chrome 116+

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

setConfiguration()

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

Seleziona una configurazione del dispositivo.

Questa funzione ripristina effettivamente il dispositivo selezionando una delle configurazioni disponibili. Sono validi solo i valori di configurazione superiori a 0, tuttavia alcuni dispositivi con bug hanno 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

  • Promise<void>

    Chrome 116+

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

setInterfaceAlternateSetting()

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

Seleziona un'impostazione alternativa su un'interfaccia rivendicata in precedenza.

Parametri

  • Una connessione aperta al dispositivo in 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

  • Promise<void>

    Chrome 116+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, 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 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 onDeviceAdded per scoprire quali eventi vengono pubblicati.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (device: Device) => void