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 e versões mais recentes

    Esta é a configuração ativa?

  • configurationValue

    number

    O número da configuração.

  • descrição

    string opcional

    Descrição da configuração.

  • extra_data

    ArrayBuffer

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

  • interfaces

    InterfaceDescriptor[]

    Interfaces disponíveis.

  • maxPower

    number

    Potência máxima necessária para este dispositivo em milissegundos (mA).

  • remoteWakeup

    booleano

    O dispositivo oferece suporte à ativação remota.

  • selfPowered

    booleano

    O dispositivo é independente.

ConnectionHandle

Propriedades

  • handle

    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 do 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 (obrigatórios apenas para transferências de saída).

  • direção

    Direção

    A direção de baldeação ("in" ou "out").

  • index

    number

    Para o campo wIndex, consulte Ibid.

  • comprimento

    número opcional

    O número máximo de bytes a receber (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 "interface" ou "endpoint".

  • solicitação

    number

    O campo bRequest. Consulte a Especificação de bus serial universal, revisão 1.1, § 9.3.

  • requestType

    RequestType

    O tipo de solicitação.

  • timeout

    número opcional

    Chrome 43 e versões mais recentes

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

  • valor

    number

    Para o campo wValue, consulte Ibid.

Device

Propriedades

  • dispositivo

    number

    Um código 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

    number

    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

    number

    O ID do fornecedor do dispositivo.

  • version

    number

    Chrome 51 e versões mais recentes

    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, verificado apenas se o ID do fornecedor corresponder.

  • vendorId

    número opcional

    ID do fornecedor do dispositivo.

DevicePromptOptions

Propriedades

  • filtros

    DeviceFilter[] opcional

    Filtre a lista de dispositivos apresentada ao usuário. Se vários filtros forem fornecidos, os dispositivos que corresponderem 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 os nomes correspondentes na especificação USB.

Enumeração

"in"

"out"

EndpointDescriptor

Propriedades

  • endereço

    number

    Endereço do endpoint.

  • direção

    Direção

    Direção da baldeação.

  • extra_data

    ArrayBuffer

    Dados extras do descritor 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 transferência de sincronização (somente isocrono).

  • Tipo de transferência.

  • utilização

    UsageType opcional

    Dica de uso do endpoint.

EnumerateDevicesAndRequestAccessOptions

Propriedades

  • interfaceId

    número opcional

    O ID da interface para solicitar acesso. Disponível apenas no ChromeOS. Ela não tem efeito em outras plataformas.

  • productId

    number

    O ID do produto.

  • vendorId

    number

    O ID do fornecedor do dispositivo.

EnumerateDevicesOptions

Propriedades

  • filtros

    DeviceFilter[] opcional

    Um dispositivo correspondente a qualquer filtro será retornado. Uma lista de filtros vazia retornará todos os dispositivos para os quais o app tem permissão.

  • productId

    número opcional

    Descontinuado

    Equivale a definir DeviceFilter.productId.

  • vendorId

    número opcional

    Descontinuado

    É equivalente à configuração de DeviceFilter.vendorId.

GenericTransferInfo

Propriedades

  • dados

    ArrayBuffer opcional

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

  • direção

    Direção

    A direção de baldeação ("in" ou "out").

  • endpoint

    number

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

  • comprimento

    número opcional

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

  • timeout

    número opcional

    Chrome 43 e versões mais recentes

    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 da configuração alternativa da interface (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

    number

    A classe de interface USB.

  • interfaceNumber

    number

    O número da interface.

  • interfaceProtocol

    number

    O protocolo de interface USB.

  • interfaceSubclass

    number

    A subclasse de interface USB.

IsochronousTransferInfo

Propriedades

  • packetLength

    number

    O tamanho de cada pacote nessa transferência.

  • pacotes

    number

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

  • transferInfo

    GenericTransferInfo

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

Recipient

Enumeração

"device"

"endpoint"

"other"

RequestType

Enumeração

SynchronizationType

Para modos de interrupção e isocrônico, SynchronizationType e UsageType são mapeados para os nomes correspondentes na especificação USB.

Enumeração

"assíncrono"

"adaptativo"

TransferResultInfo

Propriedades

  • dados

    ArrayBuffer opcional

    Os 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 bem-sucedida. Outros valores indicam falha.

TransferType

Enumeração

"bulk"

UsageType

Enumeração

"data"

"feedback"

"periodic"

Métodos

bulkTransfer()

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

Realiza uma transferência em massa no dispositivo especificado.

Parâmetros

Retorna

  • Chrome 116 ou versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 que os dados possam ser transferidos para uma interface ou endpoints associados, a interface deve ser reivindicada. Somente um identificador de conexão pode reivindicar uma interface a qualquer momento. Se a interface já tiver sido reivindicada, essa chamada vai falhar.

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

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • interfaceNumber

    number

    A interface a ser reivindicada.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 do fechamento é uma operação segura, mas não faz com que nenhuma ação seja realizada.

Parâmetros

Retorna

  • Promise<void>

    Chrome 116 ou versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

controlTransfer()

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

Transfere o controle para o dispositivo especificado.

As transferências de controle se referem ao dispositivo, a uma interface ou a um endpoint. As transferências para uma interface ou um endpoint exigem que a interface seja reivindicada.

Parâmetros

Retorna

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 ou versões mais recentes

    As promessas têm suporte apenas para 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 (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 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&lt;ConnectionHandle[]&gt;

    Chrome 116 e versões mais recentes

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

getConfiguration()

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

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

Parâmetros

Retorna

  • Promise&lt;ConfigDescriptor&gt;

    Chrome 116 ou versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getConfigurations()

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

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

Parâmetros

Retorna

  • Promise&lt;ConfigDescriptor[]&gt;

    Chrome 116 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 opcional

    O parâmetro callback tem esta aparência: 

    (devices: Device[]) => void

Retorna

  • Promessa<Dispositivo[]>

    Chrome 116 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 as Devices selecionadas. Se o usuário cancelar, os dispositivos do seletor vão estar vazios. Um gesto do usuário é necessá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 dispositivo.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (devices: Device[]) => void

Retorna

  • Promise<Device[]>

    Chrome 116 e versões mais recentes

    As promessas têm suporte apenas para 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 de interrupção no dispositivo especificado.

Parâmetros

Retorna

  • Chrome 116 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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

  • Promise&lt;ConnectionHandle&gt;

    Chrome 116 ou versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

releaseInterface()

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

Liberta uma interface reivindicada.

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • interfaceNumber

    number

    A interface a ser lançada.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 ou versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

requestAccess()

Promessa Descontinuado
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

Essa função era específica para o Chrome OS e chamá-la em outras plataformas falharia. Essa operação agora é executada implicitamente como parte de openDevice, e essa função retorna 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 o acesso.

  • interfaceId

    number

    A interface específica solicitada.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (success: boolean) => void

    • sucesso

      booleano

Retorna

  • Promise<boolean>

    Chrome 116 ou versões mais recentes

    As promessas só são compatíveis com o Manifesto 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, o identificador de conexão será fechado, e o dispositivo USB vai parecer desconectado e depois 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 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 do dispositivo.

Essa função redefine o dispositivo efetivamente ao selecionar uma das configurações disponíveis do dispositivo. 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. Por isso, esse valor é permitido.

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • configurationValue

    number

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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.

Parâmetros

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

  • interfaceNumber

    number

    A interface a ser configurada.

  • alternateSetting

    number

    A configuração alternativa a ser definida.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 116 e versões mais recentes

    As promessas só são compatíveis com o Manifesto 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 somente 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 meio de getUserSelectedDevices.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (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 este formato: 

    (device: Device) => void