feat: add support for WebUSB (#36289)
* feat: add support for WebUSB
* fixup for gn check
* fixup gn check on Windows
* Apply review feedback
Co-authored-by: Charles Kerr <charles@charleskerr.com>
* chore: address review feedback
* chore: removed unneeded code
* Migrate non-default ScopedObservation<> instantiations to ScopedObservationTraits<> in chrome/browser/
4016595
Co-authored-by: Charles Kerr <charles@charleskerr.com>
This commit is contained in:
John Kleinschmidt
GitHub
parent
2751c2b07f
commit
629c54ba36
29 changed files with 1772 additions and 23 deletions
|
|
@ -239,7 +239,7 @@ app.whenReady().then(() => {
|
|||
const selectedDevice = details.deviceList.find((device) => {
|
||||
return device.vendorId === '9025' && device.productId === '67'
|
||||
})
|
||||
callback(selectedPort?.deviceId)
|
||||
callback(selectedDevice?.deviceId)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
|
@ -429,6 +429,118 @@ const portConnect = async () => {
|
|||
}
|
||||
```
|
||||
|
||||
#### Event: 'select-usb-device'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `details` Object
|
||||
* `deviceList` [USBDevice[]](structures/usb-device.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
* `callback` Function
|
||||
* `deviceId` string (optional)
|
||||
|
||||
Emitted when a USB device needs to be selected when a call to
|
||||
`navigator.usb.requestDevice` is made. `callback` should be called with
|
||||
`deviceId` to be selected; passing no arguments to `callback` will
|
||||
cancel the request. Additionally, permissioning on `navigator.usb` can
|
||||
be further managed by using [ses.setPermissionCheckHandler(handler)](#sessetpermissioncheckhandlerhandler)
|
||||
and [ses.setDevicePermissionHandler(handler)`](#sessetdevicepermissionhandlerhandler).
|
||||
|
||||
```javascript
|
||||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
let win = null
|
||||
|
||||
app.whenReady().then(() => {
|
||||
win = new BrowserWindow()
|
||||
|
||||
win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
|
||||
if (permission === 'usb') {
|
||||
// Add logic here to determine if permission should be given to allow USB selection
|
||||
return true
|
||||
}
|
||||
return false
|
||||
})
|
||||
|
||||
// Optionally, retrieve previously persisted devices from a persistent store (fetchGrantedDevices needs to be implemented by developer to fetch persisted permissions)
|
||||
const grantedDevices = fetchGrantedDevices()
|
||||
|
||||
win.webContents.session.setDevicePermissionHandler((details) => {
|
||||
if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'usb') {
|
||||
if (details.device.vendorId === 123 && details.device.productId === 345) {
|
||||
// Always allow this type of device (this allows skipping the call to `navigator.usb.requestDevice` first)
|
||||
return true
|
||||
}
|
||||
|
||||
// Search through the list of devices that have previously been granted permission
|
||||
return grantedDevices.some((grantedDevice) => {
|
||||
return grantedDevice.vendorId === details.device.vendorId &&
|
||||
grantedDevice.productId === details.device.productId &&
|
||||
grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
|
||||
})
|
||||
}
|
||||
return false
|
||||
})
|
||||
|
||||
win.webContents.session.on('select-usb-device', (event, details, callback) => {
|
||||
event.preventDefault()
|
||||
const selectedDevice = details.deviceList.find((device) => {
|
||||
return device.vendorId === '9025' && device.productId === '67'
|
||||
})
|
||||
if (selectedDevice) {
|
||||
// Optionally, add this to the persisted devices (updateGrantedDevices needs to be implemented by developer to persist permissions)
|
||||
grantedDevices.push(selectedDevice)
|
||||
updateGrantedDevices(grantedDevices)
|
||||
}
|
||||
callback(selectedDevice?.deviceId)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
#### Event: 'usb-device-added'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `details` Object
|
||||
* `device` [USBDevice](structures/usb-device.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
|
||||
Emitted after `navigator.usb.requestDevice` has been called and
|
||||
`select-usb-device` has fired if a new device becomes available before
|
||||
the callback from `select-usb-device` is called. This event is intended for
|
||||
use when using a UI to ask users to pick a device so that the UI can be updated
|
||||
with the newly added device.
|
||||
|
||||
#### Event: 'usb-device-removed'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `details` Object
|
||||
* `device` [USBDevice](structures/usb-device.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
|
||||
Emitted after `navigator.usb.requestDevice` has been called and
|
||||
`select-usb-device` has fired if a device has been removed before the callback
|
||||
from `select-usb-device` is called. This event is intended for use when using
|
||||
a UI to ask users to pick a device so that the UI can be updated to remove the
|
||||
specified device.
|
||||
|
||||
#### Event: 'usb-device-revoked'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `details` Object
|
||||
* `device` [USBDevice[]](structures/usb-device.md)
|
||||
* `origin` string (optional) - The origin that the device has been revoked from.
|
||||
|
||||
Emitted after `USBDevice.forget()` has been called. This event can be used
|
||||
to help maintain persistent storage of permissions when
|
||||
`setDevicePermissionHandler` is used.
|
||||
|
||||
### Instance Methods
|
||||
|
||||
The following methods are available on instances of `Session`:
|
||||
|
|
@ -714,7 +826,7 @@ session.fromPartition('some-partition').setPermissionRequestHandler((webContents
|
|||
|
||||
* `handler` Function\<boolean> | null
|
||||
* `webContents` ([WebContents](web-contents.md) | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use `requestingUrl` to check the request origin. All cross origin sub frames making permission checks will pass a `null` webContents to this handler, while certain other permission checks such as `notifications` checks will always pass `null`. You should use `embeddingOrigin` and `requestingOrigin` to determine what origin the owning frame and the requesting frame are on respectively.
|
||||
* `permission` string - Type of permission check. Valid values are `midiSysex`, `notifications`, `geolocation`, `media`,`mediaKeySystem`,`midi`, `pointerLock`, `fullscreen`, `openExternal`, `hid`, or `serial`.
|
||||
* `permission` string - Type of permission check. Valid values are `midiSysex`, `notifications`, `geolocation`, `media`,`mediaKeySystem`,`midi`, `pointerLock`, `fullscreen`, `openExternal`, `hid`, `serial`, or `usb`.
|
||||
* `requestingOrigin` string - The origin URL of the permission check
|
||||
* `details` Object - Some properties are only available on certain permission types.
|
||||
* `embeddingOrigin` string (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.
|
||||
|
|
@ -800,7 +912,7 @@ Passing `null` instead of a function resets the handler to its default state.
|
|||
|
||||
* `handler` Function\<boolean> | null
|
||||
* `details` Object
|
||||
* `deviceType` string - The type of device that permission is being requested on, can be `hid` or `serial`.
|
||||
* `deviceType` string - The type of device that permission is being requested on, can be `hid`, `serial`, or `usb`.
|
||||
* `origin` string - The origin URL of the device permission check.
|
||||
* `device` [HIDDevice](structures/hid-device.md) | [SerialPort](structures/serial-port.md)- the device that permission is being requested for.
|
||||
|
||||
|
|
@ -828,6 +940,8 @@ app.whenReady().then(() => {
|
|||
return true
|
||||
} else if (permission === 'serial') {
|
||||
// Add logic here to determine if permission should be given to allow serial port selection
|
||||
} else if (permission === 'usb') {
|
||||
// Add logic here to determine if permission should be given to allow USB device selection
|
||||
}
|
||||
return false
|
||||
})
|
||||
|
|
|
|||
17
docs/api/structures/usb-device.md
Normal file
17
docs/api/structures/usb-device.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
# USBDevice Object
|
||||
|
||||
* `deviceId` string - Unique identifier for the device.
|
||||
* `vendorId` Integer - The USB vendor ID.
|
||||
* `productId` Integer - The USB product ID.
|
||||
* `productName` string (optional) - Name of the device.
|
||||
* `serialNumber` string (optional) - The USB device serial number.
|
||||
* `manufacturerName` string (optional) - The manufacturer name of the device.
|
||||
* `usbVersionMajor` Integer - The USB protocol major version supported by the device
|
||||
* `usbVersionMinor` Integer - The USB protocol minor version supported by the device
|
||||
* `usbVersionSubminor` Integer - The USB protocol subminor version supported by the device
|
||||
* `deviceClass` Integer - The device class for the communication interface supported by the device
|
||||
* `deviceSubclass` Integer - The device subclass for the communication interface supported by the device
|
||||
* `deviceProtocol` Integer - The device protocol for the communication interface supported by the device
|
||||
* `deviceVersionMajor` Integer - The major version number of the device as defined by the device manufacturer.
|
||||
* `deviceVersionMinor` Integer - The minor version number of the device as defined by the device manufacturer.
|
||||
* `deviceVersionSubminor` Integer - The subminor version number of the device as defined by the device manufacturer.
|
||||
Loading…
Add table
Add a link
Reference in a new issue