From 85f6edb81575fb4d2cfefad63e53511bb0632b95 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Fri, 25 Apr 2014 17:35:36 +0800 Subject: [PATCH] :memo: Update docs of ipc module. --- docs/api/browser/ipc-browser.md | 83 ++++++++++++++----------------- docs/api/renderer/ipc-renderer.md | 75 ++++------------------------ 2 files changed, 47 insertions(+), 111 deletions(-) diff --git a/docs/api/browser/ipc-browser.md b/docs/api/browser/ipc-browser.md index 2edaa29463ae..534a7a2a075c 100644 --- a/docs/api/browser/ipc-browser.md +++ b/docs/api/browser/ipc-browser.md @@ -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. diff --git a/docs/api/renderer/ipc-renderer.md b/docs/api/renderer/ipc-renderer.md index 4076b93b395e..5c101269d45e 100644 --- a/docs/api/renderer/ipc-renderer.md +++ b/docs/api/renderer/ipc-renderer.md @@ -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.