58a6fe13d6
* feat: add support for node / preloads in subframes This feature has delibrately been built / implemented in such a way that it has minimum impact on existing apps / code-paths. Without enabling the new "nodeSupportInSubFrames" option basically none of this new code will be hit. The things that I believe need extra scrutiny are: * Introduction of `event.reply` for IPC events and usage of `event.reply` instead of `event.sender.send()` * Usage of `node::FreeEnvironment(env)` when the new option is enabled in order to avoid memory leaks. I have tested this quite a bit and haven't managed to cause a crash but it is still feature flagged behind the "nodeSupportInSubFrames" flag to avoid potential impact. Closes #10569 Closes #10401 Closes #11868 Closes #12505 Closes #14035 * feat: add support preloads in subframes for sandboxed renderers * spec: add tests for new nodeSupportInSubFrames option * spec: fix specs for .reply and ._replyInternal for internal messages * chore: revert change to use flag instead of environment set size * chore: clean up subframe impl * chore: apply suggestions from code review Co-Authored-By: MarshallOfSound <samuel.r.attard@gmail.com> * chore: clean up reply usage * chore: fix TS docs generation * chore: cleanup after rebase * chore: rename wrap to add in event fns
112 lines
3.3 KiB
Markdown
112 lines
3.3 KiB
Markdown
# ipcMain
|
|
|
|
> Communicate asynchronously from the main process to renderer processes.
|
|
|
|
Process: [Main](../glossary.md#main-process)
|
|
|
|
The `ipcMain` module is an instance of the
|
|
[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) class. When used in the main
|
|
process, it handles asynchronous and synchronous messages sent from a renderer
|
|
process (web page). Messages sent from a renderer will be emitted to this
|
|
module.
|
|
|
|
## Sending Messages
|
|
|
|
It is also possible to send messages from the main process to the renderer
|
|
process, see [webContents.send][web-contents-send] for more information.
|
|
|
|
* When sending a message, the event name is the `channel`.
|
|
* To reply to a synchronous message, you need to set `event.returnValue`.
|
|
* To send an asynchronous message back to the sender, you can use
|
|
`event.reply(...)`. This helper method will automatically handle messages
|
|
coming from frames that aren't the main frame (e.g. iframes) whereas
|
|
`event.sender.send(...)` will always send to the main frame.
|
|
|
|
An example of sending and handling messages between the render and main
|
|
processes:
|
|
|
|
```javascript
|
|
// In main process.
|
|
const { ipcMain } = require('electron')
|
|
ipcMain.on('asynchronous-message', (event, arg) => {
|
|
console.log(arg) // prints "ping"
|
|
event.reply('asynchronous-reply', 'pong')
|
|
})
|
|
|
|
ipcMain.on('synchronous-message', (event, arg) => {
|
|
console.log(arg) // prints "ping"
|
|
event.returnValue = 'pong'
|
|
})
|
|
```
|
|
|
|
```javascript
|
|
// In renderer process (web page).
|
|
const { ipcRenderer } = require('electron')
|
|
console.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints "pong"
|
|
|
|
ipcRenderer.on('asynchronous-reply', (event, arg) => {
|
|
console.log(arg) // prints "pong"
|
|
})
|
|
ipcRenderer.send('asynchronous-message', 'ping')
|
|
```
|
|
|
|
## Methods
|
|
|
|
The `ipcMain` module has the following method to listen for events:
|
|
|
|
### `ipcMain.on(channel, listener)`
|
|
|
|
* `channel` String
|
|
* `listener` Function
|
|
|
|
Listens to `channel`, when a new message arrives `listener` would be called with
|
|
`listener(event, args...)`.
|
|
|
|
### `ipcMain.once(channel, listener)`
|
|
|
|
* `channel` String
|
|
* `listener` Function
|
|
|
|
Adds a one time `listener` function for the event. This `listener` is invoked
|
|
only the next time a message is sent to `channel`, after which it is removed.
|
|
|
|
### `ipcMain.removeListener(channel, listener)`
|
|
|
|
* `channel` String
|
|
* `listener` Function
|
|
|
|
Removes the specified `listener` from the listener array for the specified
|
|
`channel`.
|
|
|
|
### `ipcMain.removeAllListeners([channel])`
|
|
|
|
* `channel` String
|
|
|
|
Removes listeners of the specified `channel`.
|
|
|
|
## Event object
|
|
|
|
The `event` object passed to the `callback` has the following methods:
|
|
|
|
### `event.frameId`
|
|
|
|
An `Integer` representing the ID of the renderer frame that sent this message.
|
|
|
|
### `event.returnValue`
|
|
|
|
Set this to the value to be returned in a synchronous message.
|
|
|
|
### `event.sender`
|
|
|
|
Returns the `webContents` that sent the message, you can call
|
|
`event.sender.send` to reply to the asynchronous message, see
|
|
[webContents.send][web-contents-send] for more information.
|
|
|
|
[web-contents-send]: web-contents.md#contentssendchannel-arg1-arg2-
|
|
|
|
### `event.reply`
|
|
|
|
A function that will send an IPC message to the renderer frane that sent
|
|
the original message that you are currently handling. You should use this
|
|
method to "reply" to the sent message in order to guaruntee the reply will go
|
|
to the correct process and frame.
|