OLD | NEW |
---|---|
1 <h1>Message Passing</h1> | 1 <h1>Message Passing</h1> |
2 | 2 |
3 | 3 |
4 <p> | 4 <p> |
5 Since content scripts run in the context of a web page and not the extension, | 5 Since content scripts run in the context of a web page and not the extension, |
6 they often need some way of communicating with the rest of the extension. For | 6 they often need some way of communicating with the rest of the extension. For |
7 example, an RSS reader extension might use content scripts to detect the | 7 example, an RSS reader extension might use content scripts to detect the |
8 presence of an RSS feed on a page, then notify the background page in order to | 8 presence of an RSS feed on a page, then notify the background page in order to |
9 display a page action icon for that page. | 9 display a page action icon for that page. |
10 | 10 |
(...skipping 57 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
68 chrome.runtime.onMessage.addListener( | 68 chrome.runtime.onMessage.addListener( |
69 function(request, sender, sendResponse) { | 69 function(request, sender, sendResponse) { |
70 console.log(sender.tab ? | 70 console.log(sender.tab ? |
71 "from a content script:" + sender.tab.url : | 71 "from a content script:" + sender.tab.url : |
72 "from the extension"); | 72 "from the extension"); |
73 if (request.greeting == "hello") | 73 if (request.greeting == "hello") |
74 sendResponse({farewell: "goodbye"}); | 74 sendResponse({farewell: "goodbye"}); |
75 }); | 75 }); |
76 </pre> | 76 </pre> |
77 | 77 |
78 In the above example, <code>sendResponse</code> was called synchronously. | |
79 If you want to asynchronously use <code>sendResponse</code>, add | |
80 <code>return true;</code> to the <code>onMessage</code> event handler. | |
81 | |
78 <p class="note"> | 82 <p class="note"> |
79 <b>Note:</b> If multiple pages are listening for onMessage events, only the | 83 <b>Note:</b> If multiple pages are listening for onMessage events, only the |
80 first to call sendResponse() for a particular event will succeed in sending the | 84 first to call sendResponse() for a particular event will succeed in sending the |
81 response. All other responses to that event will be ignored. | 85 response. All other responses to that event will be ignored. |
82 </p> | 86 |
87 <p class="note"> | |
88 <b>Note:</b> If none of the handlers call <code>sendResponse</code>, then the | |
89 response callback is automatically invoked, unless one of the handlers returns | |
90 true. Even if a message handler returned true, the callback may still be called | |
91 automatically if the <code>sendResponse</code> callback is garbage-collected. | |
83 | 92 |
84 | 93 |
85 <h2 id="connect">Long-lived connections</h2> | 94 <h2 id="connect">Long-lived connections</h2> |
86 <p> | 95 <p> |
87 Sometimes it's useful to have a conversation that lasts longer than a single | 96 Sometimes it's useful to have a conversation that lasts longer than a single |
88 request and response. In this case, you can open a long-lived channel from | 97 request and response. In this case, you can open a long-lived channel from |
89 your content script to an extension page | 98 your content script to an extension page |
90 {{^is_apps}} | 99 {{^is_apps}} |
91 , or vice versa, | 100 , or vice versa, |
92 {{/is_apps}} | 101 {{/is_apps}} |
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
147 if (msg.joke == "Knock knock") | 156 if (msg.joke == "Knock knock") |
148 port.postMessage({question: "Who's there?"}); | 157 port.postMessage({question: "Who's there?"}); |
149 else if (msg.answer == "Madame") | 158 else if (msg.answer == "Madame") |
150 port.postMessage({question: "Madame who?"}); | 159 port.postMessage({question: "Madame who?"}); |
151 else if (msg.answer == "Madame... Bovary") | 160 else if (msg.answer == "Madame... Bovary") |
152 port.postMessage({question: "I don't get it."}); | 161 port.postMessage({question: "I don't get it."}); |
153 }); | 162 }); |
154 }); | 163 }); |
155 </pre> | 164 </pre> |
156 | 165 |
166 <h3 id="port-lifetime">Port lifetime</h3> | |
167 <p> | |
168 Ports are designed as a two-way communication method between different parts of | |
169 the extension (where a (top-level) frame is viewed as the smallest part). | |
Devlin
2016/04/13 21:41:40
nit: remove double-nested parens
robwu
2016/04/13 22:44:35
Done.
| |
170 <br> | |
171 Upon calling $(ref:tabs.connect), $(ref:runtime.connect) or | |
172 $(ref:runtime.connectNative), a $(ref:runtime.Port Port) is created. | |
173 This port is immediately usable can be used for sending messages to | |
Devlin
2016/04/13 21:41:40
nit: usable *and* can
robwu
2016/04/13 22:44:34
Done. s/is immediately usable can be used/can imme
| |
174 the other end via $(ref:runtime.Port.postMessage postMessage). | |
175 | |
176 <p> | |
177 If there are multiple frames in a tab, calling $(ref:tabs.connect) results in | |
178 multiple invocations of the $(ref:runtime.onConnect) event | |
179 (once for each frame in the tab). | |
Devlin
2016/04/13 21:41:40
"each *connected* frame", maybe? (Ditto for below
robwu
2016/04/13 22:44:34
This is about onConnect, not onMessage, so "each f
| |
180 Similarly, if $(ref:runtime.connect) is used, then the onConnect event | |
181 may be fired multiple times (once for every frame in the extension process). | |
182 | |
157 <p> | 183 <p> |
158 You may want to find out when a connection is closed, for example if you are | 184 You may want to find out when a connection is closed, for example if you are |
159 maintaining separate state for each open port. For this you can listen to the | 185 maintaining separate state for each open port. For this you can listen to the |
160 $(ref:runtime.Port.onDisconnect) | 186 $(ref:runtime.Port.onDisconnect) |
161 event. This event is fired either when the other side of the channel manually | 187 event. This event is fired either when there are no valid ports at the other |
Devlin
2016/04/13 21:41:40
remove "either"
robwu
2016/04/13 22:44:34
Done.
| |
162 calls | 188 side of the channel. This happens in the following situations: |
163 $(ref:runtime.Port.disconnect), or when the page | 189 <ul> |
164 containing the port is unloaded (for example if the tab is navigated). | 190 <li> |
165 onDisconnect is guaranteed to be fired only once for any given port. | 191 There are no listeners for $(ref:runtime.onConnect) at the other end. |
192 <li> | |
193 The tab containing the port is unloaded (e.g. if the tab is navigated). | |
194 <li> | |
195 The frame from where <code>connect</code> was called has unloaded. | |
196 <li> | |
197 All frames that received the port (via $(ref:runtime.onConnect)) have | |
198 unloaded. | |
199 <li> | |
200 $(ref:runtime.Port.disconnect) is called by <em>the other end</em>. | |
201 Note that if a <code>connect</code> call results in multiple ports at the | |
202 receiver's end, and <code>disconnect()</code> is called on any of these | |
203 ports, then the <code>onDisconnect</code> event is only fired at the port | |
204 of the sender, and not at the other ports. | |
205 </ul> | |
166 | 206 |
167 | 207 |
168 <h2 id="external">Cross-extension messaging</h2> | 208 <h2 id="external">Cross-extension messaging</h2> |
169 <p> | 209 <p> |
170 In addition to sending messages between different components in your | 210 In addition to sending messages between different components in your |
171 extension, you can use the messaging API to communicate with other extensions. | 211 extension, you can use the messaging API to communicate with other extensions. |
172 This lets you expose a public API that other extensions can take advantage of. | 212 This lets you expose a public API that other extensions can take advantage of. |
173 | 213 |
174 <p> | 214 <p> |
175 Listening for incoming requests and connections is similar to the internal | 215 Listening for incoming requests and connections is similar to the internal |
(...skipping 156 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
332 | 372 |
333 <p> | 373 <p> |
334 You can find simple examples of communication via messages in the | 374 You can find simple examples of communication via messages in the |
335 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/api/messaging/">examples/api/messaging</a> | 375 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/api/messaging/">examples/api/messaging</a> |
336 directory. | 376 directory. |
337 The <a href="nativeMessaging#examples">native messaging sample</a> demonstrates | 377 The <a href="nativeMessaging#examples">native messaging sample</a> demonstrates |
338 how a Chrome app can communicate with a native app. | 378 how a Chrome app can communicate with a native app. |
339 For more examples and for help in viewing the source code, see | 379 For more examples and for help in viewing the source code, see |
340 <a href="samples">Samples</a>. | 380 <a href="samples">Samples</a>. |
341 </p> | 381 </p> |
OLD | NEW |