mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

feat: MessagePorts in the main process (#22404)

Browse source
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
Download patch file Download diff file Expand all files Collapse all files

46
docs/api/ipc-renderer.md
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