📝 Update docs of ipc module.
This commit is contained in:
Cheng Zhao
parent
1fd8deaca7
commit
85f6edb815
2 changed files with 47 additions and 111 deletions
|
|
@ -1,52 +1,45 @@
|
|||
# ipc (browser)
|
||||
|
||||
The `ipc` module allows developers to send asynchronous messages to renderers.
|
||||
To avoid possible dead-locks, it's not allowed to send synchronous messages in
|
||||
browser.
|
||||
Handles asynchronous and synchronous message sent from web page.
|
||||
|
||||
## Event: 'message'
|
||||
The messages sent from web page would be emitted to this module, the event name
|
||||
is the `channel` when sending message. To reply a synchronous message, you need
|
||||
to set `event.returnValue`, to send an asynchronous back to the sender, you can
|
||||
use `event.sender.send(...)`.
|
||||
|
||||
* `processId` Integer
|
||||
* `routingId` Integer
|
||||
|
||||
Emitted when renderer sent a message to the browser.
|
||||
|
||||
## Event: 'sync-message'
|
||||
|
||||
* `event` Object
|
||||
* `processId` Integer
|
||||
* `routingId` Integer
|
||||
|
||||
Emitted when renderer sent a synchronous message to the browser. The receiver
|
||||
should store the result in `event.returnValue`.
|
||||
|
||||
**Note:** Due to the limitation of `EventEmitter`, returning value in the
|
||||
event handler has no effect, so we have to store the result by using the
|
||||
`event` parameter.
|
||||
|
||||
## ipc.send(processId, routingId, [args...])
|
||||
|
||||
* `processId` Integer
|
||||
* `routingId` Integer
|
||||
|
||||
Send `args...` to the renderer specified by `processId` and `routingId` and
|
||||
return immediately, the renderer should handle the message by listening to the
|
||||
`message` event.
|
||||
|
||||
## ipc.sendChannel(processId, routingId, channel, [args...])
|
||||
|
||||
* `processId` Integer
|
||||
* `routingId` Integer
|
||||
* `channel` String
|
||||
|
||||
This is the same with ipc.send, except that the renderer should listen to the
|
||||
`channel` event. The ipc.send(processId, routingId, args...) can be seen as
|
||||
ipc.sendChannel(processId, routingId, 'message', args...).
|
||||
|
||||
**Note:** If the the first argument (e.g. `processId`) is a `BrowserWindow`,
|
||||
`ipc.sendChannel` would automatically get the `processId` and `routingId`
|
||||
from it, so you can send a message to window like this:
|
||||
An example of sending and handling messages:
|
||||
|
||||
```javascript
|
||||
ipc.sendChannel(browserWindow, 'message', ...);
|
||||
// In browser.
|
||||
var ipc = require('ipc');
|
||||
ipc.on('asynchronous-message', function(event, arg) {
|
||||
console.log(arg); // prints "ping"
|
||||
event.sender.send('asynchronous-reply', 'pong');
|
||||
});
|
||||
|
||||
ipc.on('synchronous-message', function(event, arg) {
|
||||
console.log(arg); // prints "ping"
|
||||
event.returnValue = 'pong'.
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// In web page.
|
||||
var ipc = require('ipc');
|
||||
console.log(ipc.sendSync('synchronous-message', 'ping')); // prints "pong"
|
||||
|
||||
ipc.on('asynchronous-reply', function(arg) {
|
||||
console.log(arg); // prints "pong"
|
||||
});
|
||||
ipc.send('asynchronous-message', 'ping');
|
||||
```
|
||||
|
||||
### Class: Event
|
||||
|
||||
## Event.returnValue
|
||||
|
||||
Assign to this to return an value to synchronous messages.
|
||||
|
||||
## Event.sender
|
||||
|
||||
The `WebContents` of the web page that has sent the message.
|
||||
|
|
|
|||
|
|
@ -5,75 +5,18 @@ asynchronous messages to the browser, and also receive messages sent from
|
|||
browser. If you want to make use of modules of browser from renderer, you
|
||||
might consider using the [remote](remote.md) module.
|
||||
|
||||
An example of echoing messages between browser and renderer:
|
||||
See [ipc (browser)](../browser/ipc-browser.md) for examples.
|
||||
|
||||
```javascript
|
||||
// In browser:
|
||||
var ipc = require('ipc');
|
||||
ipc.on('message', function(processId, routingId, m) {
|
||||
ipc.send(processId, routingId, m);
|
||||
});
|
||||
```
|
||||
## ipc.send(channel[, args...])
|
||||
|
||||
```javascript
|
||||
// In renderer:
|
||||
var ipc = require('ipc');
|
||||
ipc.on('message', function(m) {
|
||||
console.log('Received message', m);
|
||||
});
|
||||
ipc.send('Hello world');
|
||||
```
|
||||
Send `args..` to the web page via `channel` in asynchronous message, the browser
|
||||
process can handle it by listening to the `channel` event of `ipc` module.
|
||||
|
||||
An example of sending synchronous message from renderer to browser:
|
||||
## ipc.sendSync(channel[, args...])
|
||||
|
||||
```javascript
|
||||
// In browser:
|
||||
var ipc = require('ipc');
|
||||
ipc.on('browser-data-request', function(event, processId, routingId, message) {
|
||||
event.returnValue = 'THIS SOME DATA FROM THE BROWSER';
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// In renderer:
|
||||
var ipc = require('ipc');
|
||||
console.log(ipc.sendChannelSync('browser-data-request', 'THIS IS FROM THE RENDERER'));
|
||||
```
|
||||
|
||||
## Event: 'message'
|
||||
|
||||
Emitted when browser sent a message to this window.
|
||||
|
||||
## ipc.send([args...])
|
||||
|
||||
Send all arguments to the browser and return immediately, the browser should
|
||||
handle the message by listening to the `message` event.
|
||||
|
||||
## ipc.sendSync([args...])
|
||||
|
||||
Send all arguments to the browser synchronously, and returns the result sent
|
||||
from browser. The browser should handle the message by listening to the
|
||||
`sync-message` event.
|
||||
Send `args..` to the web page via `channel` in synchronous message, and returns
|
||||
the result sent from browser. The browser process can handle it by listening to
|
||||
the `channel` event of `ipc` module, and returns by setting `event.returnValue`.
|
||||
|
||||
**Note:** Usually developers should never use this API, since sending
|
||||
synchronous message would block the browser.
|
||||
|
||||
## ipc.sendChannel(channel, [args...])
|
||||
|
||||
* `channel` String
|
||||
|
||||
This is the same with `ipc.send`, except that the browser should listen to the
|
||||
`channel` event. The `ipc.send(args...)` can be seen as
|
||||
`ipc.sendChannel('message', args...)`.
|
||||
|
||||
|
||||
## ipc.sendChannelSync(channel, [args...])
|
||||
|
||||
* `channel` String
|
||||
|
||||
This is the same with `ipc.sendSync`, except that the browser should listen to
|
||||
the `channel` event. The `ipc.sendSync(args...)` can be seen as
|
||||
`ipc.sendChannelSync('sync-message', args...)`.
|
||||
|
||||
**Note:** Usually developers should never use this API, since sending
|
||||
synchronous message would block the browser.
|
||||
synchronous message would block the whole web page.
|
||||
|
|
|
|||
Loading…
Reference in a new issue