chrome.usb

說明

使用 chrome.usb API 與連結的 USB 裝置互動。這個 API 可讓您在應用程式中存取 USB 作業。應用程式可透過這個 API 充當硬體裝置的驅動程式。這個 API 產生的錯誤會透過設定 runtime.lastError 並執行函式的一般回呼來回報。在這種情況下，回呼的一般參數會是未定義。

權限

usb

可用性

僅適用於 ChromeOS

類型

ConfigDescriptor

屬性

  • 已啟用

    布林值

    Chrome 47 以上版本

    這是有效的設定嗎？

  • configurationValue

    數字

    設定編號。

  • 說明

    字串 選填

    設定說明。

  • extra_data

    ArrayBuffer

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

  • 可用介面。

  • maxPower

    數字

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

  • remoteWakeup

    布林值

    裝置支援遠端喚醒。

  • selfPowered

    布林值

    裝置可自行供電。

ConnectionHandle

屬性

  • 帳號

    數字

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

  • productId

    數字

    產品 ID。

  • vendorId

    數字

    裝置供應商 ID。

ControlTransferInfo

屬性

  • 資料

    ArrayBuffer 選用

    要傳輸的資料 (僅輸出轉移作業需要)。

  • 方向

    方向

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

  • 索引

    數字

    wIndex 欄位，請參閱同上。

  • 長度

    數字 選填

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

  • 獲贈者

    Recipient

    移轉目標。如果 "interface" 或 "endpoint"，則必須宣告 index 指定的目標。

  • 申請。

    數字

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

  • requestType

    RequestType

    要求類型。

  • 逾時

    數字 選填

    Chrome 43 以上版本

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

  • 值

    數字

    wValue 欄位，請參閱同上。

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 規格中的同名項目。

列舉

「位於」

"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")。

  • endpoint

    數字

    目標端點位址。必須宣告含有這個端點的介面。

  • 長度

    數字 選填

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

  • 逾時

    數字 選填

    Chrome 43 以上版本

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

InterfaceDescriptor

屬性

  • alternateSetting

    數字

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

  • 說明

    字串 選填

    介面說明。

  • endpoints

    EndpointDescriptor[]

    可用的端點。

  • extra_data

    ArrayBuffer

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

  • interfaceClass

    數字

    USB 介面類別。

  • interfaceNumber

    數字

    介面編號。

  • interfaceProtocol

    數字

    USB 介面通訊協定。

  • interfaceSubclass

    數字

    USB 介面子類別。

IsochronousTransferInfo

屬性

  • packetLength

    數字

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

  • 封包

    數字

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

  • transferInfo

    GenericTransferInfo

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

Recipient

列舉

"device"

"interface"

"endpoint"

"other"

RequestType

列舉

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

在插斷和等時模式中，SynchronizationType 和 UsageType 會對應至 USB 規格中的同名項目。

列舉

「非同步」

"adaptive"

"synchronous"

TransferResultInfo

屬性

  • 資料

    ArrayBuffer 選用

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

  • resultCode

    數字 選填

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

TransferType

列舉

"control"

「中斷」

"isochronous"

"bulk"

UsageType

列舉

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

方法

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,
): Promise<void>

宣告 USB 裝置上的介面。必須先聲明介面，才能將資料傳輸至介面或相關聯的端點。在任何指定時間，只有一個連線控制代碼可以宣告介面。如果介面已認領，這項呼叫就會失敗。

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

參數

  • 與裝置的開放連線。

  • interfaceNumber

    數字

    要要求的介面。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

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

closeDevice()

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

關閉連線控制代碼。在控制代碼關閉後叫用作業是安全的，但不會執行任何動作。

參數

傳回

  • 承諾<void>

    Chrome 116 以上版本

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

controlTransfer()

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

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

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

參數

傳回

  • Chrome 116 以上版本

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

findDevices()

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

尋找由廠商、產品和介面 ID (選用) 指定的 USB 裝置，並在權限允許的情況下開啟裝置。

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

呼叫這個方法，等同於先呼叫 getDevices，再為每部裝置呼叫 openDevice。

參數

傳回

  • Promise<ConnectionHandle[]>

    Chrome 116 以上版本

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

getConfiguration()

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

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

參數

傳回

  • Chrome 116 以上版本

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

getConfigurations()

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

傳回整組裝置設定描述元。

參數

傳回

  • Promise<ConfigDescriptor[]>

    Chrome 116 以上版本

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

getDevices()

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

列舉已連接的 USB 裝置。

參數

傳回

  • Promise<Device[]>

    Chrome 116 以上版本

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

getUserSelectedDevices()

Promise 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
): Promise<Device[]>

向使用者顯示裝置挑選器，並傳回所選的 Device。如果使用者取消挑選器，裝置就會是空白。必須有使用者手勢，系統才會顯示對話方塊。如果沒有使用者手勢，回呼會像使用者取消一樣執行。

參數

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

  • callback

    函式 選填

    callback 參數如下： 

    (devices: Device[]) => void

傳回

  • Promise<Device[]>

    Chrome 116 以上版本

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

interruptTransfer()

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

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

參數

傳回

  • Chrome 116 以上版本

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

isochronousTransfer()

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

在特定裝置上執行等時傳輸。

參數

傳回

  • Chrome 116 以上版本

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

listInterfaces()

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

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

參數

傳回

  • Chrome 116 以上版本

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

openDevice()

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

開啟 getDevices 傳回的 USB 裝置。

參數

傳回

  • Chrome 116 以上版本

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

releaseInterface()

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

釋出已聲明的介面。

參數

  • 與裝置的開放連線。

  • interfaceNumber

    數字

    要釋出的介面。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

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

requestAccess()

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

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

如果裝置上的指定介面未由 ChromeOS 宣告，則向權限代理程式要求存取 ChromeOS 宣告的裝置。

參數

  • 裝置

    裝置

    要要求存取權的 Device。

  • interfaceId

    數字

    要求的特定介面。

  • callback

    函式 選填

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

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

resetDevice()

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

嘗試重設 USB 裝置。如果重設失敗，系統會關閉指定的連線控制代碼，USB 裝置會顯示為中斷連線，然後重新連線。在這種情況下，必須再次呼叫 getDevices 或 findDevices 才能取得裝置。

參數

  • 要重設的連線控制代碼。

  • callback

    函式 選填

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

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

setConfiguration()

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

選取裝置設定。

這項功能會選取裝置的其中一項可用設定，有效重設裝置。只有大於 0 的設定值才有效，但部分有錯誤的裝置具有有效的設定 0，因此允許這個值。

參數

  • 與裝置的開放連線。

  • configurationValue

    數字

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

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

setInterfaceAlternateSetting()

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

在先前要求的介面上選取替代設定。

參數

  • 與已宣告這個介面的裝置建立開放連線。

  • interfaceNumber

    數字

    要設定的介面。

  • alternateSetting

    數字

    要設定的替代設定。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

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

事件

onDeviceAdded

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

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

參數

  • callback

    函式

    callback 參數如下： 

    (device: Device) => void

onDeviceRemoved

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

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

參數

  • callback

    函式

    callback 參數如下： 

    (device: Device) => void