chrome.usb

說明

使用 chrome.usb API 與連線的 USB 裝置互動。這項 API 可在應用程式環境中存取 USB 作業。應用程式可使用這項 API 做為硬體裝置的驅動程式。如要回報這個 API 產生的錯誤，請設定 runtime.lastError 並執行函式的常規回呼。在這種情況下，回呼的常規參數會是未定義。

權限

usb

類型

ConfigDescriptor

屬性

  • 已啟用

    布林值

    Chrome 47 以上版本

    這是有效設定嗎？

  • configurationValue

    數字

    設定編號。

  • 說明

    字串 選填

    設定說明。

  • extra_data

    ArrayBuffer

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

  • 可用介面。

  • maxPower

    數字

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

  • remoteWakeup

    布林值

    裝置支援遠端喚醒功能。

  • selfPowered

    布林值

    裝置自行供電。

ConnectionHandle

屬性

  • 帳號

    數字

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

  • productId

    數字

    產品 ID。

  • vendorId

    數字

    裝置供應商 ID。

ControlTransferInfo

屬性

  • 資料

    ArrayBuffer 選填

    要傳輸的資料 (僅限輸出移轉)。

  • 方向

    方向

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

  • 索引

    數字

    wIndex 欄位，請參閱「Ibid」Ibid。

  • 長度

    號碼 選填

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

  • 獲贈者

    收件者

    轉移目標。如果為 "interface" 或 "endpoint"，則必須聲明 index 提供的目標。

  • 申請。

    數字

    bRequest 欄位，請參閱《通用序列匯流排規格修訂版 1.1》第 9.3 節。

  • requestType

    RequestType

    要求類型。

  • 逾時

    號碼 選填

    Chrome 43 以上版本

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

  • 值

    數字

    wValue 欄位，請參閱「Ibid」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 規格中的同名項目。

列舉

「位於」

「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」

「介面」

「endpoint」

「other」

RequestType

列舉

「standard」

「class」

「vendor」

「reserved」

SynchronizationType

如果是中斷和同步模式，SynchronizationType 和 UsageType 會對應至 USB 規格中的同名項目。

列舉

「asynchronous」

「adaptive」

「synchronous」

TransferResultInfo

屬性

  • 資料

    ArrayBuffer 選填

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

  • resultCode

    號碼 選填

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

TransferType

列舉

「control」

「interrupt」

「isochronous」

「大量」

UsageType

列舉

「data」

「feedback」

「explicitFeedback」

「periodic」

「notification」

方法

bulkTransfer()

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

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

參數

傳回

  • Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

claimInterface()

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

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

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

參數

  • 與裝置建立連線。

  • interfaceNumber

    數字

    要聲明的介面。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

closeDevice()

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

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

參數

傳回

  • Promise<void>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

controlTransfer()

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

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

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

參數

傳回

  • Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

findDevices()

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

找出由供應商、產品和 (選用) 介面 ID 指定的 USB 裝置，並在權限允許的情況下開啟這些裝置以供使用。

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

呼叫這個方法等同於呼叫 getDevices，然後為每個裝置呼叫 openDevice。

參數

傳回

  • Promise<ConnectionHandle[]>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getConfiguration()

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

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

參數

傳回

  • Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getConfigurations()

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

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

參數

傳回

  • Promise<ConfigDescriptor[]>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getDevices()

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

列舉已連線的 USB 裝置。

參數

傳回

  • Promise<Device[]>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getUserSelectedDevices()

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

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

參數

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

  • callback

    函式 選用

    callback 參數如下： 

    (devices: Device[]) => void

傳回

  • Promise<Device[]>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

interruptTransfer()

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

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

參數

傳回

  • Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

isochronousTransfer()

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

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

參數

傳回

  • Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

listInterfaces()

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

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

參數

傳回

  • Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

openDevice()

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

開啟 getDevices 傳回的 USB 裝置。

參數

傳回

  • Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

releaseInterface()

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

釋放已聲明的介面。

參數

  • 與裝置建立連線。

  • interfaceNumber

    數字

    要釋出的介面。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

requestAccess()

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

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

如果裝置上的指定介面未聲明擁有權，則向權限代理人要求存取 ChromeOS 聲明的裝置。

參數

  • 裝置

    裝置

    要要求存取權的 Device。

  • interfaceId

    數字

    要求的特定介面。

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

resetDevice()

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

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

參數

  • 要重設的連線控點。

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setConfiguration()

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

選取裝置設定。

選取裝置的可用設定之一，即可有效重設裝置。只有大於 0 的設定值有效，但部分有錯誤的裝置具有有效的 0 設定，因此允許這個值。

參數

  • 與裝置建立連線。

  • configurationValue

    數字

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setInterfaceAlternateSetting()

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

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

參數

  • 與已聲明擁有這個介面的裝置建立開放式連線。

  • interfaceNumber

    數字

    要設定的介面。

  • alternateSetting

    數字

    要設定的替代設定。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

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