chrome.usb

說明

使用 chrome.usb API 與已連接的 USB 裝置互動。這個 API 可讓使用者在應用程式環境中存取 USB 作業。透過這個 API，應用程式可做為硬體裝置的驅動程式。設定 runtime.lastError 並執行函式的一般回呼，即可回報這個 API 產生的錯誤。在此情況下，系統不會定義回呼的一般參數。

權限

usb

類型

ConfigDescriptor

屬性

  • 已啟用

    boolean

    Chrome 47 以上版本

    這是啟用的設定嗎？

  • configurationValue

    號碼

    設定編號。

  • description

    字串 選用

    設定的說明。

  • extra_data

    ArrayBuffer

    與這項設定相關聯的其他描述元資料。

  • 可用介面。

  • maxPower

    號碼

    裝置所需的最大功率，以毫安培 (mA) 為單位。

  • remoteWakeup

    boolean

    本裝置支援遠端喚醒功能。

  • selfPowered

    boolean

    裝置是自行供電。

ConnectionHandle

屬性

  • 帳號

    號碼

    不透明的控制代碼，代表這個 USB 裝置之間的連線，以及所有相關聯的介面與待處理的傳輸作業。每次開啟裝置時，系統就會建立新的帳號代碼。連線控制代碼與 Device.device 不同。

  • productId

    號碼

    產品 ID。

  • vendorId

    號碼

    裝置供應商 ID。

ControlTransferInfo

屬性

  • 資料或曾存取這類資料的人員

    ArrayBuffer 選用

    要傳輸的資料 (只有輸出傳輸所需)。

  • direction

    方向

    轉乘方向 ("in" 或 "out")。

  • 索引

    號碼

    wIndex 欄位，請參閱「Ibid」。

  • length

    數字 選填

    要接收的位元組數最大值 (只有輸入轉移作業所需)。

  • 獲贈者

    收件者

    轉移目標。如為 "interface" 或 "endpoint"，則必須先聲明 index 指定的目標。

  • 申請。

    號碼

    bRequest 欄位，請參閱通用串列匯流排規格修訂版本 1.1 § 9.3。

  • requestType

    RequestType

    要求類型。

  • 逾時

    數字 選填

    Chrome 43 以上版本

    要求逾時 (以毫秒為單位)。預設值 0 表示沒有逾時。

  • 值

    號碼

    wValue 欄位，請參閱「Ibid」。

Device

屬性

  • 裝置

    號碼

    USB 裝置的不透明 ID。在裝置未接上電源前，狀態不會改變。

  • manufacturerName

    字串

    Chrome 46 以上版本

    裝置讀取的 iManufacturer 字串 (如果有的話)。

  • productId

    號碼

    產品 ID。

  • productName

    字串

    Chrome 46 以上版本

    從裝置讀取的 iProduct 字串 (如果有的話)。

  • serialNumber

    字串

    Chrome 46 以上版本

    裝置讀取的 iSerialNumber 字串 (如果有的話)。

  • vendorId

    號碼

    裝置供應商 ID。

  • version

    號碼

    Chrome 51 以上版本

    裝置版本 (bcdDevice 欄位)。

DeviceFilter

屬性

  • interfaceClass

    數字 選填

    USB 介面類別，與裝置上的任何介面相符。

  • interfaceProtocol

    數字 選填

    USB 介面通訊協定，只有在介面子類別相符時才會勾選。

  • interfaceSubclass

    數字 選填

    USB 介面子類別，只會在介面類別相符時勾選。

  • productId

    數字 選填

    裝置產品 ID，只有在供應商 ID 相符時才會檢查。

  • vendorId

    數字 選填

    裝置供應商 ID。

DevicePromptOptions

屬性

  • 篩選器

    DeviceFilter[] 選用

    篩選向使用者顯示的裝置清單。如果提供的多個篩選器符合任何篩選條件，系統就會顯示相應的裝置。

  • 多個

    布林值 (選用)

    允許使用者選取多部裝置。

Direction

Direction、Recipient、RequestType 和 TransferType 都對應到 USB 規格中的名稱。

列舉

EndpointDescriptor

屬性

  • 地址

    號碼

    端點位址。

  • direction

    方向

    轉移方向。

  • extra_data

    ArrayBuffer

    與這個端點相關聯的額外描述元資料。

  • maximumPacketSize

    號碼

    封包大小上限。

  • pollingInterval

    數字 選填

    輪詢間隔 (僅限中斷和個別週期)。

  • 同步處理

    SynchronizationType 選用

    傳輸同步處理模式 (僅限獨立模式)。

  • 類型

    TransferType

    移轉作業類型。

  • 用量

    UsageType 選用

    端點使用提示。

EnumerateDevicesAndRequestAccessOptions

屬性

  • interfaceId

    數字 選填

    要求存取權的介面 ID。(僅適用於 ChromeOS)。在其他平台不會受到影響。

  • productId

    號碼

    產品 ID。

  • vendorId

    號碼

    裝置供應商 ID。

EnumerateDevicesOptions

屬性

  • 篩選器

    DeviceFilter[] 選用

    系統會傳回符合任一指定篩選條件的裝置。如果將篩選器設為空白，系統會傳回應用程式具有權限的所有裝置。

  • productId

    數字 選填

    已淘汰

    相當於設定 DeviceFilter.productId。

  • vendorId

    數字 選填

    已淘汰

    相當於設定 DeviceFilter.vendorId。

GenericTransferInfo

屬性

  • 資料或曾存取這類資料的人員

    ArrayBuffer 選用

    要傳輸的資料 (只有輸出傳輸所需)。

  • direction

    方向

    轉乘方向 ("in" 或 "out")。

  • 端點

    號碼

    目標端點位址。必須聲明含有此端點的介面。

  • length

    數字 選填

    要接收的位元組數最大值 (只有輸入轉移作業所需)。

  • 逾時

    數字 選填

    Chrome 43 以上版本

    要求逾時 (以毫秒為單位)。預設值 0 表示沒有逾時。

InterfaceDescriptor

屬性

  • alternateSetting

    號碼

    介面替代設定編號 (預設為 0)

  • description

    字串 選用

    介面說明。

  • endpoints

    EndpointDescriptor[]

    可用的端點。

  • extra_data

    ArrayBuffer

    與這個介面相關聯的額外描述元資料。

  • interfaceClass

    號碼

    USB 介面類別。

  • interfaceNumber

    號碼

    介面編號。

  • interfaceProtocol

    號碼

    USB 介面通訊協定。

  • interfaceSubclass

    號碼

    USB 介面子類別。

IsochronousTransferInfo

屬性

  • packetLength

    號碼

    這項傳輸作業中每個封包的長度。

  • 封包

    號碼

    這項傳輸作業中的封包總數。

  • transferInfo

    GenericTransferInfo

    轉移參數。此參數區塊中指定的傳輸長度或資料緩衝區會沿著 packetLength 邊界分割，形成傳輸的個別封包。

Recipient

列舉

"endpoint"

RequestType

列舉

SynchronizationType

針對中斷模式和獨立模式，SynchronizationType 和 UsageType 會對應到 USB 規格中的名稱。

列舉

TransferResultInfo

屬性

  • 資料或曾存取這類資料的人員

    ArrayBuffer 選用

    輸入移轉作業傳回的資料。undefined 用於輸出傳輸。

  • resultCode

    數字 選填

    如果值為 0，表示轉移作業已成功完成。其他值則表示失敗。

TransferType

列舉

"bulk"

UsageType

列舉

方法

bulkTransfer()

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

在指定裝置中執行大量轉移作業。

參數

傳回

  • Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

claimInterface()

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

領取 USB 裝置的介面。您必須先聲明介面的擁有權，才能將資料轉移至介面或相關聯的端點。在任何特定時間內，系統只能有一個連線控制代碼。如果已認領介面，則呼叫會失敗。

如果不再需要介面，則應呼叫 releaseInterface。

參數

  • 開放的裝置連線。

  • interfaceNumber

    號碼

    要聲明的介面。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

closeDevice()

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

關閉連線控制點。在帳號代碼關閉後叫用作業屬於安全作業，因此無須採取任何行動。

參數

傳回

  • Promise<void>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

controlTransfer()

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

在指定裝置執行控制項轉移。

控制傳輸是指裝置、介面或端點。必須先聲明介面擁有權，才能轉移至介面或端點。

參數

傳回

  • Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

findDevices()

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

尋找廠商、產品和 (選用) 介面 ID 指定的 USB 裝置，以及是否允許開啟並使用這些裝置。

如果存取要求遭拒，或裝置無法開啟連線控制代碼，系統就不會建立或傳回裝置。

呼叫這個方法相當於在每部裝置呼叫 getDevices 後接著呼叫 openDevice。

參數

傳回

  • Promise<ConnectionHandle[]>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getConfiguration()

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

取得目前所選設定的設定描述元。

參數

傳回

  • Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getConfigurations()

Promise Chrome 47 以上版本 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

傳回完整的裝置設定描述元集。

參數

傳回

  • Promise<ConfigDescriptor[]>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getDevices()

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

列舉已連線的 USB 裝置。

參數

傳回

  • Promise<裝置[]>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getUserSelectedDevices()

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

向使用者顯示裝置挑選器，並傳回選取的 Device。如果使用者取消挑選工具裝置，畫面上就不會顯示任何內容。需要使用者手勢才會顯示對話方塊。如果沒有使用者手勢，回呼將以使用者取消的狀態執行。

參數

  • 裝置挑選器對話方塊的設定。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (devices: Device[])=>void

傳回

  • Promise<裝置[]>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

interruptTransfer()

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

在指定裝置執行中斷傳輸。

參數

傳回

  • Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

isochronousTransfer()

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

在特定裝置上執行獨立傳輸作業。

參數

傳回

  • Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

listInterfaces()

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

列出 USB 裝置上的所有介面。

參數

傳回

  • Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

openDevice()

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

開啟 getDevices 傳回的 USB 裝置。

參數

傳回

  • Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

releaseInterface()

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

釋出已聲明的介面。

參數

  • 開放的裝置連線。

  • interfaceNumber

    號碼

    要發布的介面。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

requestAccess()

Promise 已淘汰
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

這個函式僅適用於 Chrome 作業系統，因此在其他平台上呼叫會失敗。這項作業目前以 openDevice 的一部分間接執行，且這個函式會在所有平台上傳回 true。

如果裝置中的指定介面未經聲明，則要求權限代理程式將存取權授予 Chrome OS 已認領的裝置。

參數

  • 裝置

    裝置

    用來要求存取權的 Device。

  • interfaceId

    號碼

    要求的特定介面。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (success: boolean)=>void

    • 成功

      boolean

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

resetDevice()

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

嘗試重設 USB 裝置。如果重設失敗，系統會關閉指定連線控點，USB 裝置會恢復連線。在這種情況下，必須再次呼叫 getDevices 或 findDevices 才能取得裝置。

參數

  • 要重設的連線控制點。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (success: boolean)=>void

    • 成功

      boolean

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

setConfiguration()

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

選取裝置設定。

這項功能會選取裝置內的其中一項可用設定，藉此有效地重設裝置。只有大於 0 的設定值才有效，但部分裝置的設定具有 0 作用，因此可以存取這個值。

參數

  • 開放的裝置連線。

  • configurationValue

    號碼

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

setInterfaceAlternateSetting()

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

選取先前聲明的介面上的替代設定。

參數

  • 對裝置發出開放連線，且裝置認領介面。

  • interfaceNumber

    號碼

    要設定的介面。

  • alternateSetting

    號碼

    要設定的替代設定。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 116 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

活動

onDeviceAdded

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

裝置新增至系統時產生的事件。活動只會播送到有權存取裝置的應用程式和擴充功能。權限可能會在安裝時、使用者接受選用權限 (請參閱 permissions.request) 或 getUserSelectedDevices 時授予。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (device: Device)=>void

onDeviceRemoved

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

從系統中移除裝置時產生的事件。如要瞭解哪些事件會傳送事件，請參閱 onDeviceAdded。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (device: Device)=>void