Nội dung mô tả
Sử dụng API chrome.usb
để tương tác với các thiết bị USB đã kết nối. API này cấp quyền truy cập vào các thao tác USB từ trong ngữ cảnh của một ứng dụng. Khi sử dụng API này, các ứng dụng có thể hoạt động như trình điều khiển cho thiết bị phần cứng. Các lỗi do API này tạo ra được báo cáo bằng cách đặt runtime.lastError
và thực thi lệnh gọi lại thông thường của hàm. Trong trường hợp này, các tham số thông thường của lệnh gọi lại sẽ không được xác định.
Quyền
usb
Loại
ConfigDescriptor
Thuộc tính
-
hoạt động
boolean
Chrome 47 trở lênĐây có phải là cấu hình đang hoạt động không?
-
configurationValue
number
Số cấu hình.
-
description
chuỗi không bắt buộc
Mô tả về cấu hình.
-
extra_data
ArrayBuffer
Dữ liệu bổ sung về mã mô tả được liên kết với cấu hình này.
-
giao diện
Các giao diện hiện có.
-
maxPower
number
Công suất tối đa cần thiết cho thiết bị này, tính bằng milliamp (mA).
-
remoteWakeup
boolean
Thiết bị hỗ trợ tính năng đánh thức từ xa.
-
selfPowered
boolean
Thiết bị này là thiết bị tự chạy nguồn.
ConnectionHandle
Thuộc tính
-
handle
number
Một ô điều khiển mờ biểu thị kết nối này với thiết bị USB cũng như tất cả giao diện được xác nhận quyền sở hữu liên kết cũng như các hoạt động chuyển đang chờ xử lý. Một tên người dùng mới sẽ được tạo mỗi khi thiết bị được mở. Tên người dùng kết nối khác với
Device.device
. -
productId
number
Mã sản phẩm.
-
vendorId
number
Mã nhà cung cấp thiết bị.
ControlTransferInfo
Thuộc tính
-
data
ArrayBuffer không bắt buộc
Dữ liệu cần truyền (chỉ yêu cầu khi chuyển dữ liệu đầu ra).
-
direction
Hướng chuyển (
"in"
hoặc"out"
). -
index
number
Trường
wIndex
, hãy xem Ibid. -
chiều dài
số không bắt buộc
Số byte tối đa cần nhận (chỉ bắt buộc khi chuyển dữ liệu đầu vào).
-
người nhận
Mục tiêu chuyển. Mục tiêu do
index
đưa ra phải được xác nhận nếu"interface"
hoặc"endpoint"
. -
request
number
Trường
bRequest
, hãy xem Bản sửa đổi thông số kỹ thuật của Universal Serial Bus 1.1 § 9.3. -
requestType
Loại yêu cầu.
-
tạm ngừng
số không bắt buộc
Chrome 43 trở lênThời gian chờ của yêu cầu (tính bằng mili giây). Giá trị mặc định
0
cho biết không có thời gian chờ. -
value
number
Trường
wValue
, hãy xem Ibid.
Device
Thuộc tính
-
thiết bị
number
Mã nhận dạng không rõ ràng cho thiết bị USB. Chế độ này sẽ không thay đổi cho đến khi bạn rút thiết bị ra khỏi nguồn điện.
-
manufacturerName
string
Chrome 46 trở lênChuỗi iManufacturer đọc từ thiết bị, nếu có.
-
productId
number
Mã sản phẩm.
-
productName
string
Chrome 46 trở lênChuỗi iProduct được đọc từ thiết bị (nếu có).
-
serialNumber
string
Chrome 46 trở lênChuỗi iSerialNumber đọc từ thiết bị, nếu có.
-
vendorId
number
Mã nhà cung cấp thiết bị.
-
version
number
Chrome 51 trở lênPhiên bản thiết bị (trường bcdDevice).
DeviceFilter
Thuộc tính
-
interfaceClass
số không bắt buộc
Lớp giao diện USB, khớp với mọi giao diện trên thiết bị.
-
interfaceProtocol
số không bắt buộc
Giao thức giao diện USB, chỉ được kiểm tra nếu lớp con của giao diện trùng khớp.
-
interfaceSubclass
số không bắt buộc
Lớp con của giao diện USB, chỉ được kiểm tra nếu lớp giao diện khớp.
-
productId
số không bắt buộc
Mã sản phẩm của thiết bị, chỉ được kiểm tra nếu mã nhà cung cấp trùng khớp.
-
vendorId
số không bắt buộc
Mã nhà cung cấp thiết bị.
DevicePromptOptions
Thuộc tính
-
bộ lọc
DeviceFilter[] không bắt buộc
Lọc danh sách thiết bị mà người dùng nhìn thấy. Nếu bạn cung cấp nhiều bộ lọc, các thiết bị khớp với bộ lọc bất kỳ sẽ xuất hiện.
-
nhiều
boolean không bắt buộc
Cho phép người dùng chọn nhiều thiết bị.
Direction
Chỉ đường, Người nhận, Kích hoạt và TransferType đều ánh xạ tới tên của họ trong thông số kỹ thuật của USB.
Liệt kê
"in"
EndpointDescriptor
Thuộc tính
-
xử lý
number
Địa chỉ điểm cuối.
-
direction
Hướng chuyển.
-
extra_data
ArrayBuffer
Dữ liệu bổ sung về bộ mô tả được liên kết với điểm cuối này.
-
maximumPacketSize
number
Kích thước gói tin tối đa.
-
pollingInterval
số không bắt buộc
Khoảng thời gian thăm dò (chỉ gián đoạn và đồng thời).
-
việc đồng bộ hoá
SynchronizationType (Không bắt buộc) không bắt buộc
Chuyển chế độ đồng bộ hoá (chỉ đẳng cấp).
-
loại
Loại chuyển dữ liệu.
-
mức sử dụng
UsageType không bắt buộc
Gợi ý về việc sử dụng thiết bị đầu cuối.
EnumerateDevicesAndRequestAccessOptions
Thuộc tính
-
interfaceId
số không bắt buộc
Mã giao diện để yêu cầu quyền truy cập. Chỉ hoạt động trên ChromeOS. Chế độ này không ảnh hưởng đến các nền tảng khác.
-
productId
number
Mã sản phẩm.
-
vendorId
number
Mã nhà cung cấp thiết bị.
EnumerateDevicesOptions
Thuộc tính
-
bộ lọc
DeviceFilter[] không bắt buộc
Hệ thống sẽ trả về một thiết bị khớp với bộ lọc cụ thể bất kỳ. Danh sách bộ lọc trống sẽ trả về tất cả thiết bị mà ứng dụng có quyền truy cập.
-
productId
số không bắt buộc
Không dùng nữaTương đương với việc thiết lập
DeviceFilter.productId
. -
vendorId
số không bắt buộc
Không dùng nữaTương đương với việc thiết lập
DeviceFilter.vendorId
.
GenericTransferInfo
Thuộc tính
-
data
ArrayBuffer không bắt buộc
Dữ liệu cần truyền (chỉ yêu cầu khi chuyển dữ liệu đầu ra).
-
direction
Hướng chuyển (
"in"
hoặc"out"
). -
thiết bị đầu cuối
number
Địa chỉ điểm cuối đích. Giao diện chứa điểm cuối này phải được xác nhận quyền sở hữu.
-
chiều dài
số không bắt buộc
Số byte tối đa cần nhận (chỉ bắt buộc khi chuyển dữ liệu đầu vào).
-
tạm ngừng
số không bắt buộc
Chrome 43 trở lênThời gian chờ của yêu cầu (tính bằng mili giây). Giá trị mặc định
0
cho biết không có thời gian chờ.
InterfaceDescriptor
Thuộc tính
-
alternateSetting
number
Số của chế độ cài đặt thay thế giao diện (mặc định là
0
-
description
chuỗi không bắt buộc
Nội dung mô tả về giao diện.
-
thiết bị đầu cuối
Các điểm cuối hiện có.
-
extra_data
ArrayBuffer
Dữ liệu mô tả bổ sung được liên kết với giao diện này.
-
interfaceClass
number
Lớp giao diện USB.
-
interfaceNumber
number
Số giao diện.
-
interfaceProtocol
number
Giao thức giao diện USB.
-
interfaceSubclass
number
Lớp giao diện USB con.
IsochronousTransferInfo
Thuộc tính
-
packetLength
number
Độ dài của từng gói trong quá trình truyền này.
-
gói
number
Tổng số gói dữ liệu trong quá trình truyền.
-
transferInfo
Truyền thông số. Độ dài truyền hoặc vùng đệm dữ liệu được chỉ định trong khối tham số này được chia dọc theo ranh giới
packetLength
để tạo thành các gói truyền tải riêng lẻ.
Recipient
Liệt kê
"device"
"other"
RequestType
Liệt kê
SynchronizationType
Đối với chế độ gián đoạn và chế độ đồng thời, syncType và UsageType ánh xạ tới các tên được đặt trong thông số kỹ thuật USB.
Liệt kê
TransferResultInfo
Thuộc tính
-
data
ArrayBuffer không bắt buộc
Dữ liệu được trả về trong quá trình chuyển dữ liệu đầu vào.
undefined
để chuyển dữ liệu đầu ra. -
resultCode
số không bắt buộc
Giá trị
0
cho biết quá trình chuyển đã thành công. Các giá trị khác cho biết không thành công.
TransferType
Liệt kê
"control"
UsageType
Liệt kê
"data"
Phương thức
bulkTransfer()
chrome.usb.bulkTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
Thực hiện chuyển hàng loạt trên thiết bị được chỉ định.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
transferInfo
Các thông số chuyển.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(info: TransferResultInfo) => void
-
info
-
Giá trị trả về
-
Promise<TransferResultInfo>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
claimInterface()
chrome.usb.claimInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
Xác nhận quyền sở hữu giao diện trên thiết bị USB. Trước khi có thể chuyển dữ liệu sang một giao diện hoặc các điểm cuối được liên kết, giao diện đó phải được xác nhận quyền sở hữu. Tại một thời điểm bất kỳ, chỉ một tên người dùng kết nối có thể xác nhận quyền sở hữu giao diện. Nếu giao diện đã được xác nhận quyền sở hữu, lệnh gọi này sẽ không thực hiện được.
releaseInterface
sẽ được gọi khi giao diện không còn cần thiết nữa.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
interfaceNumber
number
Giao diện được xác nhận quyền sở hữu.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
closeDevice()
chrome.usb.closeDevice(
handle: ConnectionHandle,
callback?: function,
)
Đóng một điểm điều khiển kết nối. Việc gọi các thao tác trên ô điều khiển sau khi nó đã đóng là một hoạt động an toàn nhưng không dẫn đến việc thực hiện hành động nào.
Tham số
-
handle
ConnectionHandle
để đóng. -
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
controlTransfer()
chrome.usb.controlTransfer(
handle: ConnectionHandle,
transferInfo: ControlTransferInfo,
callback?: function,
)
Thực hiện quá trình chuyển quyền kiểm soát trên thiết bị được chỉ định.
Các hoạt động chuyển quyền kiểm soát đề cập đến thiết bị, giao diện hoặc điểm cuối. Để chuyển dữ liệu đến một giao diện hoặc điểm cuối, bạn phải xác nhận quyền sở hữu giao diện đó.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
transferInfo
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(info: TransferResultInfo) => void
-
info
-
Giá trị trả về
-
Promise<TransferResultInfo>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
findDevices()
chrome.usb.findDevices(
options: EnumerateDevicesAndRequestAccessOptions,
callback?: function,
)
Tìm các thiết bị USB do nhà cung cấp, sản phẩm và mã giao diện (không bắt buộc) chỉ định và xem các thiết bị đó có được cấp quyền hay không.
Nếu yêu cầu truy cập bị từ chối hoặc thiết bị không mở được, thì tay điều khiển kết nối sẽ không được tạo hoặc trả về.
Việc gọi phương thức này tương đương với việc gọi getDevices
, theo sau là openDevice
cho từng thiết bị.
Tham số
-
tùy chọn
Các thuộc tính cần tìm kiếm trên thiết bị mục tiêu.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(handles: ConnectionHandle[]) => void
-
tên người dùng
-
Giá trị trả về
-
Promise<ConnectionHandle[]>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
getConfiguration()
chrome.usb.getConfiguration(
handle: ConnectionHandle,
callback?: function,
)
Lấy chỉ số mô tả cấu hình cho cấu hình hiện được chọn.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(config: ConfigDescriptor) => void
-
cấu hình
-
Giá trị trả về
-
Promise<ConfigDescriptor>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
getConfigurations()
chrome.usb.getConfigurations(
device: Device,
callback?: function,
)
Trả về tập hợp đầy đủ các mã mô tả cấu hình thiết bị.
Tham số
-
thiết bị
Device
để tìm nạp mã mô tả. -
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(configs: ConfigDescriptor[]) => void
-
cấu hình
-
Giá trị trả về
-
Promise<ConfigDescriptor[]>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
getDevices()
chrome.usb.getDevices(
options: EnumerateDevicesOptions,
callback?: function,
)
Liệt kê các thiết bị USB đã kết nối.
Tham số
Giá trị trả về
-
Hứa hẹn<Thiết bị[]>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
getUserSelectedDevices()
chrome.usb.getUserSelectedDevices(
options: DevicePromptOptions,
callback?: function,
)
Hiển thị bộ chọn thiết bị cho người dùng và trả về Device
đã chọn. Nếu người dùng huỷ, các thiết bị trong bộ chọn sẽ trống. Cần có cử chỉ của người dùng để hộp thoại hiển thị. Nếu không có cử chỉ của người dùng, lệnh gọi lại sẽ chạy như thể người dùng đã huỷ.
Tham số
Giá trị trả về
-
Hứa hẹn<Thiết bị[]>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
interruptTransfer()
chrome.usb.interruptTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
Thực hiện quá trình chuyển gián đoạn trên thiết bị được chỉ định.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
transferInfo
Các thông số chuyển.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(info: TransferResultInfo) => void
-
info
-
Giá trị trả về
-
Promise<TransferResultInfo>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
isochronousTransfer()
chrome.usb.isochronousTransfer(
handle: ConnectionHandle,
transferInfo: IsochronousTransferInfo,
callback?: function,
)
Thực hiện quá trình chuyển không đồng thời trên thiết bị cụ thể.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
transferInfo
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(info: TransferResultInfo) => void
-
info
-
Giá trị trả về
-
Promise<TransferResultInfo>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
listInterfaces()
chrome.usb.listInterfaces(
handle: ConnectionHandle,
callback?: function,
)
Liệt kê tất cả giao diện trên một thiết bị USB.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(descriptors: InterfaceDescriptor[]) => void
-
descriptors
-
Giá trị trả về
-
Promise<InterfaceDescriptor[]>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
openDevice()
chrome.usb.openDevice(
device: Device,
callback?: function,
)
Mở một thiết bị USB do getDevices
trả về.
Tham số
-
thiết bị
Device
để mở. -
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(handle: ConnectionHandle) => void
-
handle
-
Giá trị trả về
-
Promise<ConnectionHandle>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
releaseInterface()
chrome.usb.releaseInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
Phát hành giao diện đã được xác nhận quyền sở hữu.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
interfaceNumber
number
Giao diện sắp được phát hành.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
requestAccess()
chrome.usb.requestAccess(
device: Device,
interfaceId: number,
callback?: function,
)
Chức năng này dành riêng cho ChromeOS và không gọi được trên các nền tảng khác. Thao tác này hiện được ngầm thực hiện trong openDevice
và hàm này sẽ trả về true
trên tất cả nền tảng.
Yêu cầu trình môi giới cấp quyền truy cập vào một thiết bị được Chrome OS xác nhận quyền sở hữu nếu giao diện đã cho trên thiết bị không được xác nhận quyền sở hữu.
Tham số
-
thiết bị
Device
để yêu cầu quyền truy cập. -
interfaceId
number
Giao diện cụ thể được yêu cầu.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(success: boolean) => void
-
thành công
boolean
-
Giá trị trả về
-
Promise<boolean>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
resetDevice()
chrome.usb.resetDevice(
handle: ConnectionHandle,
callback?: function,
)
Thử đặt lại thiết bị USB. Nếu quá trình đặt lại không thành công, tay điều khiển kết nối đã cho sẽ đóng và thiết bị USB có vẻ như đã bị ngắt kết nối rồi kết nối lại. Trong trường hợp này, bạn phải gọi lại getDevices
hoặc findDevices
để lấy thiết bị.
Tham số
-
handle
Một trình xử lý kết nối để đặt lại.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(success: boolean) => void
-
thành công
boolean
-
Giá trị trả về
-
Promise<boolean>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
setConfiguration()
chrome.usb.setConfiguration(
handle: ConnectionHandle,
configurationValue: number,
callback?: function,
)
Chọn một cấu hình thiết bị.
Hàm này đặt lại thiết bị một cách hiệu quả bằng cách chọn một trong các cấu hình có sẵn của thiết bị. Chỉ các giá trị cấu hình lớn hơn 0
mới hợp lệ. Tuy nhiên, một số thiết bị có lỗi có cấu hình đang hoạt động 0
nên giá trị này được cho phép.
Tham số
-
handle
Kết nối đang mở với thiết bị.
-
configurationValue
number
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
setInterfaceAlternateSetting()
chrome.usb.setInterfaceAlternateSetting(
handle: ConnectionHandle,
interfaceNumber: number,
alternateSetting: number,
callback?: function,
)
Chọn chế độ cài đặt thay thế trên giao diện đã được xác nhận quyền sở hữu trước đó.
Tham số
-
handle
Kết nối đang mở tới thiết bị mà giao diện này đã được xác nhận quyền sở hữu.
-
interfaceNumber
number
Giao diện để định cấu hình.
-
alternateSetting
number
Chế độ cài đặt thay thế để định cấu hình.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 116 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
Sự kiện
onDeviceAdded
chrome.usb.onDeviceAdded.addListener(
callback: function,
)
Sự kiện được tạo khi một thiết bị được thêm vào hệ thống. Sự kiện chỉ được truyền đến các ứng dụng và tiện ích có quyền truy cập vào thiết bị. Quyền có thể đã được cấp tại thời điểm cài đặt, khi người dùng chấp nhận một quyền không bắt buộc (xem permissions.request
) hoặc thông qua getUserSelectedDevices
.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(device: Device) => void
-
thiết bị
-
onDeviceRemoved
chrome.usb.onDeviceRemoved.addListener(
callback: function,
)
Sự kiện được tạo khi một thiết bị bị xoá khỏi hệ thống. Xem onDeviceAdded
cho những sự kiện được phân phối.