chrome.usb

Descrição

Use a API chrome.usb para interagir com dispositivos USB conectados. Essa API oferece acesso a operações USB no contexto de um app. Com ela, os apps podem funcionar como drivers para dispositivos de hardware. Os erros gerados por essa API são informados definindo runtime.lastError e executando o callback regular da função. Nesse caso, os parâmetros regulares do callback serão indefinidos.

Permissões

usb

Tipos

ConfigDescriptor

Propriedades

  • ativo

    booleano

    Chrome 47 ou mais recente

    Esta é a configuração ativa?

  • configurationValue

    número

    O número da configuração.

  • descrição

    string opcional

    Descrição da configuração.

  • extra_data

    ArrayBuffer

    Dados extras do descritor associados a essa configuração.

  • interfaces

    InterfaceDescriptor[]

    Interfaces disponíveis.

  • maxPower

    número

    A potência máxima necessária para este dispositivo em miliampères (mA).

  • remoteWakeup

    booleano

    O dispositivo é compatível com ativação remota.

  • selfPowered

    booleano

    O dispositivo é alimentado por bateria.

ConnectionHandle

Propriedades

  • handle

    número

    Um handle opaco que representa essa conexão com o dispositivo USB e todas as interfaces reivindicadas e transferências pendentes associadas. Um novo identificador é criado sempre que o dispositivo é aberto. O identificador de conexão é diferente de Device.device.

  • productId

    número

    O ID do produto.

  • vendorId

    número

    O ID do fornecedor do dispositivo.

ControlTransferInfo

Propriedades

  • dados

    ArrayBuffer opcional

    Os dados a serem transmitidos (obrigatório apenas para transferências de saída).

  • direção

    Direção

    A direção da transferência ("in" ou "out").

  • index

    número

    O campo wIndex, consulte Ibid.

  • comprimento

    number optional

    O número máximo de bytes a serem recebidos (obrigatório apenas para transferências de entrada).

  • destinatário

    Destinatário

    O destino da transferência. O destino fornecido por index precisa ser reivindicado se for "interface" ou "endpoint".

  • solicitação

    número

    O campo bRequest. Consulte Universal Serial Bus Specification Revision 1.1 § 9.3.

  • requestType

    RequestType

    O tipo de solicitação.

  • timeout

    number optional

    Chrome 43 ou mais recente

    Tempo limite da solicitação (em milissegundos). O valor padrão 0 indica que não há tempo limite.

  • valor

    número

    O campo wValue, consulte Ibid.

Device

Propriedades

  • dispositivo

    número

    Um ID opaco para o dispositivo USB. Ele permanece inalterado até que o dispositivo seja desconectado.

  • manufacturerName

    string

    Chrome 46 ou mais recente

    A string iManufacturer lida do dispositivo, se disponível.

  • productId

    número

    O ID do produto.

  • productName

    string

    Chrome 46 ou mais recente

    A string iProduct lida do dispositivo, se disponível.

  • serialNumber

    string

    Chrome 46 ou mais recente

    A string iSerialNumber lida do dispositivo, se disponível.

  • vendorId

    número

    O ID do fornecedor do dispositivo.

  • version

    número

    Chrome 51 ou mais recente

    A versão do dispositivo (campo bcdDevice).

DeviceFilter

Propriedades

  • interfaceClass

    number optional

    Classe de interface USB, corresponde a qualquer interface no dispositivo.

  • interfaceProtocol

    number optional

    Protocolo de interface USB, verificado apenas se a subclasse da interface corresponder.

  • interfaceSubclass

    number optional

    Subclasse da interface USB, verificada apenas se a classe da interface corresponder.

  • productId

    number optional

    ID do produto do dispositivo, verificado apenas se o ID do fornecedor corresponder.

  • vendorId

    number optional

    ID do fornecedor do dispositivo.

DevicePromptOptions

Propriedades

  • filtros

    DeviceFilter[] opcional

    Filtra a lista de dispositivos apresentada ao usuário. Se vários filtros forem fornecidos, os dispositivos que corresponderem a qualquer um deles serão mostrados.

  • várias

    booleano opcional

    Permita que o usuário selecione vários dispositivos.

Direction

Direction, Recipient, RequestType e TransferType são mapeados para seus homônimos na especificação USB.

Enumeração

"in"

"out"

EndpointDescriptor

Propriedades

  • endereço

    número

    Endereço do endpoint.

  • direção

    Direção

    Direção da transferência.

  • extra_data

    ArrayBuffer

    Dados extras do descritor associados a este endpoint.

  • maximumPacketSize

    número

    Tamanho máximo do pacote.

  • pollingInterval

    number optional

    Intervalo de pesquisa (somente interrupção e isócrono).

  • sincronização

    SynchronizationType opcional

    Modo de sincronização de transferência (somente isócrono).

  • Tipo de transferência.

  • utilização

    UsageType opcional

    Dica de uso do endpoint.

EnumerateDevicesAndRequestAccessOptions

Propriedades

  • interfaceId

    number optional

    O ID da interface para solicitar acesso. Disponível apenas no Chrome OS. Isso não afeta outras plataformas.

  • productId

    número

    O ID do produto.

  • vendorId

    número

    O ID do fornecedor do dispositivo.

EnumerateDevicesOptions

Propriedades

  • filtros

    DeviceFilter[] opcional

    Um dispositivo que corresponda a qualquer filtro será retornado. Uma lista de filtros vazia vai retornar todos os dispositivos em que o app tem permissão.

  • productId

    number optional

    Descontinuado

    Equivale a definir DeviceFilter.productId.

  • vendorId

    number optional

    Descontinuado

    Equivale a definir DeviceFilter.vendorId.

GenericTransferInfo

Propriedades

  • dados

    ArrayBuffer opcional

    Os dados a serem transmitidos (obrigatório apenas para transferências de saída).

  • direção

    Direção

    A direção da transferência ("in" ou "out").

  • endpoint

    número

    O endereço do endpoint de destino. A interface que contém esse endpoint precisa ser reivindicada.

  • comprimento

    number optional

    O número máximo de bytes a serem recebidos (obrigatório apenas para transferências de entrada).

  • timeout

    number optional

    Chrome 43 ou mais recente

    Tempo limite da solicitação (em milissegundos). O valor padrão 0 indica que não há tempo limite.

InterfaceDescriptor

Propriedades

  • alternateSetting

    número

    O número da configuração alternativa da interface (o padrão é 0

  • descrição

    string opcional

    Descrição da interface.

  • endpoints

    EndpointDescriptor[]

    Endpoints disponíveis.

  • extra_data

    ArrayBuffer

    Dados extras do descritor associados a essa interface.

  • interfaceClass

    número

    A classe de interface USB.

  • interfaceNumber

    número

    O número da interface.

  • interfaceProtocol

    número

    O protocolo de interface USB.

  • interfaceSubclass

    número

    A subclasse da interface USB.

IsochronousTransferInfo

Propriedades

  • packetLength

    número

    O comprimento de cada pacote nesta transferência.

  • pacotes

    número

    O número total de pacotes nesta transferência.

  • transferInfo

    GenericTransferInfo

    Parâmetros de transferência. O comprimento da transferência ou o buffer de dados especificado neste bloco de parâmetros é dividido ao longo dos limites packetLength para formar os pacotes individuais da transferência.

Recipient

Enumeração

"device"

"interface"

"endpoint"

"other"

RequestType

Enumeração

"padrão"

"class"

"vendor"

"reserved"

SynchronizationType

Para os modos de interrupção e isócrono, SynchronizationType e UsageType são mapeados para seus homônimos na especificação USB.

Enumeração

"assíncrono"

"adaptive"

"synchronous"

TransferResultInfo

Propriedades

  • dados

    ArrayBuffer opcional

    Os dados retornados por uma transferência de entrada. undefined para transferências de saída.

  • resultCode

    number optional

    Um valor de 0 indica que a transferência foi concluída. Outros valores indicam falha.

TransferType

Enumeração

"controle"

"interrupt"

"isochronous"

"bulk"

UsageType

Enumeração

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Métodos

bulkTransfer()

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

Realiza uma transferência em massa no dispositivo especificado.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

claimInterface()

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

Reivindica uma interface em um dispositivo USB. Antes que os dados possam ser transferidos para uma interface ou endpoints associados, a interface precisa ser reivindicada. Apenas um identificador de conexão pode reivindicar uma interface por vez. Se a interface já estiver reivindicada, essa chamada vai falhar.

releaseInterface precisa ser chamado quando a interface não for mais necessária.

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • interfaceNumber

    número

    A interface a ser reivindicada.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

closeDevice()

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

Fecha um identificador de conexão. Invocar operações em um identificador depois que ele é fechado é uma operação segura, mas não causa nenhuma ação.

Parâmetros

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

controlTransfer()

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

Executa uma transferência de controle no dispositivo especificado.

As transferências de controle se referem ao dispositivo, a uma interface ou a um endpoint. Para transferir para uma interface ou endpoint, é necessário reivindicar a interface.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

findDevices()

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

Encontra dispositivos USB especificados pelo fornecedor, produto e (opcionalmente) IDs de interface e, se as permissões permitirem, os abre para uso.

Se a solicitação de acesso for rejeitada ou o dispositivo não puder ser aberto, um identificador de conexão não será criado nem retornado.

Chamar esse método é equivalente a chamar getDevices seguido de openDevice para cada dispositivo.

Parâmetros

Retorna

  • Promise<ConnectionHandle[]>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getConfiguration()

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

Recebe o descritor da configuração selecionada no momento.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getConfigurations()

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

Retorna o conjunto completo de descritores de configuração do dispositivo.

Parâmetros

Retorna

  • Promise<ConfigDescriptor[]>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getDevices()

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

Enumera dispositivos USB conectados.

Parâmetros

  • As propriedades a serem pesquisadas nos dispositivos de destino.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (devices: Device[]) => void

Retorna

  • Promise<Device[]>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getUserSelectedDevices()

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

Apresenta um seletor de dispositivos ao usuário e retorna os Devices selecionados. Se o usuário cancelar o seletor, os dispositivos vão ficar vazios. É necessário um gesto do usuário para que a caixa de diálogo seja exibida. Sem um gesto do usuário, o callback será executado como se o usuário tivesse cancelado.

Parâmetros

  • Configuração da caixa de diálogo do seletor de dispositivos.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (devices: Device[]) => void

Retorna

  • Promise<Device[]>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

interruptTransfer()

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

Realiza uma transferência de interrupção no dispositivo especificado.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

isochronousTransfer()

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

Realiza uma transferência isócrona no dispositivo específico.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

listInterfaces()

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

Lista todas as interfaces em um dispositivo USB.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

openDevice()

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

Abre um dispositivo USB retornado por getDevices.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

releaseInterface()

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

Libera uma interface reivindicada.

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • interfaceNumber

    número

    A interface a ser lançada.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

requestAccess()

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

Essa função era específica do Chrome OS e falhava quando chamada em outras plataformas. Agora, essa operação é realizada implicitamente como parte de openDevice, e essa função vai retornar true em todas as plataformas.

Solicita acesso do broker de permissões a um dispositivo reivindicado pelo Chrome OS se a interface especificada no dispositivo não for reivindicada.

Parâmetros

  • dispositivo

    Dispositivo

    O Device para solicitar acesso.

  • interfaceId

    número

    A interface específica solicitada.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      booleano

Retorna

  • Promise<boolean>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

resetDevice()

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

Tenta redefinir o dispositivo USB. Se a redefinição falhar, o identificador de conexão será fechado, e o dispositivo USB vai parecer desconectado e reconectado. Nesse caso, getDevices ou findDevices precisa ser chamado novamente para adquirir o dispositivo.

Parâmetros

  • Um identificador de conexão a ser redefinido.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      booleano

Retorna

  • Promise<boolean>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setConfiguration()

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

Selecione uma configuração de dispositivo.

Essa função redefine o dispositivo selecionando uma das configurações disponíveis. Apenas valores de configuração maiores que 0 são válidos, mas alguns dispositivos com bugs têm uma configuração 0 funcional. Por isso, esse valor é permitido.

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • configurationValue

    número

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setInterfaceAlternateSetting()

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

Seleciona uma configuração alternativa em uma interface reivindicada anteriormente.

Parâmetros

  • Uma conexão aberta com o dispositivo em que essa interface foi reivindicada.

  • interfaceNumber

    número

    A interface a ser configurada.

  • alternateSetting

    número

    A configuração alternativa a ser definida.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onDeviceAdded

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

Evento gerado quando um dispositivo é adicionado ao sistema. Os eventos só são transmitidos para apps e extensões que têm permissão para acessar o dispositivo. A permissão pode ter sido concedida no momento da instalação, quando o usuário aceitou uma permissão opcional (consulte permissions.request) ou por getUserSelectedDevices.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (device: Device) => void

onDeviceRemoved

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

Evento gerado quando um dispositivo é removido do sistema. Consulte onDeviceAdded para saber quais eventos são entregues.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (device: Device) => void