chrome.usb

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

    InterfaceDescriptor[]

    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

    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

    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

    RequestType

    Loại yêu cầu.

  • tạm ngừng

    số không bắt buộc

    Chrome 43 trở lên

    Thờ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ên

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

  • productId

    number

    Mã sản phẩm.

  • productName

    string

    Chrome 46 trở lên

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

  • serialNumber

    string

    Chrome 46 trở lên

    Chuỗ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ên

    Phiê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

    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

    TransferType

    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ữa

    Tươ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ữa

    Tươ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

    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ên

    Thờ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

    EndpointDescriptor[]

    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

    GenericTransferInfo

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

Cam kết 
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ố

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

Cam kết 
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ố

  • 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ê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()

Cam kết 
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ố

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

Cam kết 
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ố

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

Cam kết 
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ố

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

Cam kết 
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ố

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

Cam kết Chrome 47 trở lên 
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ố

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

Cam kết 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
)

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

Tham số

  • 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: 

    (devices: Device[])=>void

Giá trị trả về

  • Hứa hẹn<Thiết bị[]>

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

Cam kết 
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ố

  • tùy chọn

    DevicePromptOptions

    Cấu hình của hộp thoại bộ chọn 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: 

    (devices: Device[])=>void

Giá trị trả về

  • Hứa hẹn<Thiết bị[]>

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

Cam kết 
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ố

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

Cam kết 
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ố

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

Cam kết 
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ố

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

Cam kết 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
)

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

Tham 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()

Cam kết 
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ố

  • 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ê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()

Lời hứa Không dùng nữa
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ị

    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ê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()

Cam kết 
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ố

  • 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ê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()

Cam kết 
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ố

  • 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ê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()

Cam kết 
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ố

  • 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ê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 đế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

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.

Tham số

  • số gọi lại

    hàm

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

    (device: Device)=>void