Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(348)

Unified Diff: chrome/common/extensions/docs/templates/articles/messaging.html

Issue 1874133002: Improve documentation of extension messaging (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Created 4 years, 8 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « chrome/common/extensions/api/tabs.json ('k') | extensions/common/api/runtime.json » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: chrome/common/extensions/docs/templates/articles/messaging.html
diff --git a/chrome/common/extensions/docs/templates/articles/messaging.html b/chrome/common/extensions/docs/templates/articles/messaging.html
index 782c3a454d3b0f89964471308b524837f9953b67..b290d3275069930c87b9e8354dfa0d6ad1cb9eba 100644
--- a/chrome/common/extensions/docs/templates/articles/messaging.html
+++ b/chrome/common/extensions/docs/templates/articles/messaging.html
@@ -75,11 +75,21 @@ chrome.runtime.onMessage.addListener(
});
</pre>
+In the above example, <code>sendResponse</code> was called synchronously.
+If you want to asynchronously use <code>sendResponse</code>, add
+<code>return true;</code> to the <code>onMessage</code> event handler.
+
<p class="note">
<b>Note:</b> If multiple pages are listening for onMessage events, only the
first to call sendResponse() for a particular event will succeed in sending the
response. All other responses to that event will be ignored.
-</p>
+
+<p class="note">
+<b>Note:</b> The <code>sendResponse</code> callback is only valid if used
+synchronously, or if the event handler returns <code>true</code> to indicate
+that it will respond asynchronously. The <code>sendMessage</code> function's
+callback will be invoked automatically if no handlers return true or if the
+<code>sendResponse</code> callback is garbage-collected.
<h2 id="connect">Long-lived connections</h2>
@@ -154,15 +164,46 @@ chrome.runtime.onConnect.addListener(function(port) {
});
</pre>
+<h3 id="port-lifetime">Port lifetime</h3>
+<p>
+Ports are designed as a two-way communication method between different parts of
+the extension, where a (top-level) frame is viewed as the smallest part.
+<br>
+Upon calling $(ref:tabs.connect), $(ref:runtime.connect) or
+$(ref:runtime.connectNative), a $(ref:runtime.Port Port) is created.
+This port can immediately be used for sending messages to the other end via
+$(ref:runtime.Port.postMessage postMessage).
+
+<p>
+If there are multiple frames in a tab, calling $(ref:tabs.connect) results in
+multiple invocations of the $(ref:runtime.onConnect) event
+(once for each frame in the tab).
+Similarly, if $(ref:runtime.connect) is used, then the onConnect event
+may be fired multiple times (once for every frame in the extension process).
+
<p>
You may want to find out when a connection is closed, for example if you are
maintaining separate state for each open port. For this you can listen to the
$(ref:runtime.Port.onDisconnect)
-event. This event is fired either when the other side of the channel manually
-calls
-$(ref:runtime.Port.disconnect), or when the page
-containing the port is unloaded (for example if the tab is navigated).
-onDisconnect is guaranteed to be fired only once for any given port.
+event. This event is fired when there are no valid ports at the other side of
+the channel. This happens in the following situations:
+<ul>
+ <li>
+ There are no listeners for $(ref:runtime.onConnect) at the other end.
+ <li>
+ The tab containing the port is unloaded (e.g. if the tab is navigated).
+ <li>
+ The frame from where <code>connect</code> was called has unloaded.
+ <li>
+ All frames that received the port (via $(ref:runtime.onConnect)) have
+ unloaded.
+ <li>
+ $(ref:runtime.Port.disconnect) is called by <em>the other end</em>.
+ Note that if a <code>connect</code> call results in multiple ports at the
+ receiver's end, and <code>disconnect()</code> is called on any of these
+ ports, then the <code>onDisconnect</code> event is only fired at the port
+ of the sender, and not at the other ports.
+</ul>
<h2 id="external">Cross-extension messaging</h2>
« no previous file with comments | « chrome/common/extensions/api/tabs.json ('k') | extensions/common/api/runtime.json » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698