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 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. Nesse caso, os parâmetros regulares do callback serão indefinidos.

Permissões

usb

Tipos

ConfigDescriptor

Propriedades

  • ativo

    booleano

    Chrome 47 ou superior

    Esta é a configuração ativa?

  • configurationValue

    number

    O número da configuração.

  • descrição

    string opcional

    Descrição da configuração.

  • extra_data

    Buffer de matriz

    Dados extras do descritor associados a esta 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 serem recebidos (obrigatório apenas para transferências de entrada).

  • destinatário

    Destinatário

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

  • solicitação

    number

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

  • requestType

    RequestType

    O tipo de solicitação.

  • timeout

    número opcional

    Chrome 43 ou superior

    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. Ela permanece inalterada até que o dispositivo seja desconectado.

  • manufacturerName

    string

    Chrome 46 ou superior

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

  • productId

    number

    O ID do produto.

  • productName

    string

    Chrome 46 ou superior

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

  • serialNumber

    string

    Chrome 46 ou superior

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

  • vendorId

    number

    O ID do fornecedor do dispositivo.

  • version

    number

    Chrome 51 ou superior

    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 de interface USB, marcada apenas se a classe de interface corresponder.

  • productId

    número opcional

    ID do produto do dispositivo, marcado apenas se o ID do fornecedor for correspondente.

  • 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

Directions, Recipient, RequestType e TransferType são mapeados para os próprios nomes na especificação USB.

Enumeração

"em"

"out"

EndpointDescriptor

Propriedades

  • endereço

    number

    Endereço do endpoint.

  • direção

    Direção

    Direção da baldeação.

  • extra_data

    Buffer de matriz

    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 sincronização de transferência (somente isócrono).

  • Tipo de transferência.

  • utilização

    UsageType opcional

    Dica de uso de endpoint.

EnumerateDevicesAndRequestAccessOptions

Propriedades

  • interfaceId

    número opcional

    O ID da interface à qual solicitar acesso. Disponível apenas no ChromeOS. Ela não afeta 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

    É equivalente à configuração de 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 serem recebidos (obrigatório apenas para transferências de entrada).

  • timeout

    número opcional

    Chrome 43 ou superior

    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 (o padrão é 0)

  • descrição

    string opcional

    Descrição da interface.

  • endpoints

    EndpointDescriptor[]

    Endpoints disponíveis.

  • extra_data

    Buffer de matriz

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

Recipient

Enumeração

"dispositivo"

"interface"

"endpoint"

"outro"

RequestType

Enumeração

"padrão"

"classe"

"fornecedor"

"reservado"

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íncrona"

"adaptável"

"síncrona"

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

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

TransferType

Enumeração

"controle"

"interromper"

"isócrona"

"em massa"

UsageType

Enumeração

"dados"

"feedback"

"explicitFeedback"

"periódico"

"notificação"

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

  • Promise<TransferResultInfo>

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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 por vez. Se a interface já tiver sido reivindicada, a chamada falhará.

releaseInterface precisa ser chamado quando a interface não é 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

  • Promessa<void>

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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

  • Promessa<void>

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no Manifesto 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 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 só têm suporte no Manifesto 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 da interface e se as permissões permitem abri-los 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 ou versões mais recentes

    As promessas só têm suporte no 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 só têm suporte no Manifesto 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 ou versões mais recentes

    As promessas só têm suporte no 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 ou versões mais recentes

    As promessas só têm suporte no 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 estarão 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 dispositivo.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (devices: Device[]) => void

Retorna

  • Promessa<Dispositivo[]>

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

interruptTransfer()

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

Interrompe a transferência no dispositivo especificado.

Parâmetros

Retorna

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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

  • Promise&lt;InterfaceDescriptor[]&gt;

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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 só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

releaseInterface()

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

Lança 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 esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no Manifesto 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 esta aparência: 

    (success: boolean) => void

    • sucesso

      booleano

Retorna

  • Promise&lt;boolean&gt;

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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 fornecido será fechado e o dispositivo USB parecerá estar desconectado e 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 opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      booleano

Retorna

  • Promise&lt;boolean&gt;

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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 de dispositivo.

Essa função redefine o dispositivo efetivamente selecionando 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 esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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 esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 116 ou versões mais recentes

    As promessas só têm suporte no 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 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 onDeviceAdded para saber quais eventos são entregues.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (device: Device) => void