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
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
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
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
Il tipo di richiesta.
-
timeout
numero facoltativo
Chrome 43 e versioni successiveTimeout 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 successiveLa stringa iManufacturer letta dal dispositivo, se disponibile.
-
productId
numero
L'ID prodotto.
-
productName
stringa
Chrome 46 e versioni successiveLa stringa iProduct letta dal dispositivo, se disponibile.
-
serialNumber
stringa
Chrome 46 e versioni successiveLa stringa iSerialNumber letta dal dispositivo, se disponibile.
-
vendorId
numero
L'ID del fornitore del dispositivo.
-
versione
numero
Chrome 51 e versioni successiveLa 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 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
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
DeprecatoEquivale all'impostazione
DeviceFilter.productId
. -
vendorId
numero facoltativo
DeprecatoEquivale all'impostazione
DeviceFilter.vendorId
.
GenericTransferInfo
Proprietà
-
dati
ArrayBuffer facoltativo
I dati da trasmettere (necessari solo per i trasferimenti di output).
-
direction
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 successiveTimeout 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
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
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()
chrome.usb.bulkTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
Esegue un trasferimento collettivo sul dispositivo specificato.
Parametri
-
handle
Una connessione aperta al dispositivo.
-
transferInfo
I parametri di trasferimento.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(info: TransferResultInfo) => void
-
informazioni
-
Ritorni
-
Promise<TransferResultInfo>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
claimInterface()
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
-
handle
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
closeDevice()
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
-
handle
La
ConnectionHandle
da chiudere. -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
controlTransfer()
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
-
handle
Una connessione aperta al dispositivo.
-
transferInfo
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(info: TransferResultInfo) => void
-
informazioni
-
Ritorni
-
Promise<TransferResultInfo>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
findDevices()
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
-
Le proprietà da cercare sui dispositivi target.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(handles: ConnectionHandle[]) => void
-
handle
-
Ritorni
-
Promise<ConnectionHandle[]>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getConfiguration()
chrome.usb.getConfiguration(
handle: ConnectionHandle,
callback?: function,
)
Consente di acquisire il descrittore di configurazione per la configurazione attualmente selezionata.
Parametri
-
handle
Una connessione aperta al dispositivo.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(config: ConfigDescriptor) => void
-
config
-
Ritorni
-
Promise<ConfigDescriptor>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getConfigurations()
chrome.usb.getConfigurations(
device: Device,
callback?: function,
)
Restituisce il set completo di descrittori di configurazione del dispositivo.
Parametri
-
dispositivo
Il campo
Device
da cui recuperare i descrittori. -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(configs: ConfigDescriptor[]) => void
-
configs
-
Ritorni
-
Promise<ConfigDescriptor[]>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getDevices()
chrome.usb.getDevices(
options: EnumerateDevicesOptions,
callback?: function,
)
Enumera i dispositivi USB connessi.
Parametri
-
opzioni
Le proprietà da cercare sui dispositivi target.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(devices: Device[]) => void
-
dispositivi
-
Ritorni
-
Promessa<Dispositivo[]>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getUserSelectedDevices()
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
-
opzioni
Configurazione della finestra di dialogo del selettore dispositivo.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(devices: Device[]) => void
-
dispositivi
-
Ritorni
-
Promessa<Dispositivo[]>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
interruptTransfer()
chrome.usb.interruptTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
Esegue un trasferimento di interruzione sul dispositivo specificato.
Parametri
-
handle
Una connessione aperta al dispositivo.
-
transferInfo
I parametri di trasferimento.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(info: TransferResultInfo) => void
-
informazioni
-
Ritorni
-
Promise<TransferResultInfo>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
isochronousTransfer()
chrome.usb.isochronousTransfer(
handle: ConnectionHandle,
transferInfo: IsochronousTransferInfo,
callback?: function,
)
Esegue un trasferimento in sincronismo di tempo sul dispositivo specifico.
Parametri
-
handle
Una connessione aperta al dispositivo.
-
transferInfo
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(info: TransferResultInfo) => void
-
informazioni
-
Ritorni
-
Promise<TransferResultInfo>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
listInterfaces()
chrome.usb.listInterfaces(
handle: ConnectionHandle,
callback?: function,
)
Elenca tutte le interfacce su un dispositivo USB.
Parametri
-
handle
Una connessione aperta al dispositivo.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(descriptors: InterfaceDescriptor[]) => void
-
descriptors
-
Ritorni
-
Promise<InterfaceDescriptor[]>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
openDevice()
chrome.usb.openDevice(
device: Device,
callback?: function,
)
Apre un dispositivo USB restituito da getDevices
.
Parametri
-
dispositivo
Il
Device
da aprire. -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(handle: ConnectionHandle) => void
-
handle
-
Ritorni
-
Promise<ConnectionHandle>
Chrome 116 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
releaseInterface()
chrome.usb.releaseInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
Rilascia un'interfaccia rivendicata.
Parametri
-
handle
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
requestAccess()
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
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
resetDevice()
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
-
handle
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setConfiguration()
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
-
handle
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setInterfaceAlternateSetting()
chrome.usb.setInterfaceAlternateSetting(
handle: ConnectionHandle,
interfaceNumber: number,
alternateSetting: number,
callback?: function,
)
Consente di selezionare un'impostazione alternativa su un'interfaccia rivendicata in precedenza.
Parametri
-
handle
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 successiveLe 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
-
dispositivo
-
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
-
dispositivo
-