chrome.usb

說明

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

權限

usb

類型

ConfigDescriptor

屬性

  • 已啟用

    布林值

    Chrome 47 以上版本

    這是有效的設定嗎？

  • configurationValue

    數字

    設定編號。

  • 說明

    string optional

    設定說明。

  • extra_data

    ArrayBuffer

    與這個設定相關聯的額外描述元資料。

  • 可用介面。

  • maxPower

    數字

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

  • remoteWakeup

    布林值

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

  • selfPowered

    布林值

    裝置為自主電源。

ConnectionHandle

屬性

  • 帳號

    數字

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

  • productId

    數字

    產品 ID。

  • vendorId

    數字

    裝置供應商 ID。

ControlTransferInfo

屬性

  • 資料

    ArrayBuffer 選用

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

  • 方向

    方向

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

  • 索引

    數字

    wIndex 欄位，請參閱 Ibid。

  • 長度

    編號 選填

    要接收的位元組數上限 (僅適用於輸入移轉作業)。

  • 獲贈者

    收件者

    轉移目標。如果為 "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。

  • 版本

    數字

    Chrome 51 以上版本

    裝置版本 (bcdDevice 欄位)。

DeviceFilter

屬性

  • interfaceClass

    編號 選填

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

  • interfaceProtocol

    編號 選填

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

  • interfaceSubclass

    編號 選填

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

  • productId

    編號 選填

    裝置產品 ID (只有在供應商 ID 相符時才會勾選)。

  • vendorId

    編號 選填

    裝置供應商 ID。

DevicePromptOptions

屬性

  • 篩選器

    DeviceFilter[] 選用

    篩選向使用者顯示的裝置清單。若提供多個篩選條件的裝置符合任何篩選條件，就會顯示。

  • 多個

    布林值 選填

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

Direction

Direction、Recipient、RequestType 和 TransferType 等都會對應至其在 USB 規格中的名稱。

列舉

"in"

"out"

EndpointDescriptor

屬性

  • 地址

    數字

    端點位址。

  • 方向

    方向

    轉乘方向。

  • 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 選用

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

  • 方向

    方向

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

  • 端點

    數字

    目標端點位址。必須聲明包含這個端點的介面。

  • 長度

    編號 選填

    要接收的位元組數上限 (僅適用於輸入移轉作業)。

  • 逾時

    編號 選填

    Chrome 43 以上版本

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

InterfaceDescriptor

屬性

  • alternateSetting

    數字

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

  • 說明

    string optional

    介面說明。

  • endpoints

    EndpointDescriptor[]

    可用端點。

  • extra_data

    ArrayBuffer

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

  • interfaceClass

    數字

    USB 介面類別。

  • interfaceNumber

    數字

    介面號碼。

  • interfaceProtocol

    數字

    USB 介面通訊協定。

  • interfaceSubclass

    數字

    USB 介面子類別。

IsochronousTransferInfo

屬性

  • packetLength

    數字

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

  • 封包

    數字

    這項移轉作業中的封包總數。

  • transferInfo

    GenericTransferInfo

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

Recipient

列舉

「裝置」

"interface"

"endpoint"

「其他」

RequestType

列舉

"標準"

"class"

「供應商」

"reserve"

SynchronizationType

如果是中斷模式和同異模式，SynchronizationType 和 UsageType 會在 USB 規格中對應至相應的名稱。

列舉

"非同步"

「自動調整」

"同步"

TransferResultInfo

屬性

  • 資料

    ArrayBuffer 選用

    輸入傳輸傳回的資料。undefined 用於輸出傳輸。

  • resultCode

    編號 選填

    如果值為 0，表示轉移成功。其他值則代表失敗。

TransferType

列舉

"control"

"中斷"

「同行」

"大量"

UsageType

列舉

"資料"

"意見回饋"

「明確意見回饋」

"週期"

"通知"

方法

bulkTransfer()

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

在指定裝置上執行大量傳輸作業。

參數

傳回

  • Promise<TransferResultInfo>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

claimInterface()

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

聲明 USB 裝置上的介面。必須先聲明介面擁有權，才能將資料移轉至介面或相關聯的端點。一次只能有一個連線控制代碼聲明介面的擁有權。如果已聲明介面的擁有權，此呼叫就會失敗。

不再需要介面時，應呼叫 releaseInterface。

參數

  • 裝置的開放式連線。

  • interfaceNumber

    數字

    要聲明擁有權的介面。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

closeDevice()

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

關閉連線控點。在控點關閉後對帳號代碼叫用作業是安全的作業，不會導致使用者採取任何動作。

參數

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

controlTransfer()

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

在指定裝置上執行控制轉移作業。

控制移轉作業是指裝置、介面或端點。轉移至介面或端點時，必須聲明介面的擁有權。

參數

傳回

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

findDevices()

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

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

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

呼叫此方法等同於呼叫 getDevices，後面依序為每部裝置呼叫 openDevice。

參數

傳回

  • Promise&lt;ConnectionHandle[]&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getConfiguration()

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

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

參數

傳回

  • Promise&lt;ConfigDescriptor&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getConfigurations()

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

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

參數

傳回

  • Promise&lt;ConfigDescriptor[]&gt;

    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,
)

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

參數

傳回

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

isochronousTransfer()

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

在該裝置上執行異位傳輸。

參數

傳回

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

listInterfaces()

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

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

參數

傳回

  • Promise&lt;InterfaceDescriptor[]&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

openDevice()

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

開啟 getDevices 傳回的 USB 裝置。

參數

傳回

  • Promise&lt;ConnectionHandle&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

releaseInterface()

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

釋出已聲明著作權的介面。

參數

  • 裝置的開放式連線。

  • interfaceNumber

    數字

    即將發布的介面。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

requestAccess()

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

這是 Chrome OS 專屬函式，在其他平台上呼叫該函式會失敗。這項作業現會在 openDevice 中以隱含形式執行，且這個函式會在所有平台上傳回 true。

如未聲明裝置上指定介面的擁有權，則權限代理程式會要求存取 Chrome OS 認領的裝置。

參數

  • 裝置

    裝置

    要求存取權的 Device。

  • interfaceId

    數字

    要求的特定介面。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

resetDevice()

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

嘗試重設 USB 裝置。如果重設失敗，指定連線控點將會關閉，USB 裝置看起來已中斷連線，然後重新連線。在此情況下，您必須再次呼叫 getDevices 或 findDevices，才能取得裝置。

參數

  • 要重設的連線控制點。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setConfiguration()

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

選取裝置設定。

這項功能可讓您選取裝置可用的設定，有效地重設裝置。只有大於 0 的設定值才有效，但某些錯誤的裝置具有正常運作的設定 0，因此這個值可以使用。

參數

  • 裝置的開放式連線。

  • configurationValue

    數字

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setInterfaceAlternateSetting()

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

在先前已聲明著作權的介面中選取替代設定。

參數

  • 連線至有人聲明這個介面的裝置開放連線。

  • interfaceNumber

    數字

    要設定的介面。

  • alternateSetting

    數字

    要設定的替代設定。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<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