feat: MessagePorts in the main process (#22404)

This commit is contained in:
Jeremy Apthorp 2020-03-11 18:07:54 -07:00 committed by GitHub
parent c4c0888972
commit b4d07f76d3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
34 changed files with 1316 additions and 113 deletions

View file

@ -57,7 +57,7 @@ Removes all listeners, or those of the specified `channel`.
Send an asynchronous message to the main process via `channel`, along with
arguments. Arguments will be serialized with the [Structured Clone
Algorithm][SCA], just like [`postMessage`][], so prototype chains will not be
Algorithm][SCA], just like [`window.postMessage`][], so prototype chains will not be
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
throw an exception.
@ -68,6 +68,10 @@ throw an exception.
The main process handles it by listening for `channel` with the
[`ipcMain`](ipc-main.md) module.
If you need to transfer a [`MessagePort`][] to the main process, use [`ipcRenderer.postMessage`](#ipcrendererpostmessagechannel-message-transfer).
If you want to receive a single response from the main process, like the result of a method call, consider using [`ipcRenderer.invoke`](#ipcrendererinvokechannel-args).
### `ipcRenderer.invoke(channel, ...args)`
* `channel` String
@ -77,7 +81,7 @@ Returns `Promise<any>` - Resolves with the response from the main process.
Send a message to the main process via `channel` and expect a result
asynchronously. Arguments will be serialized with the [Structured Clone
Algorithm][SCA], just like [`postMessage`][], so prototype chains will not be
Algorithm][SCA], just like [`window.postMessage`][], so prototype chains will not be
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
throw an exception.
@ -102,6 +106,10 @@ ipcMain.handle('some-name', async (event, someArgument) => {
})
```
If you need to transfer a [`MessagePort`][] to the main process, use [`ipcRenderer.postMessage`](#ipcrendererpostmessagechannel-message-transfer).
If you do not need a respons to the message, consider using [`ipcRenderer.send`](#ipcrenderersendchannel-args).
### `ipcRenderer.sendSync(channel, ...args)`
* `channel` String
@ -111,7 +119,7 @@ Returns `any` - The value sent back by the [`ipcMain`](ipc-main.md) handler.
Send a message to the main process via `channel` and expect a result
synchronously. Arguments will be serialized with the [Structured Clone
Algorithm][SCA], just like [`postMessage`][], so prototype chains will not be
Algorithm][SCA], just like [`window.postMessage`][], so prototype chains will not be
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
throw an exception.
@ -127,6 +135,35 @@ and replies by setting `event.returnValue`.
> last resort. It's much better to use the asynchronous version,
> [`invoke()`](ipc-renderer.md#ipcrendererinvokechannel-args).
### `ipcRenderer.postMessage(channel, message, [transfer])`
* `channel` String
* `message` any
* `transfer` MessagePort[] (optional)
Send a message to the main process, optionally transferring ownership of zero
or more [`MessagePort`][] objects.
The transferred `MessagePort` objects will be available in the main process as
[`MessagePortMain`](message-port-main.md) objects by accessing the `ports`
property of the emitted event.
For example:
```js
// Renderer process
const { port1, port2 } = new MessageChannel()
ipcRenderer.postMessage('port', { message: 'hello' }, [port1])
// Main process
ipcMain.on('port', (e, msg) => {
const [port] = e.ports
// ...
})
```
For more information on using `MessagePort` and `MessageChannel`, see the [MDN
documentation](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel).
### `ipcRenderer.sendTo(webContentsId, channel, ...args)`
* `webContentsId` Number
@ -150,4 +187,5 @@ in the [`ipc-renderer-event`](structures/ipc-renderer-event.md) structure docs.
[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
[`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
[`window.postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
[`MessagePort`]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort

View file

@ -0,0 +1,30 @@
# MessageChannelMain
`MessageChannelMain` is the main-process-side equivalent of the DOM
[`MessageChannel`][] object. Its singular function is to create a pair of
connected [`MessagePortMain`](message-port-main.md) objects.
See the [Channel Messaging API][] documentation for more information on using
channel messaging.
## Class: MessageChannelMain
Example:
```js
const { port1, port2 } = new MessageChannelMain()
w.webContents.postMessage('port', null, [port2])
port1.postMessage({ some: 'message' })
```
### Instance Properties
#### `channel.port1`
A [`MessagePortMain`](message-port-main.md) property.
#### `channel.port2`
A [`MessagePortMain`](message-port-main.md) property.
[`MessageChannel`]: https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel
[Channel Messaging API]: https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API

View file

@ -0,0 +1,49 @@
# MessagePortMain
`MessagePortMain` is the main-process-side equivalent of the DOM
[`MessagePort`][] object. It behaves similarly to the DOM version, with the
exception that it uses the Node.js `EventEmitter` event system, instead of the
DOM `EventTarget` system. This means you should use `port.on('message', ...)`
to listen for events, instead of `port.onmessage = ...` or
`port.addEventListener('message', ...)`
See the [Channel Messaging API][] documentation for more information on using
channel messaging.
`MessagePortMain` is an [EventEmitter][event-emitter].
## Class: MessagePortMain
### Instance Methods
#### `port.postMessage(message, [transfer])`
* `message` any
* `transfer` MessagePortMain[] (optional)
Sends a message from the port, and optionally, transfers ownership of objects
to other browsing contexts.
#### `port.start()`
Starts the sending of messages queued on the port. Messages will be queued
until this method is called.
#### `port.close()`
Disconnects the port, so it is no longer active.
### Instance Events
#### Event: 'message'
Returns:
* `messageEvent` Object
* `data` any
* `ports` MessagePortMain[]
Emitted when a MessagePortMain object receives a message.
[`MessagePort`]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
[Channel Messaging API]: https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API

View file

@ -3,6 +3,7 @@
* `frameId` Integer - The ID of the renderer frame that sent this message
* `returnValue` any - Set this to the value to be returned in a synchronous message
* `sender` WebContents - Returns the `webContents` that sent the message
* `ports` MessagePortMain[] - A list of MessagePorts that were transferred with this message
* `reply` Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to "reply" to the sent message in order to guarantee the reply will go to the correct process and frame.
* `channel` String
* `...args` any[]

View file

@ -2,5 +2,6 @@
* `sender` IpcRenderer - The `IpcRenderer` instance that emitted the event originally
* `senderId` Integer - The `webContents.id` that sent the message, you can call `event.sender.sendTo(event.senderId, ...)` to reply to the message, see [ipcRenderer.sendTo][ipc-renderer-sendto] for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set `event.senderId` to `0`.
* `ports` MessagePort[] - A list of MessagePorts that were transferred with this message
[ipc-renderer-sendto]: #ipcrenderersendtowindowid-channel--arg1-arg2-

View file

@ -1593,6 +1593,32 @@ ipcMain.on('ping', (event) => {
})
```
#### `contents.postMessage(channel, message, [transfer])`
* `channel` String
* `message` any
* `transfer` MessagePortMain[] (optional)
Send a message to the renderer process, optionally transferring ownership of
zero or more [`MessagePortMain`][] objects.
The transferred `MessagePortMain` objects will be available in the renderer
process by accessing the `ports` property of the emitted event. When they
arrive in the renderer, they will be native DOM `MessagePort` objects.
For example:
```js
// Main process
const { port1, port2 } = new MessageChannelMain()
webContents.postMessage('port', { message: 'hello' }, [port1])
// Renderer process
ipcRenderer.on('port', (e, msg) => {
const [port] = e.ports
// ...
})
```
#### `contents.enableDeviceEmulation(parameters)`
* `parameters` Object