說明
使用 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
要求類型。
-
逾時
數字 選填
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
數字 選填
輪詢間隔 (僅限中斷和個別週期)。
-
同步處理
傳輸同步處理模式 (僅限獨立模式)。
-
類型
移轉作業類型。
-
用量
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
可用的端點。
-
extra_data
ArrayBuffer
與這個介面相關聯的額外描述元資料。
-
interfaceClass
號碼
USB 介面類別。
-
interfaceNumber
號碼
介面編號。
-
interfaceProtocol
號碼
USB 介面通訊協定。
-
interfaceSubclass
號碼
USB 介面子類別。
IsochronousTransferInfo
屬性
-
packetLength
號碼
這項傳輸作業中每個封包的長度。
-
封包
號碼
這項傳輸作業中的封包總數。
-
transferInfo
轉移參數。此參數區塊中指定的傳輸長度或資料緩衝區會沿著
packetLength
邊界分割,形成傳輸的個別封包。
Recipient
列舉
"endpoint"
RequestType
列舉
SynchronizationType
針對中斷模式和獨立模式,SynchronizationType 和 UsageType 會對應到 USB 規格中的名稱。
列舉
TransferResultInfo
屬性
-
資料或曾存取這類資料的人員
ArrayBuffer 選用
輸入移轉作業傳回的資料。
undefined
用於輸出傳輸。 -
resultCode
數字 選填
如果值為
0
,表示轉移作業已成功完成。其他值則表示失敗。
TransferType
列舉
"bulk"
UsageType
列舉
方法
bulkTransfer()
chrome.usb.bulkTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
在指定裝置中執行大量轉移作業。
參數
-
開放的裝置連線。
-
transferInfo
轉移參數。
-
回呼
函式選用
callback
參數如下所示:(info: TransferResultInfo) => void
傳回
-
Promise<TransferResultInfo>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
claimInterface()
chrome.usb.claimInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
領取 USB 裝置的介面。您必須先聲明介面的擁有權,才能將資料轉移至介面或相關聯的端點。在任何特定時間內,系統只能有一個連線控制代碼。如果已認領介面,則呼叫會失敗。
如果不再需要介面,則應呼叫 releaseInterface
。
參數
-
開放的裝置連線。
-
interfaceNumber
號碼
要聲明的介面。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
closeDevice()
chrome.usb.closeDevice(
handle: ConnectionHandle,
callback?: function,
)
關閉連線控制點。在帳號代碼關閉後叫用作業屬於安全作業,因此無須採取任何行動。
參數
-
要關閉的
ConnectionHandle
。 -
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
controlTransfer()
chrome.usb.controlTransfer(
handle: ConnectionHandle,
transferInfo: ControlTransferInfo,
callback?: function,
)
在指定裝置執行控制項轉移。
控制傳輸是指裝置、介面或端點。必須先聲明介面擁有權,才能轉移至介面或端點。
參數
-
開放的裝置連線。
-
transferInfo
-
回呼
函式選用
callback
參數如下所示:(info: TransferResultInfo) => void
傳回
-
Promise<TransferResultInfo>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
findDevices()
chrome.usb.findDevices(
options: EnumerateDevicesAndRequestAccessOptions,
callback?: function,
)
尋找廠商、產品和 (選用) 介面 ID 指定的 USB 裝置,以及是否允許開啟並使用這些裝置。
如果存取要求遭拒,或裝置無法開啟連線控制代碼,系統就不會建立或傳回裝置。
呼叫這個方法相當於在每部裝置呼叫 getDevices
後接著呼叫 openDevice
。
參數
-
要在目標裝置上搜尋的屬性。
-
回呼
函式選用
callback
參數如下所示:(handles: ConnectionHandle[]) => void
-
帳號代碼
-
傳回
-
Promise<ConnectionHandle[]>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getConfiguration()
chrome.usb.getConfiguration(
handle: ConnectionHandle,
callback?: function,
)
取得目前所選設定的設定描述元。
參數
-
開放的裝置連線。
-
回呼
函式選用
callback
參數如下所示:(config: ConfigDescriptor) => void
-
config
-
傳回
-
Promise<ConfigDescriptor>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getConfigurations()
chrome.usb.getConfigurations(
device: Device,
callback?: function,
)
傳回完整的裝置設定描述元集。
參數
-
裝置
用來擷取描述元的
Device
。 -
回呼
函式選用
callback
參數如下所示:(configs: ConfigDescriptor[]) => void
-
configs
-
傳回
-
Promise<ConfigDescriptor[]>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getDevices()
chrome.usb.getDevices(
options: EnumerateDevicesOptions,
callback?: function,
)
列舉已連線的 USB 裝置。
參數
傳回
-
Promise<裝置[]>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getUserSelectedDevices()
chrome.usb.getUserSelectedDevices(
options: DevicePromptOptions,
callback?: function,
)
向使用者顯示裝置挑選器,並傳回選取的 Device
。如果使用者取消挑選工具裝置,畫面上就不會顯示任何內容。需要使用者手勢才會顯示對話方塊。如果沒有使用者手勢,回呼將以使用者取消的狀態執行。
參數
傳回
-
Promise<裝置[]>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
interruptTransfer()
chrome.usb.interruptTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
在指定裝置執行中斷傳輸。
參數
-
開放的裝置連線。
-
transferInfo
轉移參數。
-
回呼
函式選用
callback
參數如下所示:(info: TransferResultInfo) => void
傳回
-
Promise<TransferResultInfo>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
isochronousTransfer()
chrome.usb.isochronousTransfer(
handle: ConnectionHandle,
transferInfo: IsochronousTransferInfo,
callback?: function,
)
在特定裝置上執行獨立傳輸作業。
參數
-
開放的裝置連線。
-
transferInfo
-
回呼
函式選用
callback
參數如下所示:(info: TransferResultInfo) => void
傳回
-
Promise<TransferResultInfo>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
listInterfaces()
chrome.usb.listInterfaces(
handle: ConnectionHandle,
callback?: function,
)
列出 USB 裝置上的所有介面。
參數
-
開放的裝置連線。
-
回呼
函式選用
callback
參數如下所示:(descriptors: InterfaceDescriptor[]) => void
-
descriptors
-
傳回
-
Promise<InterfaceDescriptor[]>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
openDevice()
chrome.usb.openDevice(
device: Device,
callback?: function,
)
開啟 getDevices
傳回的 USB 裝置。
參數
-
裝置
要開啟的
Device
。 -
回呼
函式選用
callback
參數如下所示:(handle: ConnectionHandle) => void
傳回
-
Promise<ConnectionHandle>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
releaseInterface()
chrome.usb.releaseInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
釋出已聲明的介面。
參數
-
開放的裝置連線。
-
interfaceNumber
號碼
要發布的介面。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
requestAccess()
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()
chrome.usb.resetDevice(
handle: ConnectionHandle,
callback?: function,
)
嘗試重設 USB 裝置。如果重設失敗,系統會關閉指定連線控點,USB 裝置會恢復連線。在這種情況下,必須再次呼叫 getDevices
或 findDevices
才能取得裝置。
參數
-
要重設的連線控制點。
-
回呼
函式選用
callback
參數如下所示:(success: boolean) => void
-
成功
boolean
-
傳回
-
Promise<boolean>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setConfiguration()
chrome.usb.setConfiguration(
handle: ConnectionHandle,
configurationValue: number,
callback?: function,
)
選取裝置設定。
這項功能會選取裝置內的其中一項可用設定,藉此有效地重設裝置。只有大於 0
的設定值才有效,但部分裝置的設定具有 0
作用,因此可以存取這個值。
參數
-
開放的裝置連線。
-
configurationValue
號碼
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setInterfaceAlternateSetting()
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
時授予。
onDeviceRemoved
chrome.usb.onDeviceRemoved.addListener(
callback: function,
)
從系統中移除裝置時產生的事件。如要瞭解哪些事件會傳送事件,請參閱 onDeviceAdded
。