chrome.usb

說明

使用 chrome.usb API 與已連接的 USB 裝置互動。這個 API 可在應用程式內容中提供 USB 作業存取權。使用這個 API 時，應用程式可充當硬體裝置的驅動程式。系統會透過設定 runtime.lastError，並執行該函式的一般回呼，回報這個 API 產生的錯誤。在這種情況下，回呼的一般參數會處於未定義狀態。

權限

usb

類型

ConfigDescriptor

屬性

  • 已啟用

    布林值

    Chrome 47 以上版本

    這是有效的設定嗎？

  • configurationValue

    數字

    設定編號。

  • 說明

    string 選填

    設定說明。

  • 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 規格內的名稱。

列舉

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 選填

    介面說明。

  • endpoints

    EndpointDescriptor[]

    可用的端點。

  • extra_data

    ArrayBuffer

    與此介面相關聯的額外描述符資料。

  • interfaceClass

    數字

    USB 介面類別。

  • interfaceNumber

    數字

    介面號碼。

  • interfaceProtocol

    數字

    USB 介面通訊協定。

  • interfaceSubclass

    數字

    USB 介面子類別。

IsochronousTransferInfo

屬性

  • packetLength

    數字

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

  • 封包

    數字

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

  • transferInfo

    GenericTransferInfo

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

Recipient

列舉

"device"

RequestType

列舉

"vendor"

"reserved"

SynchronizationType

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

列舉

TransferResultInfo

屬性

  • 資料

    ArrayBuffer 選填

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

  • resultCode

    編號 選填

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

TransferType

列舉

UsageType

列舉

"data"

"periodic"

"notification"

方法

bulkTransfer()

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

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

參數

傳回

  • Chrome 116 以上版本

    承諾僅支援資訊清單 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 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

controlTransfer()

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

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

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

參數

傳回

  • Promise<TransferResultInfo>

    Chrome 116 以上版本

    承諾僅支援資訊清單 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,
)

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

參數

傳回

  • Promise&lt;ConfigDescriptor&gt;

    Chrome 116 以上版本

    承諾僅支援資訊清單 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<Device[]>

    Chrome 116 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getUserSelectedDevices()

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

向使用者顯示裝置挑選器，並傳回所選的 Device。如果使用者取消挑選器裝置，裝置就不會顯示任何內容。需要使用者手勢才能顯示對話方塊。如果沒有使用者手勢，回呼會以使用者取消的情況執行。

參數

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (devices: Device[]) => void

傳回

  • Promise<Device[]>

    Chrome 116 以上版本

    承諾僅支援資訊清單 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,
)

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

參數

傳回

  • Promise<TransferResultInfo>

    Chrome 116 以上版本

    承諾僅支援資訊清單 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 裝置。

參數

傳回

  • Chrome 116 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

releaseInterface()

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

釋出已聲明的介面。

參數

  • 與裝置建立開放式連線。

  • interfaceNumber

    數字

    要釋出的介面。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

requestAccess()

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

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

如果裝置上的指定介面未聲明聲明，則向權限仲介要求存取 Chrome OS 聲明的裝置。

參數

  • 裝置

    裝置

    要求存取權的 Device。

  • interfaceId

    數字

    要求的特定介面。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 116 以上版本

    承諾僅支援資訊清單 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

傳回

  • Promise<void>

    Chrome 116 以上版本

    承諾僅支援資訊清單 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