chrome.usb

Descrição

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

Permissões

usb

Tipos

ConfigDescriptor

Propriedades

  • ativo

    boolean

    Chrome 47 ou mais recente

    Esta é a configuração ativa?

  • configurationValue

    number

    O número de configuração.

  • descrição

    string opcional

    Descrição da configuração.

  • extra_data

    ArrayBuffer

    Dados de descritor extras associados a esta configuração.

  • interfaces

    InterfaceDescriptor[]

    Interfaces disponíveis.

  • maxPower

    number

    A potência máxima necessária para o dispositivo em miliams (mA).

  • remoteWakeup

    boolean

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

  • selfPowered

    boolean

    O dispositivo é autoligado.

ConnectionHandle

Propriedades

  • identificador

    number

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

  • productId

    number

    O ID do produto.

  • vendorId

    number

    O ID do fornecedor do dispositivo.

ControlTransferInfo

Propriedades

  • dados

    ArrayBuffer opcional

    Os dados a serem transmitidos (necessários apenas para transferências de saída).

  • direction

    Direção

    Direção da baldeação ("in" ou "out").

  • índice

    number

    O campo wIndex, consulte Ibid.

  • length

    número opcional

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

  • destinatário

    Destinatário

    O destino da transferência. A meta fornecida por index precisa ser reivindicada se "interface" ou "endpoint".

  • request

    number

    O campo bRequest, consulte Revisão da especificação do barramento serial universal 1.1 § 9.3.

  • requestType

    RequestType

    O tipo de solicitação.

  • pedido de tempo

    número opcional

    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

    number

    O campo wValue, consulte Ibid.

Device

Propriedades

  • dispositivo

    number

    Um ID opaco para o dispositivo USB. Ela permanece inalterada até que o dispositivo seja desconectado.

  • manufacturerName

    string

    Chrome 46 ou mais recente

    String do iManufacturer lida no dispositivo, se disponível.

  • productId

    number

    O ID do produto.

  • productName

    string

    Chrome 46 ou mais recente

    String iProduct lida no dispositivo, se disponível.

  • serialNumber

    string

    Chrome 46 ou mais recente

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

  • vendorId

    number

    O ID do fornecedor do dispositivo.

  • versão

    number

    Chrome 51 ou mais recente

    A versão do dispositivo (campo bcdDevice).

DeviceFilter

Propriedades

  • interfaceClass

    número opcional

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

  • interfaceProtocol

    número opcional

    Protocolo de interface USB, marcado apenas se a subclasse de interface corresponder.

  • interfaceSubclass

    número opcional

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

  • productId

    número opcional

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

  • vendorId

    número opcional

    ID do fornecedor do dispositivo.

DevicePromptOptions

Propriedades

  • filtros

    DeviceFilter[] opcional

    Filtrar a lista de dispositivos apresentada ao usuário. Se vários filtros forem fornecidos, os dispositivos correspondentes a qualquer filtro serão exibidos.

  • várias

    booleano opcional

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

Direction

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

Tipo enumerado

EndpointDescriptor

Propriedades

  • endereço

    number

    Endereço do endpoint.

  • direction

    Direção

    Direção da transferência.

  • extra_data

    ArrayBuffer

    Dados de descritor extras associados a este endpoint.

  • maximumPacketSize

    number

    Tamanho máximo do pacote.

  • pollingInterval

    número opcional

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

  • sincronização

    SynchronizationType opcional

    Modo de sincronização de transferência (apenas isocrono).

  • digitar

    TransferType

    Tipo de transferência.

  • utilização

    UsageType opcional

    Dica de uso do endpoint.

EnumerateDevicesAndRequestAccessOptions

Propriedades

  • interfaceId

    número opcional

    O ID da interface à qual solicitar acesso. Disponível apenas no ChromeOS. Ela não afeta as outras plataformas.

  • productId

    number

    O ID do produto.

  • vendorId

    number

    O ID do fornecedor do dispositivo.

EnumerateDevicesOptions

Propriedades

  • filtros

    DeviceFilter[] opcional

    Será retornado um dispositivo que corresponda a qualquer filtro. Uma lista de filtros vazia retornará todos os dispositivos para os quais o app tem permissão.

  • productId

    número opcional

    Descontinuado

    Equivalente a definir DeviceFilter.productId.

  • vendorId

    número opcional

    Descontinuado

    Equivalente a definir DeviceFilter.vendorId.

GenericTransferInfo

Propriedades

  • dados

    ArrayBuffer opcional

    Os dados a serem transmitidos (necessários apenas para transferências de saída).

  • direction

    Direção

    Direção da baldeação ("in" ou "out").

  • endpoint

    number

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

  • length

    número opcional

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

  • pedido de tempo

    número opcional

    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

    number

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

  • descrição

    string opcional

    Descrição da interface.

  • endpoint

    EndpointDescriptor[]

    Endpoints disponíveis.

  • extra_data

    ArrayBuffer

    Dados de descritor extra associados a esta interface.

  • interfaceClass

    number

    A classe de interface USB.

  • interfaceNumber

    number

    O número da interface.

  • interfaceProtocol

    number

    O protocolo de interface USB.

  • interfaceSubclass

    number

    Subclasse da interface USB.

IsochronousTransferInfo

Propriedades

  • packetLength

    number

    O tamanho de cada pacote nesta transferência.

  • pacotes

    number

    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âmetro é dividido ao longo dos limites de packetLength para formar os pacotes individuais da transferência.

Recipient

Tipo enumerado

"interface"

"endpoint"

RequestType

Tipo enumerado

SynchronizationType

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

Tipo enumerado

TransferResultInfo

Propriedades

  • dados

    ArrayBuffer opcional

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

  • resultCode

    número opcional

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

TransferType

Tipo enumerado

UsageType

Tipo enumerado

"feedback"

"explicitFeedback"

Métodos

bulkTransfer()

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

Executa uma transferência em massa no dispositivo especificado.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

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

claimInterface()

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

Reivindica uma interface em um dispositivo USB. Antes de transferir os dados para uma interface ou para endpoints associados, a interface precisa ser reivindicada. Somente um identificador de conexão pode reivindicar uma interface por vez. Se a interface já tiver sido reivindicada, a chamada vai falhar.

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

Parâmetros

  • identificador

    ConnectionHandle

    Uma conexão aberta com o dispositivo.

  • interfaceNumber

    number

    A interface a ser reivindicada.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

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

closeDevice()

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

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

Parâmetros

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

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

controlTransfer()

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

Executa uma transferência de controle no dispositivo especificado.

As transferências de controle são o dispositivo, uma interface ou um endpoint. As transferências para uma interface ou um endpoint exigem que a interface seja reivindicada.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

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

findDevices()

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

Encontra dispositivos USB especificados pelo fornecedor, produto e IDs de interface (opcional) e, se as permissões permitirem, eles serão abertos para uso.

Se a solicitação de acesso for rejeitada ou se o dispositivo não for 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

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

getConfiguration()

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

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

Parâmetros

Retorna

  • Chrome 116 ou mais recente

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

getConfigurations()

Promessa Chrome 47+ 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

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

Parâmetros

Retorna

  • Promise<ConfigDescriptor[]>

    Chrome 116 ou mais recente

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

getDevices()

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

Enumera os dispositivos USB conectados.

Parâmetros

  • As propriedades a serem pesquisadas nos dispositivos de destino.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (devices: Device[])=>void

Retorna

  • Prometer<Dispositivo[]>

    Chrome 116 ou mais recente

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

getUserSelectedDevices()

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

Apresenta um seletor de dispositivo ao usuário e retorna os Devices selecionados. Se ele cancelar, os seletores vão ficar vazios. Um gesto do usuário é necessário para que a caixa de diálogo seja mostrada. 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 dispositivo.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (devices: Device[])=>void

Retorna

  • Prometer<Dispositivo[]>

    Chrome 116 ou mais recente

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

interruptTransfer()

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

Executa uma transferência interrompida no dispositivo especificado.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

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

isochronousTransfer()

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

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

Parâmetros

Retorna

  • Chrome 116 ou mais recente

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

listInterfaces()

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

Lista todas as interfaces em um dispositivo USB.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

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

openDevice()

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

Abre um dispositivo USB retornado por getDevices.

Parâmetros

Retorna

  • Chrome 116 ou mais recente

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

releaseInterface()

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

Libera uma interface reivindicada.

Parâmetros

  • identificador

    ConnectionHandle

    Uma conexão aberta com o dispositivo.

  • interfaceNumber

    number

    A interface a ser lançada.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

    Promessas são compatíveis apenas 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,
)

Essa função era específica do Chrome OS, e chamá-la em outras plataformas falharia. Agora, essa operação é realizada de forma implícita como parte de openDevice, e a função retornará true em todas as plataformas.

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

Parâmetros

  • dispositivo

    Dispositivo

    O Device que vai receber a solicitação de acesso.

  • interfaceId

    number

    A interface específica solicitada.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (success: boolean)=>void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 116 ou mais recente

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

resetDevice()

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

Tenta redefinir o dispositivo USB. Se a redefinição falhar, a alça de conexão fornecida será fechada, e o dispositivo USB parecerá desconectado e reconectado. Nesse caso, getDevices ou findDevices precisam ser chamados novamente para adquirir o dispositivo.

Parâmetros

  • identificador

    ConnectionHandle

    Um identificador de conexão para redefinir.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (success: boolean)=>void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 116 ou mais recente

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

setConfiguration()

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

Selecione uma configuração de dispositivo.

Essa função redefine o dispositivo de forma eficaz selecionando uma das configurações disponíveis. Somente valores de configuração maiores que 0 são válidos. No entanto, alguns dispositivos com bugs têm uma configuração 0 em funcionamento e, portanto, esse valor é permitido.

Parâmetros

  • identificador

    ConnectionHandle

    Uma conexão aberta com o dispositivo.

  • configurationValue

    number

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

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

setInterfaceAlternateSetting()

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

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

Parâmetros

  • identificador

    ConnectionHandle

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

  • interfaceNumber

    number

    A interface a ser configurada.

  • alternateSetting

    number

    A configuração alternativa a ser definida.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 116 ou mais recente

    Promessas são compatíveis apenas 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ão transmitidos apenas 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 pelo 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 o onDeviceAdded para saber quais eventos são entregues.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (device: Device)=>void