feat: add serial api support (#25237)

* feat: add serial api support

resolves #22478

* Put serial port support behind a flag and mark as experimental

* Update docs/api/session.md

Co-authored-by: Jeremy Rose <jeremya@chromium.org>

* Use enable-blink-features=Serial instead of enable-experimental-web-platform-features

* Set enableBlinkFeatures on webPreferences instead of commandline

Co-authored-by: Jeremy Rose <jeremya@chromium.org>
This commit is contained in:
John Kleinschmidt 2020-09-28 12:22:03 -04:00 committed by GitHub
parent bed50bb73c
commit fd63510ca9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 936 additions and 1 deletions

View file

@ -178,6 +178,76 @@ Emitted when a hunspell dictionary file download fails. For details
on the failure you should collect a netlog and inspect the download
request.
#### Event: 'select-serial-port' _Experimental_
Returns:
* `event` Event
* `portList` [SerialPort[]](structures/serial-port.md)
* `webContents` [WebContents](web-contents.md)
* `callback` Function
* `portId` String
Emitted when a serial port needs to be selected when a call to
`navigator.serial.requestPort` is made. `callback` should be called with
`portId` to be selected, passing an empty string to `callback` will
cancel the request. Additionally, permissioning on `navigator.serial` can
be managed by using [ses.setPermissionCheckHandler(handler)](#sessetpermissioncheckhandlerhandler)
with the `serial` permission.
Because this is an experimental feature it is disabled by default. To enable this feature, you
will need to use the `--enable-features=ElectronSerialChooser` command line switch. Additionally
because this is an experimental Chromium feature you will need to set `enableBlinkFeatures: 'Serial'`
on the `webPreferences` property when opening a BrowserWindow.
```javascript
const { app, BrowserWindow } = require('electron')
let win = null
app.commandLine.appendSwitch('enable-features', 'ElectronSerialChooser')
app.whenReady().then(() => {
win = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
enableBlinkFeatures: 'Serial'
}
})
win.webContents.session.on('select-serial-port', (event, portList, callback) => {
event.preventDefault()
const selectedPort = portList.find((device) => {
return device.vendorId === 0x2341 && device.productId === 0x0043
})
if (!selectedPort) {
callback('')
} else {
callback(result1.portId)
}
})
})
```
#### Event: 'serial-port-added' _Experimental_
Returns:
* `event` Event
* `port` [SerialPort](structures/serial-port.md)
* `webContents` [WebContents](web-contents.md)
Emitted after `navigator.serial.requestPort` has been called and `select-serial-port` has fired if a new serial port becomes available. For example, this event will fire when a new USB device is plugged in.
#### Event: 'serial-port-removed' _Experimental_
Returns:
* `event` Event
* `port` [SerialPort](structures/serial-port.md)
* `webContents` [WebContents](web-contents.md)
Emitted after `navigator.serial.requestPort` has been called and `select-serial-port` has fired if a serial port has been removed. For example, this event will fire when a USB device is unplugged.
### Instance Methods
The following methods are available on instances of `Session`:
@ -420,7 +490,7 @@ session.fromPartition('some-partition').setPermissionRequestHandler((webContents
* `handler` Function<Boolean> | null
* `webContents` [WebContents](web-contents.md) - WebContents checking the permission. Please note that if the request comes from a subframe you should use `requestingUrl` to check the request origin.
* `permission` String - Enum of 'media'.
* `permission` String - Type of permission check. Valid values are `midiSysex`, `notifications`, `geolocation`, `media`,`mediaKeySystem`,`midi`, `pointerLock`, `fullscreen`, `openExternal`, or `serial`.
* `requestingOrigin` String - The origin URL of the permission check
* `details` Object - Some properties are only available on certain permission types.
* `securityOrigin` String - The security origin of the `media` check.

View file

@ -0,0 +1,8 @@
# SerialPort Object
* `portId` String - Unique identifier for the port
* `portName` String - Name of the port
* `displayName` String - Addtional information for the port
* `persistentId` String - This platform-specific identifier, if present, can be used to identify the device across restarts of the application and operating system.
* `vendorId` String - Optional USB vendor ID
* `productId` String - Optional USB product ID