chrome.usb

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 cung cấp quyền truy cập vào các hoạt động USB trong bối 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. 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

Phạm vi cung cấp

Chỉ dành cho ChromeOS

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

    số

    Số cấu hình.

  • mô tả

    chuỗi không bắt buộc

    Nội dung mô tả về cấu hình.

  • extra_data

    ArrayBuffer

    Dữ liệu mô tả bổ sung liên kết với cấu hình này.

  • giao diện

    InterfaceDescriptor[]

    Giao diện hiện có.

  • maxPower

    số

    Công suất tối đa mà thiết bị này cần, tính bằng miliampe (mA).

  • remoteWakeup

    boolean

    Thiết bị hỗ trợ tính năng đánh thức từ xa.

  • selfPowered

    boolean

    Thiết bị tự cấp nguồn.

ConnectionHandle

Thuộc tính

  • handle

    số

    Một handle mờ đại diện cho kết nối này với thiết bị USB và tất cả giao diện được xác nhận quyền sở hữu 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

    số

    Mã sản phẩm.

  • vendorId

    số

    Mã nhà cung cấp thiết bị.

ControlTransferInfo

Thuộc tính

  • khác

    Không bắt buộc ArrayBuffer

    Dữ liệu cần truyền (chỉ bắt buộc đối với các hoạt động chuyển dữ liệu đầu ra).

  • chỉ đường

    Hướng dẫn

    Hướng chuyển ("in" hoặc "out").

  • index

    số

    Trường wIndex, hãy xem Ibid.

  • chiều dài

    number không bắt buộc

    Số byte tối đa cần nhận (chỉ bắt buộc đối với các lượt chuyển dữ liệu đầu vào).

  • người nhận

    Người nhận

    Đích chuyển. Bạn phải xác nhận quyền sở hữu mục tiêu do index cung cấp nếu "interface" hoặc "endpoint".

  • request

    số

    Trường bRequest, xem Bản sửa đổi thông số kỹ thuật của Buýt nối tiếp đa năng 1.1 § 9.3.

  • requestType

    RequestType

    Loại yêu cầu.

  • tạm ngừng

    number không bắt buộc

    Chrome 43 trở lên

    Thời gian chờ 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

    số

    Trường wValue, hãy xem Ibid.

Device

Thuộc tính

  • thiết bị

    số

    Mã nhận dạng mờ cho thiết bị USB. Trạng thái này không thay đổi cho đến khi thiết bị được rút phích cắm.

  • manufacturerName

    chuỗi

    Chrome 46 trở lên

    Chuỗi iManufacturer được đọc từ thiết bị, nếu có.

  • productId

    số

    Mã sản phẩm.

  • Tên sản phẩm

    chuỗi

    Chrome 46 trở lên

    Chuỗi iProduct đọc được từ thiết bị, nếu có.

  • serialNumber

    chuỗi

    Chrome 46 trở lên

    Chuỗi iSerialNumber đọc được từ thiết bị, nếu có.

  • vendorId

    số

    Mã nhà cung cấp thiết bị.

  • phiên bản

    số

    Chrome 51 trở lên

    Phiên bản thiết bị (trường bcdDevice).

DeviceFilter

Thuộc tính

  • interfaceClass

    number 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

    number 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 khớp.

  • interfaceSubclass

    number 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

    number 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 khớp.

  • vendorId

    number 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ị hiển thị cho người dùng. Nếu bạn cung cấp nhiều bộ lọc, thì những thiết bị khớp với bất kỳ bộ lọc nào cũng 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

Direction, Recipient, RequestType và TransferType đều liên kết với các tên tương ứng trong thông số kỹ thuật USB.

Enum

"in"

"out"

EndpointDescriptor

Thuộc tính

  • xử lý

    số

    Địa chỉ điểm cuối.

  • chỉ đường

    Hướng dẫn

    Hướng chuyển.

  • extra_data

    ArrayBuffer

    Dữ liệu mô tả bổ sung liên kết với điểm cuối này.

  • maximumPacketSize

    số

    Kích thước gói tối đa.

  • pollingInterval

    number không bắt buộc

    Khoảng thời gian thăm dò ý kiến (chỉ ngắt và đồng bộ).

  • đồng bộ hoá

    SynchronizationType không bắt buộc

    Chế độ đồng bộ hoá chuyển (chỉ đẳng thời).

  • loại

    TransferType

    Loại chuyển cuộc gọi.

  • mức sử dụng

    UsageType không bắt buộc

    Gợi ý về cách sử dụng điểm cuối.

EnumerateDevicesAndRequestAccessOptions

Thuộc tính

  • interfaceId

    number không bắt buộc

    Mã giao diện để yêu cầu quyền truy cập. Chỉ có trên ChromeOS. Lựa chọn ưu tiên này không ảnh hưởng đến các nền tảng khác.

  • productId

    số

    Mã sản phẩm.

  • vendorId

    số

    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ề thiết bị khớp với bất kỳ bộ lọc nào đã cho. 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

    number không bắt buộc

    Không dùng nữa

    Tương đương với việc đặt DeviceFilter.productId.

  • vendorId

    number không bắt buộc

    Không dùng nữa

    Tương đương với việc đặt DeviceFilter.vendorId.

GenericTransferInfo

Thuộc tính

  • khác

    Không bắt buộc ArrayBuffer

    Dữ liệu cần truyền (chỉ bắt buộc đối với các hoạt động chuyển dữ liệu đầu ra).

  • chỉ đường

    Hướng dẫn

    Hướng chuyển ("in" hoặc "out").

  • điểm cuối

    số

    Địa chỉ điểm cuối đích. Bạn phải xác nhận quyền sở hữu giao diện chứa điểm cuối này.

  • chiều dài

    number không bắt buộc

    Số byte tối đa cần nhận (chỉ bắt buộc đối với các lượt chuyển dữ liệu đầu vào).

  • tạm ngừng

    number không bắt buộc

    Chrome 43 trở lên

    Thời gian chờ 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

    số

    Số cài đặt thay thế của giao diện (mặc định là 0

  • mô tả

    chuỗi không bắt buộc

    Nội dung mô tả về giao diện.

  • điểm cuối

    EndpointDescriptor[]

    Điểm cuối hiện có.

  • extra_data

    ArrayBuffer

    Dữ liệu mô tả bổ sung liên kết với giao diện này.

  • interfaceClass

    số

    Lớp giao diện USB.

  • interfaceNumber

    số

    Số giao diện.

  • interfaceProtocol

    số

    Giao thức giao diện USB.

  • interfaceSubclass

    số

    Lớp con của giao diện USB.

IsochronousTransferInfo

Thuộc tính

  • packetLength

    số

    Độ dài của mỗi gói trong lần chuyển này.

  • gói tin

    số

    Tổng số gói trong lần chuyển này.

  • transferInfo

    GenericTransferInfo

    Tham số chuyển. Độ dài truyền hoặc vùng đệm dữ liệu được chỉ định trong khối tham số này được phân tách dọc theo ranh giới packetLength để tạo thành các gói riêng lẻ của quá trình truyền.

Recipient

Enum

"device"

"interface"

"endpoint"

"other"

RequestType

Enum

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

Đối với chế độ ngắt và chế độ đẳng thời, SynchronizationType và UsageType sẽ liên kết với tên của chúng trong thông số kỹ thuật USB.

Enum

"asynchronous"

"adaptive"

"đồng bộ"

TransferResultInfo

Thuộc tính

  • khác

    Không bắt buộc ArrayBuffer

    Dữ liệu được trả về bằng một quá trình chuyển dữ liệu đầu vào. undefined cho các lần chuyển dữ liệu ra ngoài.

  • resultCode

    number 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 lỗi.

TransferType

Enum

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

Enum

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Phương thức

bulkTransfer()

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

Thực hiện chuyển hàng loạt trên thiết bị được chỉ định.

Thông số

Giá trị trả về

  • Chrome 116 trở lên

    Lờ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()

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

Xác nhận quyền sở hữu một giao diện trên thiết bị USB. Trước khi có thể chuyển dữ liệu đến một giao diện hoặc các điểm cuối liên kết, bạn phải xác nhận quyền sở hữu giao diện đó. Chỉ một tay điều khiển kết nối có thể xác nhận quyền sở hữu một giao diện tại bất kỳ thời điểm nào. Nếu giao diện đã được xác nhận quyền sở hữu, thì lệnh gọi này sẽ không thành công.

Bạn nên gọi releaseInterface khi không cần giao diện nữa.

Thông số

  • Một kết nối mở với thiết bị.

  • interfaceNumber

    số

    Giao diện cần xác nhận quyền sở hữu.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 116 trở lên

    Lờ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()

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

Đóng một tay điều khiển kết nối. Việc gọi các thao tác trên một tay điều khiển sau khi tay điều khiển đó đã đóng là một thao tác an toàn nhưng không có hành động nào được thực hiện.

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 116 trở lên

    Lờ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()

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

Thực hiện chuyển quyền kiểm soát trên thiết bị được chỉ định.

Quá trình chuyển dữ liệu điều khiển liên quan đến thiết bị, giao diện hoặc điểm cuối. Để chuyển sang 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 đó.

Thông số

Giá trị trả về

  • Chrome 116 trở lên

    Lờ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()

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

Tìm 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à nếu quyền cho phép thì mở các thiết bị đó để sử dụng.

Nếu yêu cầu truy cập bị từ chối hoặc thiết bị không mở được, thì trình xử lý 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, sau đó gọi openDevice cho từng thiết bị.

Thông số

Giá trị trả về

  • Promise<ConnectionHandle[]>

    Chrome 116 trở lên

    Lờ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()

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

Lấy chỉ số mô tả cấu hình cho cấu hình hiện được chọn.

Thông số

Giá trị trả về

  • Chrome 116 trở lên

    Lờ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()

Promise Chrome 47 trở lên 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

Trả về tập hợp đầy đủ các chỉ số mô tả cấu hình thiết bị.

Thông số

Giá trị trả về

  • Promise<ConfigDescriptor[]>

    Chrome 116 trở lên

    Lờ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()

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

Liệt kê các thiết bị USB đã kết nối.

Thông số

  • Các thuộc tính cần tìm kiếm trên thiết bị mục tiêu.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (devices: Device[]) => void

Giá trị trả về

  • Promise<Device[]>

    Chrome 116 trở lên

    Lờ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()

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

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ỷ bộ chọn, thì danh sách thiết bị 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ỷ.

Thông số

  • tùy chọn

    DevicePromptOptions

    Cấu hình của hộp thoại bộ chọn thiết bị.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (devices: Device[]) => void

Giá trị trả về

  • Promise<Device[]>

    Chrome 116 trở lên

    Lờ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()

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

Thực hiện chuyển giao ngắt trên thiết bị được chỉ định.

Thông số

Giá trị trả về

  • Chrome 116 trở lên

    Lờ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()

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

Thực hiện chuyển dữ liệu đồng bộ trên thiết bị cụ thể.

Thông số

Giá trị trả về

  • Chrome 116 trở lên

    Lờ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()

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

Liệt kê tất cả giao diện trên một thiết bị USB.

Thông số

Giá trị trả về

  • Chrome 116 trở lên

    Lờ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()

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

Mở thiết bị USB do getDevices trả về.

Thông số

Giá trị trả về

  • Chrome 116 trở lên

    Lờ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()

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

Giải phóng một giao diện đã xác nhận quyền sở hữu.

Thông số

  • Một kết nối mở với thiết bị.

  • interfaceNumber

    số

    Giao diện sẽ được phát hành.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 116 trở lên

    Lờ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()

Promise Không dùng nữa
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
): Promise<boolean>

Hàm này dành riêng cho ChromeOS và việc gọi hàm này trên các nền tảng khác sẽ không thành công. Thao tác này hiện được thực hiện ngầm định trong openDevice và hàm này sẽ trả về true trên tất cả nền tảng.

Yêu cầu quyền truy cập từ trình quản lý quyền vào một thiết bị do ChromeOS xác nhận quyền sở hữu nếu giao diện đã cho trên thiết bị đó chưa được xác nhận quyền sở hữu.

Thông số

  • thiết bị

    Thiết bị

    Device để yêu cầu quyền truy cập.

  • interfaceId

    số

    Giao diện cụ thể được yêu cầu.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (success: boolean) => void

    • thành công

      boolean

Giá trị trả về

  • Promise<boolean>

    Chrome 116 trở lên

    Lờ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()

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

Cố gắng đặt lại thiết bị USB. Nếu không đặt lại được, thì trình xử lý kết nối đã cho sẽ bị đóng và thiết bị USB sẽ 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ị.

Thông số

  • Một tên người dùng kết nối để đặt lại.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (success: boolean) => void

    • thành công

      boolean

Giá trị trả về

  • Promise<boolean>

    Chrome 116 trở lên

    Lờ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()

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

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 hoạt động 0 nên giá trị này được cho phép.

Thông số

  • Một kết nối mở với thiết bị.

  • configurationValue

    số

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 116 trở lên

    Lờ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()

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

Chọn một chế độ cài đặt thay thế trên giao diện đã xác nhận quyền sở hữu trước đó.

Thông số

  • Một kết nối mở với thiết bị mà giao diện này đã được xác nhận quyền sở hữu.

  • interfaceNumber

    số

    Giao diện cần định cấu hình.

  • alternateSetting

    số

    Chế độ cài đặt thay thế cần định cấu hình.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 116 trở lên

    Lờ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 phát đế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.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (device: Device) => void

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 để biết những sự kiện nào được phân phối.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (device: Device) => void