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. Com ela, 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

Disponibilidade

Somente no ChromeOS

Tipos

ConfigDescriptor

Propriedades

  • ativo

    booleano

    Chrome 47+

    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 miliamperes (mA).

  • remoteWakeup

    booleano

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

  • selfPowered

    booleano

    O dispositivo tem alimentação própria.

ConnectionHandle

Propriedades

  • handle

    número

    Um identificador 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 (necessários apenas para transferências de saída).

  • direção

    Direção

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

  • índice

    número

    O campo wIndex, consulte Ibid.

  • comprimento

    número optional

    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. O destino fornecido por index precisa ser reivindicado se "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

    número optional

    Chrome 43+

    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.

  • versão

    número

    Chrome 51 ou mais recente

    A versão do dispositivo (campo bcdDevice).

DeviceFilter

Propriedades

  • interfaceClass

    número optional

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

  • interfaceProtocol

    número optional

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

  • interfaceSubclass

    número optional

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

  • productId

    número optional

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

  • vendorId

    número optional

    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 um deles serão exibidos.

  • várias

    booleano opcional

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

Direction

Direction, Recipient, RequestType e TransferType são mapeados para os 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 esse endpoint.

  • maximumPacketSize

    número

    Tamanho máximo do pacote.

  • pollingInterval

    número optional

    Intervalo de sondagem (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

    número optional

    O ID da interface para solicitar acesso. Disponível apenas no Chrome OS. Ela 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 fornecido será retornado. Uma lista de filtros vazia vai retornar todos os dispositivos para os quais o app tem permissão.

  • productId

    número optional

    Descontinuado

    Equivale a definir DeviceFilter.productId.

  • vendorId

    número optional

    Descontinuado

    Equivale a definir DeviceFilter.vendorId.

GenericTransferInfo

Propriedades

  • dados

    ArrayBuffer opcional

    Os dados a serem transmitidos (necessários 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

    número optional

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

  • timeout

    número optional

    Chrome 43+

    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 tamanho de cada um dos pacotes nessa transferência.

  • pacotes

    número

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

  • transferInfo

    GenericTransferInfo

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

Recipient

Enumeração

"device"

"interface"

"endpoint"

"other"

RequestType

Enumeração

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

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

Enumeração

"asynchronous"

"adaptive"

"synchronous"

TransferResultInfo

Propriedades

  • dados

    ArrayBuffer opcional

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

  • resultCode

    número optional

    O valor 0 indica que a transferência foi bem-sucedida. Outros valores indicam falha.

TransferType

Enumeração

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

Enumeração

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Métodos

bulkTransfer()

Promessa 
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+

    As promessas só são compatíveis 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,
): 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á tiver sido 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 optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 116+

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

closeDevice()

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

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

Parâmetros

Retorna

  • Promessa<void>

    Chrome 116+

    As promessas só são compatíveis 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,
): 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. As transferências para uma interface ou endpoint exigem que a interface seja reivindicada.

Parâmetros

Retorna

  • Chrome 116+

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

findDevices()

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

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

Se o pedido de acesso for rejeitado 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<ConnectionHandle[]>

    Chrome 116+

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

getConfiguration()

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

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

Parâmetros

Retorna

  • Chrome 116+

    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+ 
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+

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

getDevices()

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

Enumera os dispositivos USB conectados.

Parâmetros

  • As propriedades a serem pesquisadas nos dispositivos de destino.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (devices: Device[]) => void

Retorna

  • Promise<Device[]>

    Chrome 116+

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

getUserSelectedDevices()

Promessa 
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ária uma interação do usuário para que a caixa de diálogo seja exibida. Sem uma interação inicial, 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 optional

    O parâmetro callback é semelhante a: 

    (devices: Device[]) => void

Retorna

  • Promise<Device[]>

    Chrome 116+

    As promessas só são compatíveis 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,
): Promise<TransferResultInfo>

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

Parâmetros

Retorna

  • Chrome 116+

    As promessas só são compatíveis 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,
): Promise<TransferResultInfo>

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

Parâmetros

Retorna

  • Chrome 116+

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

listInterfaces()

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

Lista todas as interfaces em um dispositivo USB.

Parâmetros

Retorna

  • Chrome 116+

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

openDevice()

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

Abre um dispositivo USB retornado por getDevices.

Parâmetros

Retorna

  • Chrome 116+

    As promessas só são compatíveis 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,
): Promise<void>

Libera uma interface reivindicada.

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • interfaceNumber

    número

    A interface a ser liberada.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 116+

    As promessas só são compatíveis com 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,
): Promise<boolean>

Essa função era específica do Chrome OS, e chamá-la em outras plataformas resultava em falha. Essa operação agora é realizada implicitamente como parte de openDevice, e essa função vai retornar true em todas as plataformas.

Solicita acesso do agente de permissões a um dispositivo reivindicado pelo ChromeOS se a interface fornecida 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 optional

    O parâmetro callback é semelhante a: 

    (success: boolean) => void

    • sucesso

      booleano

Retorna

  • Promise<boolean>

    Chrome 116+

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

resetDevice()

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

Tenta redefinir o dispositivo USB. Se a redefinição falhar, o identificador de conexão fornecido 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 para redefinir.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (success: boolean) => void

    • sucesso

      booleano

Retorna

  • Promise<boolean>

    Chrome 116+

    As promessas só são compatíveis 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,
): Promise<void>

Selecione um Configurador do dispositivo.

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

Parâmetros

  • Uma conexão aberta com o dispositivo.

  • configurationValue

    número

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 116+

    As promessas só são compatíveis 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,
): 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.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 116+

    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ã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 por getUserSelectedDevices.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (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 é semelhante a: 

    (device: Device) => void