Annotation of html5/postmsg/Overview.html, revision 1.157
1.114 ihickson 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"><html lang="en-US-x-Hixie"><title>HTML5 Web Messaging</title><style type="text/css">
1.1 ihickson 2: pre { margin-left: 2em; white-space: pre-wrap; }
3: h2 { margin: 3em 0 1em 0; }
4: h3 { margin: 2.5em 0 1em 0; }
5: h4 { margin: 2.5em 0 0.75em 0; }
6: h5, h6 { margin: 2.5em 0 1em; }
7: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
8: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
9: p { margin: 1em 0; }
10: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
11: dl, dd { margin-top: 0; margin-bottom: 0; }
12: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
13: dt + dt { margin-top: 0; }
14: dd dt { margin-top: 0.25em; margin-bottom: 0; }
15: dd p { margin-top: 0; }
16: dd dl + p { margin-top: 1em; }
17: dd table + p { margin-top: 1em; }
18: p + * > li, dd li { margin: 1em 0; }
19: dt, dfn { font-weight: bold; font-style: normal; }
1.91 ihickson 20: i, em { font-style: italic; }
1.1 ihickson 21: dt dfn { font-style: italic; }
22: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
23: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
24: pre em { font-weight: bolder; font-style: normal; }
25: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
26: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
27: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
1.39 ihickson 28: table thead, table tbody { border-bottom: solid; }
1.1 ihickson 29: table tbody th:first-child { border-left: solid; }
30: table tbody th { text-align: left; }
31: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
32: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
33:
34: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
35: .matrix, .matrix td { border: none; text-align: right; }
36: .matrix { margin-left: 2em; }
37: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
38: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
39: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
40:
41: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
1.94 ihickson 42: img.extra, p.overview { float: right; }
1.93 ihickson 43: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
1.1 ihickson 44: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
1.93 ihickson 45: pre.idl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
1.1 ihickson 46: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
47: pre.css:first-line { color: #AAAA50; }
1.15 ihickson 48: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
1.1 ihickson 49: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
50: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
51: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
52: dl.domintro dd p { margin: 0.5em 0; }
1.99 ihickson 53: dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
1.1 ihickson 54: dl.switch { padding-left: 2em; }
55: dl.switch > dt { text-indent: -1.5em; }
56: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
57: dl.triple { padding: 0 0 0 1em; }
58: dl.triple dt, dl.triple dd { margin: 0; display: inline }
59: dl.triple dt:after { content: ':'; }
60: dl.triple dd:after { content: '\A'; white-space: pre; }
61: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
62: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
63: a .diff-new { border-bottom: 1px blue solid; }
64:
65: h2 { page-break-before: always; }
66: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
67: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
68:
1.64 ihickson 69: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
70: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 ihickson 71:
72: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
73: div.head p { margin: 0; }
74: div.head h1 { margin: 0; }
75: div.head .logo { float: right; margin: 0 1em; }
76: div.head .logo img { border: none } /* remove border from top image */
77: div.head dl { margin: 1em 0; }
78: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
79:
80: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
81: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
82: body > .toc > li > * { margin-bottom: 0.5em; }
83: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
84: .toc, .toc li { list-style: none; }
85:
86: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
87: .brief li { margin: 0; padding: 0; }
88: .brief li p { margin: 0; padding: 0; }
89:
90: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
91: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
92: .category-list li { display: inline; }
93: .category-list li:not(:last-child)::after { content: ', '; }
94: .category-list li > span, .category-list li > a { text-transform: lowercase; }
95: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
96:
97: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
98: .XXX > :first-child { margin-top: 0; }
99: p .XXX { line-height: 3em; }
100: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
101: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
102: .annotation :link, .annotation :visited { color: inherit; }
103: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
104: .annotation span { border: none ! important; }
105: .note { color: green; background: transparent; font-family: sans-serif; }
106: .warning { color: red; background: transparent; }
107: .note, .warning { font-weight: bolder; font-style: italic; }
1.91 ihickson 108: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.1 ihickson 109: p.note, div.note { padding: 0.5em 2em; }
110: span.note { padding: 0 2em; }
111: .note p:first-child, .warning p:first-child { margin-top: 0; }
112: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
113: .warning:before { font-style: normal; }
114: p.note:before { content: 'Note: '; }
115: p.warning:before { content: '\26A0 Warning! '; }
116:
117: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
118: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
119: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.57 ihickson 120: .bookkeeping dt { margin: 0.5em 2em 0; }
121: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 ihickson 122:
123: h4 { position: relative; z-index: 3; }
124: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
125: .element {
126: background: #EEEEFF;
127: color: black;
128: margin: 0 0 1em 0.15em;
129: padding: 0 1em 0.25em 0.75em;
130: border-left: solid #9999FF 0.25em;
131: position: relative;
132: z-index: 1;
133: }
134: .element:before {
135: position: absolute;
136: z-index: 2;
137: top: 0;
138: left: -1.15em;
139: height: 2em;
140: width: 0.9em;
141: background: #EEEEFF;
142: content: ' ';
143: border-style: none none solid solid;
144: border-color: #9999FF;
145: border-width: 0.25em;
146: }
147:
148: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
149: td > .example:only-child { margin: 0 0 0 0.1em; }
150:
151: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
152: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
153: ul.domTree li li { list-style: none; }
154: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
155: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
156: ul.domTree span { font-style: italic; font-family: serif; }
157: ul.domTree .t1 code { color: purple; font-weight: bold; }
158: ul.domTree .t2 { font-style: normal; font-family: monospace; }
159: ul.domTree .t2 .name { color: black; font-weight: bold; }
160: ul.domTree .t2 .value { color: blue; font-weight: normal; }
161: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
162: ul.domTree .t7 code, .domTree .t8 code { color: green; }
163: ul.domTree .t10 code { color: teal; }
164:
1.7 ihickson 165: body.dfnEnabled dfn { cursor: pointer; }
166: .dfnPanel {
167: display: inline;
168: position: absolute;
169: z-index: 10;
170: height: auto;
171: width: auto;
172: padding: 0.5em 0.75em;
173: font: small sans-serif, Droid Sans Fallback;
174: background: #DDDDDD;
175: color: black;
176: border: outset 0.2em;
177: }
178: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
179: .dfnPanel :link, .dfnPanel :visited { color: black; }
180: .dfnPanel p { font-weight: bolder; }
181: .dfnPanel * + p { margin-top: 0.25em; }
182: .dfnPanel li { list-style-position: inside; }
183:
1.1 ihickson 184: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
185: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
186: #configUI p label { display: block; }
187: #configUI #updateUI, #configUI .loginUI { text-align: center; }
188: #configUI input[type=button] { display: block; margin: auto; }
1.56 ihickson 189:
1.66 ihickson 190: fieldset { margin: 1em; padding: 0.5em 1em; }
191: fieldset > legend + * { margin-top: 0; }
1.63 ihickson 192: fieldset > :last-child { margin-bottom: 0; }
1.66 ihickson 193: fieldset p { margin: 0.5em 0; }
1.63 ihickson 194:
1.147 ihickson 195: </style><link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-ED" type="text/css"><meta content="noindex" name="robots"><script type="text/javascript">
1.1 ihickson 196: function getCookie(name) {
197: var params = location.search.substr(1).split("&");
198: for (var index = 0; index < params.length; index++) {
199: if (params[index] == name)
200: return "1";
201: var data = params[index].split("=");
202: if (data[0] == name)
203: return unescape(data[1]);
204: }
205: var cookies = document.cookie.split("; ");
206: for (var index = 0; index < cookies.length; index++) {
207: var data = cookies[index].split("=");
208: if (data[0] == name)
209: return unescape(data[1]);
210: }
211: return null;
212: }
1.114 ihickson 213: </script><body>
214: <div class="head" id="head">
1.147 ihickson 215: <p><a href="http://www.w3.org/"><img width="72" src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48"></a></p>
1.48 ihickson 216:
1.10 ihickson 217: <h1>HTML5 Web Messaging</h1>
1.79 ihickson 218:
1.157 ! ihickson 219: <h2 class="no-num no-toc" id="editor-s-draft-13-november-2013">Editor's Draft 13 November 2013</h2>
1.72 ihickson 220: <dl><dt>Latest Published Version:</dt>
1.70 abarsto 221: <dd><a href="http://www.w3.org/TR/webmessaging/">http://www.w3.org/TR/webmessaging/</a></dd>
1.1 ihickson 222: <dt>Latest Editor's Draft:</dt>
1.147 ihickson 223: <dd><a href="http://dev.w3.org/html5/postmsg/" class="latest-link">http://dev.w3.org/html5/postmsg/</a></dd>
1.82 ihickson 224:
1.113 ihickson 225:
1.1 ihickson 226: <dt>Previous Versions:</dt>
1.72 ihickson 227: <dd><a href="http://www.w3.org/TR/2010/WD-webmessaging-20101118/">http://www.w3.org/TR/2010/WD-webmessaging-20101118/</a></dd>
1.1 ihickson 228: <!-- :ZZZ -->
1.72 ihickson 229: <dt>Editor:</dt>
1.1 ihickson 230: <dd><a href="mailto:ian@hixie.ch">Ian Hickson</a>, Google, Inc.</dd>
1.3 ihickson 231: </dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
1.115 ihickson 232: © 2012 <a href="http://www.w3.org/"><abbr title="World Wide
1.1 ihickson 233: Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts
1.90 ihickson 234: Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research
1.1 ihickson 235: Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C
236: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
237: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
238: and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document
239: use</a> rules apply.</p>
1.6 ihickson 240:
1.48 ihickson 241:
1.6 ihickson 242: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
1.52 ihickson 243: <p class="alt">The bulk of the text of this specification is also
1.48 ihickson 244: available in the WHATWG <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html#comms">Web Applications 1.0</a> specification, under a license that permits
245: reuse of the specification text.</p>
1.6 ihickson 246: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
247:
1.48 ihickson 248:
1.114 ihickson 249: </div>
250:
251: <hr class="top"><h2 class="no-num no-toc" id="abstract">Abstract</h2>
252:
253: <p>This specification defines two mechanisms for communicating
254: between browsing contexts in HTML documents.</p>
255:
256: <h2 class="no-num no-toc" id="status-of-this-document">Status of This document</h2>
257:
258:
259:
260:
261: <p><em>This section describes the status of this document at the
1.1 ihickson 262: time of its publication. Other documents may supersede this
1.90 ihickson 263: document. A list of current W3C publications and the
264:
265: most recently formally published <!-- DO NOT CHANGE THIS BACK TO THE STANDARD BOILERPLATE, AS IT IS INACCURATE -->
266:
267: revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
1.114 ihickson 268: http://www.w3.org/TR/.</em></p>
269:
270:
271:
272:
1.126 ihickson 273: <p>If you wish to make comments regarding this document, you can
1.114 ihickson 274: enter feedback using this form:</p>
275:
276: <form action="http://www.whatwg.org/specs/web-apps/current-work/file-spam.cgi" method="post">
1.63 ihickson 277: <fieldset><legend>Feedback Comments</legend>
1.147 ihickson 278: <input value="top" name="id" type="hidden"><input value="Web Messaging (editor: Ian Hickson)" name="component" type="hidden"><input value="html" name="response" type="hidden"><p><label for="feedbackBox">Please enter your feedback, carefully
1.65 ihickson 279: indicating the title of the section for which you are submitting
280: feedback, quoting the text that's wrong today if appropriate. If
281: you're suggesting a new feature, it's really important to say
282: <em>what</em> the problem you're trying to solve is. That's more
283: important than the solution, in fact.</label></p>
1.147 ihickson 284: <p><textarea name="text" rows="10" id="feedbackBox" cols="79"></textarea></p>
1.66 ihickson 285: <p class="note">Please don't use section numbers as these tend to
286: change rapidly and make your feedback harder to understand.</p>
1.65 ihickson 287: <script type="text/javascript">
1.85 ihickson 288: function checkFeedbackForm(form) {
289: if (form.elements.text.value.match(/^ *</)) {
290: alert('Please don\'t start your feedback with an angle bracket, instead explain what topic your feedback is about first.');
291: return true;
292: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
293: if (form.elements.text.value.match(/^Please enter your feedback, carefully/)) {
294: alert('Please enter your feedback, explaining what is wrong, and without repeating the instructions. Thanks!');
295: return true;
296: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
297: form.action = "http://www.whatwg.org/specs/web-apps/current-work/file-bug.cgi";
298: return true;
299: } else {
300: alert('Please include significantly more detail about exactly what problem you are trying to solve.');
301: return false;
302: }
303: }
304: }
1.66 ihickson 305: </script><p>
1.147 ihickson 306: <input value="Submit feedback" onclick="return checkFeedbackForm(form)" type="submit"><small>(Note: Your IP address and user agent will be publicly recorded for spam prevention purposes.)</small>
1.66 ihickson 307: </p>
1.114 ihickson 308: </fieldset></form>
309:
310:
311: <p>You can also e-mail feedback to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>,
1.72 ihickson 312: <a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>),
313: or <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a> (<a href="http://lists.whatwg.org/listinfo.cgi/whatwg-whatwg.org">subscribe</a>,
1.63 ihickson 314: <a href="http://lists.whatwg.org/pipermail/whatwg-whatwg.org/">archives</a>).
1.114 ihickson 315: All feedback is welcome.</p>
316:
317:
318: <p>Implementors should be aware that this specification is not
1.72 ihickson 319: stable. <strong>Implementors who are not taking part in the
320: discussions are likely to find the specification changing out from
321: under them in incompatible ways.</strong> Vendors interested in
322: implementing this specification before it eventually reaches the
323: Candidate Recommendation stage should join the aforementioned
1.114 ihickson 324: mailing lists and take part in the discussions.</p>
325:
326: <div id="multipage-common">
327: </div>
328:
329: <p>The latest
1.72 ihickson 330: stable version of the editor's draft of this specification is always
331: available on <a href="http://dev.w3.org/html5/postmsg/">the W3C CVS server</a>
332: and in the <a href="http://svn.whatwg.org/webapps/">WHATWG
333: Subversion repository</a>. The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html">latest
1.1 ihickson 334: editor's working copy</a> (which may contain unfinished text in the
335: process of being prepared) contains the latest draft text of this
336: specification (amongst others). For more details, please see the <a href="http://wiki.whatwg.org/wiki/FAQ#What_are_the_various_versions_of_the_spec.3F">WHATWG
1.114 ihickson 337: FAQ</a>.</p>
338:
339: <p>Notifications of changes to this specification are sent along
1.72 ihickson 340: with notifications of changes to related specifications using the
1.114 ihickson 341: following mechanisms:</p>
342: <dl><dt>E-mail notifications of changes</dt>
1.1 ihickson 343: <dd>Commit-Watchers mailing list (complete source diffs): <a href="http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org">http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org</a></dd>
344: <dt>Browsable version-control record of all changes:</dt>
345: <dd>CVSWeb interface with side-by-side diffs: <a href="http://dev.w3.org/cvsweb/html5/">http://dev.w3.org/cvsweb/html5/</a></dd>
346: <dd>Annotated summary with unified diffs: <a href="http://html5.org/tools/web-apps-tracker">http://html5.org/tools/web-apps-tracker</a></dd>
347: <dd>Raw Subversion interface: <code>svn checkout http://svn.whatwg.org/webapps/</code></dd>
1.72 ihickson 348: </dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
349: Working Group</a> is the W3C working group responsible for this
350: specification's progress along the W3C Recommendation track.
1.157 ! ihickson 351: This specification is the 13 November 2013 Editor's Draft.
1.114 ihickson 352: </p>
353:
354:
355:
356: <p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
1.147 ihickson 357: February 2004 W3C Patent Policy</a>. W3C maintains a <a rel="disclosure" href="http://www.w3.org/2004/01/pp-impl/42538/status">public list of
1.1 ihickson 358: any patent disclosures</a> made in connection with the deliverables
359: of the group; that page also includes instructions for disclosing a
360: patent. An individual who has actual knowledge of a patent which the
361: individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
362: Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
1.114 ihickson 363: 6 of the W3C Patent Policy</a>.</p>
364:
365:
366: <h2 class="no-num no-toc" id="contents">Table of Contents</h2>
367:
1.113 ihickson 368:
1.1 ihickson 369: <ol class="toc">
1.72 ihickson 370: <li><a href="#conformance-requirements"><span class="secno">1 </span>Conformance requirements</a>
1.1 ihickson 371: <ol>
1.72 ihickson 372: <li><a href="#dependencies"><span class="secno">1.1 </span>Dependencies</a></ol></li>
373: <li><a href="#terminology"><span class="secno">2 </span>Terminology</a></li>
374: <li><a href="#event-definitions"><span class="secno">3 </span>Event definitions</a></li>
375: <li><a href="#web-messaging"><span class="secno">4 </span>Cross-document messaging</a>
376: <ol>
377: <li><a href="#introduction"><span class="secno">4.1 </span>Introduction</a></li>
378: <li><a href="#security-postmsg"><span class="secno">4.2 </span>Security</a>
1.1 ihickson 379: <ol>
1.72 ihickson 380: <li><a href="#authors"><span class="secno">4.2.1 </span>Authors</a></li>
381: <li><a href="#user-agents"><span class="secno">4.2.2 </span>User agents</a></ol></li>
382: <li><a href="#posting-messages"><span class="secno">4.3 </span>Posting messages</a></ol></li>
383: <li><a href="#channel-messaging"><span class="secno">5 </span>Channel messaging</a>
1.1 ihickson 384: <ol>
1.100 ihickson 385: <li><a href="#introduction-0"><span class="secno">5.1 </span>Introduction</a>
386: <ol>
1.121 ihickson 387: <li><a href="#examples"><span class="secno">5.1.1 </span>Examples</a></li>
388: <li><a href="#ports-as-the-basis-of-an-object-capability-model-on-the-web"><span class="secno">5.1.2 </span>Ports as the basis of an object-capability model on the Web</a></li>
389: <li><a href="#ports-as-the-basis-of-abstracting-out-service-implementations"><span class="secno">5.1.3 </span>Ports as the basis of abstracting out service implementations</a></ol></li>
1.72 ihickson 390: <li><a href="#message-channels"><span class="secno">5.2 </span>Message channels</a></li>
1.128 ihickson 391: <li><a href="#message-ports"><span class="secno">5.3 </span>Message ports</a></li>
392: <li><a href="#broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</a></li>
393: <li><a href="#ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</a></ol></li>
1.147 ihickson 394: <li><a href="#references" class="no-num">References</a></li>
395: <li><a href="#acknowledgements" class="no-num">Acknowledgements</a></ol>
1.114 ihickson 396:
397: <hr><h2 id="conformance-requirements"><span class="secno">1 </span>Conformance requirements</h2>
398:
399: <p>All diagrams, examples, and notes in this specification are
1.72 ihickson 400: non-normative, as are all sections explicitly marked non-normative.
1.114 ihickson 401: Everything else in this specification is normative.</p>
402:
403: <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
1.72 ihickson 404: "OPTIONAL" in the normative parts of this document are to be
405: interpreted as described in RFC2119. For readability, these words do
1.114 ihickson 406: not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
407:
408: <p>Requirements phrased in the imperative as part of algorithms
1.72 ihickson 409: (such as "strip any leading space characters" or "return false and
410: abort these steps") are to be interpreted with the meaning of the
411: key word ("must", "should", "may", etc) used in introducing the
1.114 ihickson 412: algorithm.</p>
413:
414: <p>Some conformance requirements are phrased as requirements on
1.72 ihickson 415: attributes, methods or objects. Such requirements are to be
1.114 ihickson 416: interpreted as requirements on user agents.</p>
417:
418: <p>Conformance requirements phrased as algorithms or specific steps
1.72 ihickson 419: may be implemented in any manner, so long as the end result is
420: equivalent. (In particular, the algorithms defined in this
421: specification are intended to be easy to follow, and not intended to
1.114 ihickson 422: be performant.)</p>
423:
424: <p>The only conformance class defined by this specification is user
425: agents.</p>
426:
427: <p>User agents may impose implementation-specific limits on
1.72 ihickson 428: otherwise unconstrained inputs, e.g. to prevent denial of service
429: attacks, to guard against running out of memory, or to work around
1.114 ihickson 430: platform-specific limitations.</p>
431:
432: <p>When support for a feature is disabled (e.g. as an emergency
1.72 ihickson 433: measure to mitigate a security problem, or to aid in development, or
434: for performance reasons), user agents must act as if they had no
435: support for the feature whatsoever, and as if the feature was not
436: mentioned in this specification. For example, if a particular
437: feature is accessed via an attribute in a Web IDL interface, the
438: attribute itself would be omitted from the objects that implement
439: that interface — leaving the attribute on the object but
1.114 ihickson 440: making it return null or throw an exception is insufficient.</p>
441:
442:
443: <h3 id="dependencies"><span class="secno">1.1 </span>Dependencies</h3>
444:
445: <p>This specification relies on several other underlying
446: specifications.</p>
447:
448: <dl><dt>HTML</dt>
1.72 ihickson 449:
450: <dd>
451:
452: <p>Many fundamental concepts from HTML are used by this
453: specification. <a href="#refsHTML">[HTML]</a></p>
454:
455: </dd>
456:
457: <dt>WebIDL</dt>
458:
459: <dd>
460:
461: <p>The IDL blocks in this specification use the semantics of the
462: WebIDL specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
463:
464: </dd>
465:
1.114 ihickson 466: </dl><h2 id="terminology"><span class="secno">2 </span>Terminology</h2>
467:
468: <p>The construction "a <code title="">Foo</code> object", where
1.72 ihickson 469: <code title="">Foo</code> is actually an interface, is sometimes
470: used instead of the more accurate "an object implementing the
1.114 ihickson 471: interface <code title="">Foo</code>".</p>
472:
473: <p>The term DOM is used to refer to the API set made available to
1.72 ihickson 474: scripts in Web applications, and does not necessarily imply the
475: existence of an actual <code>Document</code> object or of any other
1.132 ihickson 476: <code>Node</code> objects as defined in the DOM specifications. <a href="#refsDOM">[DOM]</a></p>
1.114 ihickson 477:
478: <p>An IDL attribute is said to be <em>getting</em> when its value is
1.72 ihickson 479: being retrieved (e.g. by author script), and is said to be
1.114 ihickson 480: <em>setting</em> when a new value is assigned to it.</p>
481:
482:
483:
484: <h2 id="event-definitions"><span class="secno">3 </span>Event definitions</h2>
485:
1.133 ihickson 486: <p>Messages in <span>server-sent events</span>, <span>Web sockets</span>, <a href="#web-messaging">cross-document
1.157 ! ihickson 487: messaging</a>, <a href="#channel-messaging">channel messaging</a>, and <span>broadcast channels</span> use the <dfn id="event-message" title="event-message"><code>message</code></dfn> event. </p>
1.114 ihickson 488:
489: <p>The following interface is defined for this event:</p>
490:
491: <pre class="idl">[Constructor(DOMString type, optional <a href="#messageeventinit">MessageEventInit</a> eventInitDict)]
1.96 ihickson 492: interface <dfn id="messageevent">MessageEvent</dfn> : <span>Event</span> {
1.1 ihickson 493: readonly attribute any <a href="#dom-messageevent-data" title="dom-MessageEvent-data">data</a>;
494: readonly attribute DOMString <a href="#dom-messageevent-origin" title="dom-MessageEvent-origin">origin</a>;
495: readonly attribute DOMString <a href="#dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId">lastEventId</a>;
1.157 ! ihickson 496: readonly attribute DOMString <a href="#dom-messageevent-channel" title="dom-MessageEvent-channel">channel</a>;
1.118 ihickson 497: readonly attribute (<span>WindowProxy</span> or <a href="#messageport">MessagePort</a>)? <a href="#dom-messageevent-source" title="dom-MessageEvent-source">source</a>;
1.96 ihickson 498: readonly attribute <a href="#messageport">MessagePort</a>[]? <a href="#dom-messageevent-ports" title="dom-MessageEvent-ports">ports</a>;
499: };
500:
501: dictionary <dfn id="messageeventinit">MessageEventInit</dfn> : <span>EventInit</span> {
502: any data;
503: DOMString origin;
504: DOMString lastEventId;
1.157 ! ihickson 505: DOMString channel;
1.149 ihickson 506: (<span>WindowProxy</span> or <a href="#messageport">MessagePort</a>)? source;
1.155 ihickson 507: sequence<<a href="#messageport">MessagePort</a>> ports;
1.114 ihickson 508: };</pre>
509:
510: <dl class="domintro"><dt><var title="">event</var> . <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code></dt>
1.1 ihickson 511:
512: <dd>
513:
514: <p>Returns the data of the message.</p>
515:
516: </dd>
517:
518: <dt><var title="">event</var> . <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code></dt>
519:
520: <dd>
521:
1.136 ihickson 522: <p>Returns the origin of the message, for <span>server-sent events</span> and
523: <a href="#web-messaging">cross-document messaging</a>.</p>
1.1 ihickson 524:
525: </dd>
526:
527: <dt><var title="">event</var> . <code title="dom-MessageEvent-lastEventId"><a href="#dom-messageevent-lasteventid">lastEventId</a></code></dt>
528:
529: <dd>
530:
1.136 ihickson 531: <p>Returns the <span title="concept-event-stream-last-event-id">last event ID string</span>, for
532: <span>server-sent events</span>.</p>
1.1 ihickson 533:
534: </dd>
535:
1.157 ! ihickson 536: <dt><var title="">event</var> . <code title="dom-MessageEvent-channel"><a href="#dom-messageevent-channel">channel</a></code></dt>
! 537:
! 538: <dd>
! 539:
! 540: <p>Returns the channel ID, for <span>broadcast channels</span>.</p>
! 541:
! 542: </dd>
! 543:
1.1 ihickson 544: <dt><var title="">event</var> . <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code></dt>
545:
546: <dd>
547:
1.136 ihickson 548: <p>Returns the <code>WindowProxy</code> of the source window, for <a href="#web-messaging">cross-document
549: messaging</a>, and the <code><a href="#messageport">MessagePort</a></code> being attached, in the <code title="event-connect">connect</code> event fired at <code>SharedWorkerGlobalScope</code>
550: objects.</p>
1.1 ihickson 551:
552: </dd>
553:
554: <dt><var title="">event</var> . <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code></dt>
555:
556: <dd>
557:
1.136 ihickson 558: <p>Returns the <code><a href="#messageport">MessagePort</a></code> array sent with the message, for <a href="#web-messaging">cross-document
559: messaging</a> and <a href="#channel-messaging">channel messaging</a>.</p>
1.1 ihickson 560:
561: </dd>
562:
563: </dl><div class="impl">
564:
1.153 ihickson 565: <p>The <dfn id="dom-messageevent-data" title="dom-MessageEvent-data"><code>data</code></dfn> attribute must return the value
566: it was initialized to. When the object is created, this attribute must be initialized to null. It
1.96 ihickson 567: represents the message being sent.</p>
1.1 ihickson 568:
1.153 ihickson 569: <p>The <dfn id="dom-messageevent-origin" title="dom-MessageEvent-origin"><code>origin</code></dfn> attribute must return the
570: value it was initialized to. When the object is created, this attribute must be initialized to the
571: empty string. It represents, in <span>server-sent events</span> and <a href="#web-messaging">cross-document
572: messaging</a>, the <span>origin</span> of the document that sent the message (typically the
573: scheme, hostname, and port of the document, but not its path or fragment identifier).</p>
574:
575: <p>The <dfn id="dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId"><code>lastEventId</code></dfn> attribute must
576: return the value it was initialized to. When the object is created, this attribute must be
577: initialized to the empty string. It represents, in <span>server-sent events</span>, the <span title="concept-event-stream-last-event-id">last event ID string</span> of the event source.</p>
578:
1.157 ! ihickson 579: <p>The <dfn id="dom-messageevent-channel" title="dom-MessageEvent-channel"><code>channel</code></dfn> attribute must return the
! 580: value it was initialized to. When the object is created, this attribute must be initialized to the
! 581: empty string. It represents, in <span>broadcast channels</span>, the channel of the message.</p>
! 582:
1.153 ihickson 583: <p>The <dfn id="dom-messageevent-source" title="dom-MessageEvent-source"><code>source</code></dfn> attribute must return the
584: value it was initialized to. When the object is created, this attribute must be initialized to
585: null. It represents, in <a href="#web-messaging">cross-document messaging</a>, the <code>WindowProxy</code> of the
586: <span>browsing context</span> of the <code>Window</code> object from which the message came; and
587: in the <code title="event-connect">connect</code> events used by <span title="SharedWorkerGlobalScope">shared workers</span>, the newly connecting
588: <code><a href="#messageport">MessagePort</a></code>.</p>
589:
590: <p>The <dfn id="dom-messageevent-ports" title="dom-MessageEvent-ports"><code>ports</code></dfn> attribute must return the
591: value it was initialized to. When the object is created, this attribute must be initialized to
592: null. It represents, in
1.155 ihickson 593: <a href="#web-messaging">cross-document messaging</a> and <a href="#channel-messaging">channel messaging</a>, the
1.153 ihickson 594: <code><a href="#messageport">MessagePort</a></code> array being sent, if any.</p>
1.1 ihickson 595:
1.114 ihickson 596: </div>
597:
598:
599: <h2 id="web-messaging"><span class="secno">4 </span><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h2>
600:
1.153 ihickson 601: <p>Web browsers, for security and privacy reasons, prevent documents in different domains from
602: affecting each other; that is, cross-site scripting is disallowed.</p>
603:
604: <p>While this is an important security feature, it prevents pages from different domains from
605: communicating even when those pages are not hostile. This section introduces a messaging system
606: that allows documents to communicate with each other regardless of their source domain, in a way
607: designed to not enable cross-site scripting attacks.</p>
1.114 ihickson 608:
609: <div class="impl">
1.1 ihickson 610:
1.153 ihickson 611: <p>The <span>task source</span> for the <span title="concept-task">tasks</span> in
612: <a href="#web-messaging">cross-document messaging</a> is the <dfn id="posted-message-task-source">posted message task source</dfn>.</p>
1.1 ihickson 613:
1.114 ihickson 614: </div>
615:
616:
617: <h3 id="introduction"><span class="secno">4.1 </span>Introduction</h3>
618:
619: <p><i>This section is non-normative.</i></p>
620:
621: <div class="example">
1.1 ihickson 622:
1.153 ihickson 623: <p>For example, if document A contains an <code>iframe</code> element that contains document B,
624: and script in document A calls <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> on the
625: <code>Window</code> object of document B, then a message event will be fired on that object,
626: marked as originating from the <code>Window</code> of document A. The script in document A might
1.1 ihickson 627: look like:</p>
628:
629: <pre>var o = document.getElementsByTagName('iframe')[0];
630: o.contentWindow.postMessage('Hello world', 'http://b.example.org/');</pre>
631:
1.153 ihickson 632: <p>To register an event handler for incoming events, the script would use <code title="">addEventListener()</code> (or similar mechanisms). For example, the script in document B
633: might look like:</p>
1.1 ihickson 634:
635: <pre>window.addEventListener('message', receiver, false);
636: function receiver(e) {
637: if (e.origin == 'http://example.com') {
638: if (e.data == 'Hello world') {
639: e.source.postMessage('Hello', e.origin);
640: } else {
641: alert(e.data);
642: }
643: }
644: }</pre>
645:
1.153 ihickson 646: <p>This script first checks the domain is the expected domain, and then looks at the message,
647: which it either displays to the user, or responds to by sending a message back to the document
648: which sent the message in the first place.</p>
1.1 ihickson 649:
1.114 ihickson 650: </div>
651:
652:
653:
654: <h3 id="security-postmsg"><span class="secno">4.2 </span>Security</h3>
655:
656: <div class="impl">
1.1 ihickson 657:
1.72 ihickson 658: <h4 id="authors"><span class="secno">4.2.1 </span>Authors</h4>
1.1 ihickson 659:
1.114 ihickson 660: </div>
661:
1.153 ihickson 662: <p id="security-4" class="warning">Use of this API requires extra care to protect users from
663: hostile entities abusing a site for their own purposes.</p>
664:
665: <p>Authors should check the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute to
666: ensure that messages are only accepted from domains that they expect to receive messages from.
667: Otherwise, bugs in the author's message handling code could be exploited by hostile sites.</p>
668:
669: <p>Furthermore, even after checking the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code>
670: attribute, authors should also check that the data in question is of the expected format.
671: Otherwise, if the source of the event has been attacked using a cross-site scripting flaw, further
672: unchecked processing of information sent using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method could result in the attack being
673: propagated into the receiver.</p>
674:
675: <p>Authors should not use the wildcard keyword (*) in the <var title="">targetOrigin</var>
676: argument in messages that contain any confidential information, as otherwise there is no way to
677: guarantee that the message is only delivered to the recipient to which it was intended.</p>
678:
679: <hr><p>Authors who accept messages from any origin are encouraged to consider the risks of a
680: denial-of-service attack. An attacker could send a high volume of messages; if the receiving page
681: performs expensive computation or causes network traffic to be sent for each such message, the
682: attacker's message could be multplied into a denial-of-service attack. Authors are encouraged to
683: employ rate limiting (only accepting a certain number of messages per minute) to make such attacks
684: impractical.</p>
1.114 ihickson 685:
686:
687: <div class="impl">
1.1 ihickson 688:
1.72 ihickson 689: <h4 id="user-agents"><span class="secno">4.2.2 </span>User agents</h4>
1.1 ihickson 690:
1.153 ihickson 691: <p>The integrity of this API is based on the inability for scripts of one <span>origin</span> to
692: post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in
693: other origins (those that are not the <span title="same origin">same</span>).</p>
694:
695: <p class="note">Implementors are urged to take extra care in the implementation of this feature.
696: It allows authors to transmit information from one domain to another domain, which is normally
697: disallowed for security reasons. It also requires that UAs be careful to allow access to certain
698: properties but not others.</p>
699:
700: <hr><p>User agents are also encouraged to consider rate-limiting message traffic between different
701: <span title="origin">origins</span>, to protect naïve sites from denial-of-service
702: attacks.</p>
1.108 ihickson 703:
1.114 ihickson 704: </div>
705:
706:
707:
708: <h3 id="posting-messages"><span class="secno">4.3 </span>Posting messages</h3>
709:
710: <dl class="domintro"><dt><var title="">window</var> . <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage</a></code>(<var title="">message</var>, <var title="">targetOrigin</var> [, <var title="">transfer</var> ])</dt>
1.1 ihickson 711:
712: <dd>
713:
1.153 ihickson 714: <p>Posts a message to the given window. Messages can be structured objects, e.g. nested objects
715: and arrays, can contain JavaScript values (strings, numbers, <code>Date</code>s, etc), and can
716: contain certain data objects such as <code>File</code> <code>Blob</code>, <code>FileList</code>,
717: and <code>ArrayBuffer</code> objects.</p>
718:
719: <p>Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning that
720: they are no longer usable on the sending side.</p>
721:
722: <p>If the origin of the target window doesn't match the given origin, the message is discarded,
723: to avoid information leakage. To send the message to the target regardless of origin, set the
724: target origin to "<code title="">*</code>". To restrict the message to same-origin targets only,
725: without needing to explicitly state the origin, set the target origin to "<code title="">/</code>".</p>
1.1 ihickson 726:
1.138 ihickson 727: <p>Throws a <code>DataCloneError</code> exception if <var title="">transfer</var> array contains
728: duplicate objects or if <var title="">message</var> could not be cloned.</p>
1.1 ihickson 729:
730: </dd>
731:
1.153 ihickson 732: </dl><p class="note">When posting a message to a <code>Window</code> of a <span>browsing context</span>
733: that has just been navigated to a new <code>Document</code> is likely to result in the message not
734: receiving its intended recipient: the scripts in the target <span>browsing context</span> have to
735: have had time to set up listeners for the messages. Thus, for instance, in situations where a
736: message is to be sent to the <code>Window</code> of newly created child <code>iframe</code>,
737: authors are advised to have the child <code>Document</code> post a message to their parent
738: announcing their readiness to receive messages, and for the parent to wait for this message before
739: beginning posting messages.</p>
1.114 ihickson 740:
741: <div class="impl">
1.1 ihickson 742:
1.153 ihickson 743: <p>When a script invokes the <dfn id="dom-window-postmessage" title="dom-window-postMessage"><code>postMessage(<var title="">message</var>, <var title="">targetOrigin</var>, <var title="">transfer</var>)</code></dfn> method (with two or three arguments) on a
744: <code>Window</code> object, the user agent must follow these steps:</p>
1.1 ihickson 745:
746: <ol><li>
747:
1.153 ihickson 748: <p>If the value of the <var title="">targetOrigin</var> argument is neither a single U+002A
749: ASTERISK character (*), a single U+002F SOLIDUS character (/), nor an <span>absolute URL</span>,
750: then throw a <code>SyntaxError</code> exception and abort the overall set of steps.</p>
1.1 ihickson 751:
752: </li>
753:
754: <li>
755:
1.88 ihickson 756: <p>Let <var title="">new ports</var> be an empty array.</p>
1.1 ihickson 757:
758: </li>
759:
760: <li>
761:
1.153 ihickson 762: <p>Let <var title="">transfer map</var> be an empty association list of
763: <code>Transferable</code> objects to placeholder objects.</p>
1.1 ihickson 764:
765: </li>
766:
767: <li>
768:
1.153 ihickson 769: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
770: substeps:</p>
1.88 ihickson 771:
772: <ol><li>
773:
1.153 ihickson 774: <p>If any object is listed in <var title="">transfer</var> more than once, or any of the
775: <code>Transferable</code> objects listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then throw a
776: <code>DataCloneError</code> exception and abort these steps.</p>
1.88 ihickson 777:
778: </li>
779:
780: <li>
781:
1.153 ihickson 782: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a
783: mapping from <var title="">x</var> to a new unique placeholder object created for <var title="">x</var> to <var title="">transfer map</var>, and if <var title="">x</var> is a
784: <code><a href="#messageport">MessagePort</a></code> object, also append the placeholder object to the <var title="">new
1.105 ihickson 785: ports</var> array.</p>
1.88 ihickson 786:
787: </li>
788:
789: </ol></li>
790:
791: <li>
1.1 ihickson 792:
1.153 ihickson 793: <p>Let <var title="">message clone</var> be the result of obtaining a <span>structured
794: clone</span> of the <var title="">message</var> argument, with <var title="">transfer map</var>
795: as the <i>transfer map</i>. If this throws an exception, then throw that exception and abort
796: these steps.</p>
1.1 ihickson 797:
798: </li>
799:
1.106 ihickson 800: <li>
801:
1.153 ihickson 802: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
803: substeps:</p>
1.105 ihickson 804:
805: <ol><li>
806:
1.154 ihickson 807: <p>Let <var title="">new owner</var> be the <span>script settings object</span> of the <code>Window</code> object on which the method was
1.153 ihickson 808: invoked.</p>
1.105 ihickson 809:
810: </li>
811:
812: <li>
813:
1.153 ihickson 814: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain a new
815: object <var title="">y</var> by <span title="transfer a Transferable
816: object">transferring</span> the object <var title="">x</var> to <var title="">new owner</var>,
817: and replace the placeholder object that was created for the object <var title="">x</var> by
818: the new object <var title="">y</var> wherever the placeholder exists (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</p>
1.105 ihickson 819:
820: </li>
821:
1.106 ihickson 822: </ol></li>
823:
824: <li>
1.1 ihickson 825:
1.153 ihickson 826: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span>
827: array.</p>
1.84 ihickson 828:
829: </li>
830:
831: <li>
832:
1.35 ihickson 833: <p>Return from the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method, but
1.1 ihickson 834: asynchronously continue running these steps.</p>
835:
836: </li>
837:
838: <li>
839:
1.154 ihickson 840:
1.153 ihickson 841: <p>If the <var title="">targetOrigin</var> argument is a single literal U+002F SOLIDUS character
842: (/), and the <code>Document</code> of the <code>Window</code> object on which the method was
1.156 ihickson 843: invoked does not have the <span>same origin</span> as the <span>responsible document</span> specified by the <span>entry settings
1.154 ihickson 844: object</span>, then abort these steps silently.</p>
1.153 ihickson 845:
846: <p>Otherwise, if the <var title="">targetOrigin</var> argument is an <span>absolute URL</span>,
847: and the <code>Document</code> of the <code>Window</code> object on which the method was invoked
848: does not have the <span>same origin</span> as <var title="">targetOrigin</var>, then abort these
849: steps silently.</p>
850:
851: <p>Otherwise, the <var title="">targetOrigin</var> argument is a single literal U+002A ASTERISK
852: character (*), and no origin check is made.</p>
1.1 ihickson 853:
854: </li>
855:
856: <li>
857:
1.154 ihickson 858:
1.124 ihickson 859: <p>Create a <span title="concept-events-trusted">trusted</span> event that uses the
860: <code><a href="#messageevent">MessageEvent</a></code> interface, with the event type <code title="event-message"><a href="#event-message">message</a></code>, which does not bubble, is not cancelable, and has no
861: default action. The <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute must be
862: initialized to the value of <var title="">message clone</var>, the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute must be initialized to the <span title="Unicode serialization of an origin">Unicode serialization</span> of the
1.156 ihickson 863: <span>origin</span> specified by the <span>incumbent settings object</span>, the <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code> attribute must be initialized to the
1.154 ihickson 864: <code>WindowProxy</code> object corresponding to the
865: <span>global object</span> (a <code>Window</code> object) specified by the
1.156 ihickson 866: <span>incumbent settings object</span>,
1.154 ihickson 867: and the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code> attribute must be initialized to the <var title="">new ports</var> array.
1.109 ihickson 868:
869: <a href="#refsHTML">[HTML]</a>
870:
1.148 ihickson 871: </p>
872:
1.113 ihickson 873:
1.1 ihickson 874: </li>
875:
876: <li>
877:
1.130 ihickson 878: <p><span>Queue a task</span> to <span title="concept-event-dispatch">dispatch</span> the event
879: created in the previous step at the <code>Window</code> object on which the method was invoked.
880: The <span>task source</span> for this <span title="concept-task">task</span> is the <a href="#posted-message-task-source">posted
881: message task source</a>.</p>
1.1 ihickson 882:
883: </li>
884:
1.114 ihickson 885: </ol></div>
886:
887:
888:
889:
890: <h2 id="channel-messaging"><span class="secno">5 </span><dfn>Channel messaging</dfn></h2>
891:
892: <h3 id="introduction-0"><span class="secno">5.1 </span>Introduction</h3>
893:
894: <p><i>This section is non-normative.</i></p>
895:
1.153 ihickson 896: <p>To enable independent pieces of code (e.g. running in different <span title="browsing
897: context">browsing contexts</span>) to communicate directly, authors can use <a href="#channel-messaging">channel
1.114 ihickson 898: messaging</a>.</p>
899:
1.153 ihickson 900: <p>Communication channels in this mechanism are implemented as two-ways pipes, with a port at each
901: end. Messages sent in one port are delivered at the other port, and vice-versa. Messages are
1.114 ihickson 902: asynchronous, and delivered as DOM events.</p>
903:
1.153 ihickson 904: <p>To create a connection (two "entangled" ports), the <code title="">MessageChannel()</code>
905: constructor is called:</p>
1.114 ihickson 906:
907: <pre>var channel = new MessageChannel();</pre>
908:
1.153 ihickson 909: <p>One of the ports is kept as the local port, and the other port is sent to the remote code, e.g.
910: using <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code>:</p>
1.114 ihickson 911:
912: <pre>otherWindow.postMessage('hello', 'http://example.com', [channel.port2]);</pre>
913:
914: <p>To send messages, the <code title="dom-MessagePort-postMessage"><a href="#dom-messageport-postmessage">postMessage()</a></code> method on
915: the port is used:</p>
916:
917: <pre>channel.port1.postMessage('hello');</pre>
918:
919: <p>To receive messages, one listens to <code title="event-message"><a href="#event-message">message</a></code> events:</p>
920:
921: <pre>channel.port1.onmessage = handleMessage;
1.1 ihickson 922: function handleMessage(event) {
923: // message is in event.data
924: // ...
1.114 ihickson 925: }</pre>
926:
1.153 ihickson 927: <p>Data sent on a port can be structured data; for example here an array of strings is passed on a
928: <code><a href="#messageport">MessagePort</a></code>:</p>
1.114 ihickson 929:
1.140 ihickson 930: <pre>port1.postMessage(['hello', 'world']);</pre>
1.114 ihickson 931:
932:
1.121 ihickson 933: <h4 id="examples"><span class="secno">5.1.1 </span>Examples</h4>
934:
935: <p><i>This section is non-normative.</i></p>
936:
937: <div class="example">
938:
1.153 ihickson 939: <p>In this example, two JavaScript libraries are connected to each other using
940: <code><a href="#messageport">MessagePort</a></code>s. This allows the libraries to later be hosted in different frames, or
941: in <code>Worker</code> objects, without any change to the APIs.</p>
1.121 ihickson 942:
943: <pre><script src="contacts.js"></script> <!-- exposes a contacts object -->
944: <script src="compose-mail.js"></script> <!-- exposes a composer object -->
945: <script>
946: var channel = new MessageChannel();
947: composer.addContactsProvider(channel.port1);
948: contacts.registerConsumer(channel.port2);
949: </script></pre>
950:
1.153 ihickson 951: <p>Here's what the "addContactsProvider()" function's implementation could look like:</p>
1.121 ihickson 952:
953: <pre>function addContactsProvider(port) {
954: port.onmessage = function (event) {
955: switch (event.data.messageType) {
956: 'search-result': handleSearchResult(event.data.results); break;
957: 'search-done': handleSearchDone(); break;
958: 'search-error': handleSearchError(event.data.message); break;
959: // ...
960: }
961: };
962: };</pre>
963:
964: <p>Alternatively, it could be implemented as follows:</p>
965:
966: <pre>function addContactsProvider(port) {
967: port.addEventListener('message', function (event) {
968: if (event.data.messageType == 'search-result')
969: handleSearchResult(event.data.results);
970: });
971: port.addEventListener('message', function (event) {
972: if (event.data.messageType == 'search-done')
973: handleSearchDone();
974: });
975: port.addEventListener('message', function (event) {
976: if (event.data.messageType == 'search-error')
977: handleSearchError(event.data.message);
978: });
979: // ...
980: port.start();
981: };</pre>
982:
1.153 ihickson 983: <p>The key difference is that when using <code title="dom-EventTarget-addEventListener">addEventListener()</code>, the <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method must also be invoked. When using <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code>, the call to <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> is implied.</p>
984:
985: <p>The <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method, whether called explicitly or
986: implicitly (by setting <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code>), starts the
987: flow of messages: messages posted on message ports are initially paused, so that they don't get
988: dropped on the floor before the script has had a chance to set up its handlers.</p>
1.121 ihickson 989:
990: </div>
991:
992:
993: <h4 id="ports-as-the-basis-of-an-object-capability-model-on-the-web"><span class="secno">5.1.2 </span>Ports as the basis of an object-capability model on the Web</h4>
1.114 ihickson 994:
995: <p><i>This section is non-normative.</i></p>
996:
1.153 ihickson 997: <p>Ports can be viewed as a way to expose limited capabilities (in the object-capability model
998: sense) to other actors in the system. This can either be a weak capability system, where the ports
999: are merely used as a convenient model within a particular origin, or as a strong capability model,
1000: where they are provided by one origin <var title="">provider</var> as the only mechanism by which
1001: another origin <var title="">consumer</var> can effect change in or obtain information from <var title="">provider</var>.</p>
1002:
1003: <p>For example, consider a situation in which a social Web site embeds in one <code>iframe</code>
1004: the user's e-mail contacts provider (an address book site, from a second origin), and in a second
1005: <code>iframe</code> a game (from a third origin). The outer social site and the game in the second
1006: <code>iframe</code> cannot access anything inside the first <code>iframe</code>; together they can
1007: only:</p>
1008:
1009: <ul class="brief"><li><span>Navigate</span> the <code>iframe</code> to a new <span>URL</span>, such as the same
1010: <span>URL</span> but with a different fragment identifier, causing the <code>Window</code> in the
1011: <code>iframe</code> to receive a <code title="event-hashchange">hashchange</code> event.</li>
1.100 ihickson 1012:
1.153 ihickson 1013: <li>Resize the <code>iframe</code>, causing the <code>Window</code> in the <code>iframe</code> to
1014: receive a <code title="event-resize">resize</code> event.</li>
1.100 ihickson 1015:
1016:
1017:
1.153 ihickson 1018: <li>Send a <code title="event-message"><a href="#event-message">message</a></code> event to the <code>Window</code> in the
1019: <code>iframe</code> using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">window.postMessage()</a></code>
1.100 ihickson 1020: API.</li>
1021:
1.153 ihickson 1022: </ul><p>The contacts provider can use these methods, most particularly the third one, to provide an API
1023: that can be accessed by other origins to manipulate the user's address book. For example, it could
1.100 ihickson 1024: respond to a message "<code title="">add-contact Guillaume Tell
1.153 ihickson 1025: <tell@pomme.example.net></code>" by adding the given person and e-mail address to the user's
1026: address book.</p>
1027:
1028: <p>To avoid any site on the Web being able to manipulate the user's contacts, the contacts
1029: provider might only allow certain trusted sites, such as the social site, to do this.</p>
1.114 ihickson 1030:
1.153 ihickson 1031: <p>Now suppose the game wanted to add a contact to the user's address book, and that the social
1032: site was willing to allow it to do so on its behalf, essentially "sharing" the trust that the
1033: contacts provider had with the social site. There are several ways it could do this; most simply,
1034: it could just proxy messages between the game site and the contacts site. However, this solution
1035: has a number of difficulties: it requires the social site to either completely trust the game site
1036: not to abuse the privilege, or it requires that the social site verify each request to make sure
1037: it's not a request that it doesn't want to allow (such as adding multiple contacts, reading the
1038: contacts, or deleting them); it also requires some additional complexity if there's ever the
1039: possibility of multiple games simultaneously trying to interact with the contacts provider.</p>
1040:
1041: <p>Using message channels and <code><a href="#messageport">MessagePort</a></code> objects, however, all of these problems can
1042: go away. When the game tells the social site that it wants to add a contact, the social site can
1043: ask the contacts provider not for it to add a contact, but for the <em>capability</em> to add a
1044: single contact. The contacts provider then creates a pair of <code><a href="#messageport">MessagePort</a></code> objects, and
1045: sends one of them back to the social site, who forwards it on to the game. The game and the
1046: contacts provider then have a direct connection, and the contacts provider knows to only honor a
1047: single "add contact" request, nothing else. In other words, the game has been granted the
1.114 ihickson 1048: capability to add a single contact.</p>
1049:
1050:
1.121 ihickson 1051: <h4 id="ports-as-the-basis-of-abstracting-out-service-implementations"><span class="secno">5.1.3 </span>Ports as the basis of abstracting out service implementations</h4>
1.114 ihickson 1052:
1053: <p><i>This section is non-normative.</i></p>
1054:
1.153 ihickson 1055: <p>Continuing the example from the previous section, consider the contacts provider in particular.
1056: While an initial implementation might have simply used <code>XMLHttpRequest</code> objects in the
1057: service's <code>iframe</code>, an evolution of the service might instead want to use a <span title="SharedWorker">shared worker</span> with a single <code>WebSocket</code> connection.</p>
1058:
1059: <p>If the initial design used <code><a href="#messageport">MessagePort</a></code> objects to grant capabilities, or even just
1060: to allow multiple simultaneous independent sessions, the service implementation can switch from
1061: the <code>XMLHttpRequest</code>s-in-each-<code>iframe</code> model to the
1062: shared-<code>WebSocket</code> model without changing the API at all: the ports on the service
1063: provider side can all be forwarded to the shared worker without it affecting the users of the API
1064: in the slightest.</p>
1.114 ihickson 1065:
1066:
1067:
1068: <h3 id="message-channels"><span class="secno">5.2 </span>Message channels</h3>
1069:
1070: <pre class="idl">[<a href="#dom-messagechannel" title="dom-MessageChannel">Constructor</a>]
1.1 ihickson 1071: interface <dfn id="messagechannel">MessageChannel</dfn> {
1072: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port1" title="dom-channel-port1">port1</a>;
1073: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port2" title="dom-channel-port2">port2</a>;
1.114 ihickson 1074: };</pre>
1075:
1076: <dl class="domintro"><dt><var title="">channel</var> = new <code title="dom-MessageChannel"><a href="#dom-messagechannel">MessageChannel</a></code>()</dt>
1.1 ihickson 1077:
1078: <dd>
1079:
1080: <p>Returns a new <code><a href="#messagechannel">MessageChannel</a></code> object with two new <code><a href="#messageport">MessagePort</a></code> objects.</p>
1081:
1082: </dd>
1083:
1084: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port1">port1</code></dt>
1085:
1086: <dd>
1087:
1088: <p>Returns the first <code><a href="#messageport">MessagePort</a></code> object.</p>
1089:
1090: </dd>
1091:
1092: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port2">port2</code></dt>
1093:
1094: <dd>
1095:
1096: <p>Returns the second <code><a href="#messageport">MessagePort</a></code> object.</p>
1097:
1098: </dd>
1099:
1100: </dl><div class="impl">
1101:
1.153 ihickson 1102: <p>When the <dfn id="dom-messagechannel" title="dom-MessageChannel"><code>MessageChannel()</code></dfn> constructor is
1103: called, it must run the following algorithm:</p>
1.1 ihickson 1104:
1.154 ihickson 1105: <ol><li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a> whose <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1.156 ihickson 1106: is the <span>incumbent settings object</span>, and let <var title="">port1</var> be that object.</li>
1.154 ihickson 1107:
1.1 ihickson 1108:
1.154 ihickson 1109: <li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a> whose <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1.156 ihickson 1110: is the <span>incumbent settings object</span>, and let <var title="">port2</var> be that object.</li>
1.1 ihickson 1111:
1.153 ihickson 1112: <li><p><a href="#entangle">Entangle</a> the <var title="">port1</var> and <var title="">port2</var>
1113: objects.</li>
1.1 ihickson 1114:
1.153 ihickson 1115: <li><p>Instantiate a new <code><a href="#messagechannel">MessageChannel</a></code> object, and let <var title="">channel</var>
1116: be that object.</li>
1.1 ihickson 1117:
1.153 ihickson 1118: <li><p>Let the <code title="dom-channel-port1"><a href="#dom-channel-port1">port1</a></code> attribute of the <var title="">channel</var> object be <var title="">port1</var>.</p>
1.1 ihickson 1119:
1.153 ihickson 1120: <li><p>Let the <code title="dom-channel-port2"><a href="#dom-channel-port2">port2</a></code> attribute of the <var title="">channel</var> object be <var title="">port2</var>.</p>
1.1 ihickson 1121:
1122: <li><p>Return <var title="">channel</var>.</li>
1123:
1.153 ihickson 1124: </ol><p>The <dfn id="dom-channel-port1" title="dom-channel-port1"><code>port1</code></dfn> and <dfn id="dom-channel-port2" title="dom-channel-port2"><code>port2</code></dfn> attributes must return the values they were
1125: assigned when the <code><a href="#messagechannel">MessageChannel</a></code> object was created.</p>
1.1 ihickson 1126:
1.114 ihickson 1127: </div>
1128:
1129:
1130:
1131: <h3 id="message-ports"><span class="secno">5.3 </span>Message ports</h3>
1132:
1.153 ihickson 1133: <p>Each channel has two message ports. Data sent through one port is received by the other port,
1134: and vice versa.</p>
1.114 ihickson 1135:
1136: <pre class="idl">interface <dfn id="messageport">MessagePort</dfn> : <span>EventTarget</span> {
1.113 ihickson 1137: void <a href="#dom-messageport-postmessage" title="dom-MessagePort-postMessage">postMessage</a>(any message, optional sequence<<span>Transferable</span>> transfer);
1138: void <a href="#dom-messageport-start" title="dom-MessagePort-start">start</a>();
1.1 ihickson 1139: void <a href="#dom-messageport-close" title="dom-MessagePort-close">close</a>();
1140:
1141: // event handlers
1.120 ihickson 1142: attribute <span>EventHandler</span> <a href="#handler-messageport-onmessage" title="handler-MessagePort-onmessage">onmessage</a>;
1.1 ihickson 1143: };
1.146 ihickson 1144: // <a href="#messageport">MessagePort</a> implements <span>Transferable</span>;</pre>
1.114 ihickson 1145:
1146: <dl class="domintro"><dt><var title="">port</var> . <code title="dom-MessagePort-postMessage"><a href="#dom-messageport-postmessage">postMessage</a></code>(<var title="">message</var> [, <var title="">transfer</var>] )</dt>
1.1 ihickson 1147:
1148: <dd>
1149:
1.153 ihickson 1150: <p>Posts a message through the channel. Objects listed in <var title="">transfer</var> are
1151: transferred, not just cloned, meaning that they are no longer usable on the sending side.</p>
1.1 ihickson 1152:
1.138 ihickson 1153: <p>Throws a <code>DataCloneError</code> exception if <var title="">transfer</var> array contains
1154: duplicate objects or the source or target ports, or if <var title="">message</var> could not be
1155: cloned.</p>
1.1 ihickson 1156:
1157: </dd>
1158:
1159: <dt><var title="">port</var> . <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start</a></code>()</dt>
1160:
1161: <dd>
1162:
1163: <p>Begins dispatching messages received on the port.</p>
1164:
1165: </dd>
1166:
1167: <dt><var title="">port</var> . <code title="dom-MessagePort-close"><a href="#dom-messageport-close">close</a></code>()</dt>
1168:
1169: <dd>
1170:
1171: <p>Disconnects the port, so that it is no longer active.</p>
1172:
1173: </dd>
1174:
1175: </dl><div class="impl">
1176:
1.137 ihickson 1177: <p>Each <code><a href="#messageport">MessagePort</a></code> object can be entangled with another (a symmetric relationship).
1178: Each <code><a href="#messageport">MessagePort</a></code> object also has a <span>task source</span> called the <dfn id="port-message-queue">port
1179: message queue</dfn>, initially empty. A <a href="#port-message-queue">port message queue</a> can be enabled or
1180: disabled, and is initially disabled. Once enabled, a port can never be disabled again (though
1181: messages in the queue can get moved to another queue or removed altogether, which has much the
1.154 ihickson 1182: same effect). A <code><a href="#messageport">MessagePort</a></code> also has a <dfn id="has-been-shipped">has been shipped</dfn> flag, which must
1183: initially be false, and an <dfn id="concept-port-owner" title="concept-port-owner">owner</dfn>, which is a <span>settings
1184: object</span> set when the object is created, as described below.</p>
1185:
1.134 ihickson 1186:
1.151 ihickson 1187: <p>When a port's <a href="#port-message-queue">port message queue</a> is enabled, the <span>event loop</span> must use
1.154 ihickson 1188: it as one of its <span title="task source">task sources</span>. All <span title="concept-task">tasks</span> <span title="queue a task">queued</span> on the <a href="#port-message-queue">port
1189: message queue</a> must be associated with the <span>responsible document</span> specified by
1190: the port's <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</p>
1191:
1.151 ihickson 1192:
1.154 ihickson 1193: <p class="note">If the port's <a href="#concept-port-owner" title="concept-port-owner">owner</a> specifies a <span>responsible document</span> that is <span>fully active</span>,
1194: but the event listeners all have scripts whose <span title="settings object">settings objects</span>
1195: specify <span title="responsible document">responsible documents</span> that are <em>not</em> <span>fully active</span>, then the messages will be
1.151 ihickson 1196: lost.</p>
1197:
1.154 ihickson 1198:
1.134 ihickson 1199: <p>Each <span>event loop</span> has a <span>task source</span> called the <dfn id="unshipped-port-message-queue">unshipped port
1200: message queue</dfn>. This is a virtual <span>task source</span>: it must act as if it contained
1201: the <span title="concept-task">tasks</span> of each <a href="#port-message-queue">port message queue</a> of each
1.154 ihickson 1202: <code><a href="#messageport">MessagePort</a></code> whose <a href="#has-been-shipped">has been shipped</a> flag is false, whose <a href="#port-message-queue">port
1203: message queue</a> is enabled, and whose <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1204: specifies that <span>event loop</span> as the <span>responsible event loop</span>,
1205: in the order in which they were added to their respective
1.151 ihickson 1206: <span>task source</span>. When a <span title="concept-task">task</span> would be removed from the
1207: <a href="#unshipped-port-message-queue">unshipped port message queue</a>, it must instead be removed from its <a href="#port-message-queue">port message
1208: queue</a>.</p>
1.134 ihickson 1209:
1210: <p>When a <code><a href="#messageport">MessagePort</a></code>'s <a href="#has-been-shipped">has been shipped</a> flag is false, its <a href="#port-message-queue">port
1211: message queue</a> must be ignored for the purposes of the <span>event loop</span>. (The
1212: <a href="#unshipped-port-message-queue">unshipped port message queue</a> is used instead.)</p>
1213:
1214: <p class="note">The <a href="#has-been-shipped">has been shipped</a> flag is set to true when a port, its twin, or
1215: the object it was cloned from, is or has been <span title="transfer a transferable
1216: object">transferred</span>. When a <code><a href="#messageport">MessagePort</a></code>'s <a href="#has-been-shipped">has been shipped</a> flag
1217: is true, its <a href="#port-message-queue">port message queue</a> acts as a first-class <span>task source</span>,
1218: unaffected to any <a href="#unshipped-port-message-queue">unshipped port message queue</a>.</p>
1.1 ihickson 1219:
1.154 ihickson 1220:
1221: <p>When the user agent is to <dfn id="create-a-new-messageport-object">create a new <code>MessagePort</code> object</dfn> with a particular
1222: <span>settings object</span> as its <var title="">owner</var>, it must instantiate a new
1223: <code><a href="#messageport">MessagePort</a></code> object, and let its <a href="#concept-port-owner" title="concept-port-owner">owner</a> be <var title="">owner</var>.</p>
1.137 ihickson 1224:
1225: <p>When the user agent is to <dfn id="entangle">entangle</dfn> two <code><a href="#messageport">MessagePort</a></code> objects, it must run
1226: the following steps:</p>
1.1 ihickson 1227:
1228: <ol><li>
1229:
1.153 ihickson 1230: <p>If one of the ports is already entangled, then disentangle it and the port that it was
1231: entangled with.</p>
1.1 ihickson 1232:
1.153 ihickson 1233: <p class="note">If those two previously entangled ports were the two ports of a
1234: <code><a href="#messagechannel">MessageChannel</a></code> object, then that <code><a href="#messagechannel">MessageChannel</a></code> object no longer
1235: represents an actual channel: the two ports in that object are no longer entangled.</p>
1.1 ihickson 1236:
1237: </li>
1238:
1.143 ihickson 1239: <li>
1240:
1241: <p>Associate the two ports to be entangled, so that they form the two parts of a new channel.
1242: (There is no <code><a href="#messagechannel">MessageChannel</a></code> object that represents this channel.)</p>
1243:
1.144 ihickson 1244: <p>Two ports <var title="">A</var> and <var title="">B</var> that have gone through this step
1245: are now said to be entangled; one is entangled to the other, and vice versa.</p>
1.143 ihickson 1246:
1247: <p class="note">While this specification describes this process as instantaneous,
1248: implementations are more likely to implement it via message passing. As with all algorithms, the
1249: key is "merely" that the end result be indistinguishable, in a black-box sense, from the
1250: specification.</p>
1251:
1252: </li>
1.1 ihickson 1253:
1.153 ihickson 1254: </ol><p>When the user agent is to <dfn id="clone-a-port">clone a port</dfn> <var title="">original port</var>, with the
1255: clone being owned by <var title="">owner</var>, it must run the following steps, which return a
1256: new <code><a href="#messageport">MessagePort</a></code> object. These steps must be run atomically.</p>
1.1 ihickson 1257:
1.134 ihickson 1258: <ol><li><p>Set <var title="">original port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1259: true.</li>
1260:
1.154 ihickson 1261: <li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a> whose <a href="#concept-port-owner" title="concept-port-owner">owner</a> is <var title="">owner</var>, and let <var title="">new port</var> be that object.</li>
1.1 ihickson 1262:
1.134 ihickson 1263: <li><p>Set <var title="">new port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to true.</li>
1264:
1.153 ihickson 1265: <li><p>Move all the events in the <a href="#port-message-queue">port message queue</a> of <var title="">original
1266: port</var> to the <a href="#port-message-queue">port message queue</a> of <var title="">new port</var>, if any,
1267: leaving the <var title="">new port</var>'s <a href="#port-message-queue">port message queue</a> in its initial
1268: disabled state.</li>
1.1 ihickson 1269:
1270: <li>
1271:
1.153 ihickson 1272: <p>If the <var title="">original port</var> is entangled with another port, then run these
1273: substeps:</p>
1.1 ihickson 1274:
1.153 ihickson 1275: <ol><li><p>Let the <var title="">remote port</var> be the port with which the <var title="">original port</var> is entangled.</li>
1.1 ihickson 1276:
1.134 ihickson 1277: <li><p>Set <var title="">remote port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1278: true.</li>
1279:
1.153 ihickson 1280: <li><p><a href="#entangle">Entangle</a> the <var title="">remote port</var> and <var title="">new
1281: port</var> objects. The <var title="">original port</var> object will be disentangled by this
1.1 ihickson 1282: process.</li>
1283:
1284: </ol></li>
1285:
1.153 ihickson 1286: <li><p>Return <var title="">new port</var>. It is the clone.</li>
1.1 ihickson 1287:
1.153 ihickson 1288: </ol><p id="transferMessagePort">To <span title="transfer a Transferable object">transfer</span> a
1289: <code><a href="#messageport">MessagePort</a></code> object <var title="">old</var> to a new owner <var title="">owner</var>,
1290: a user agent must <a href="#clone-a-port" title="clone a port">clone</a> the <var title="">old</var> object with
1291: the clone being owned by <var title="">owner</var>, thus obtaining <var title="">new</var>, must
1292: <span title="concept-Transferable-neutered">neuter</span> the <var title="">old</var> port, and
1293: must finally return <var title="">new</var>.</p>
1294:
1295: <hr><p>The <dfn id="dom-messageport-postmessage" title="dom-MessagePort-postMessage"><code>postMessage()</code></dfn> method, when
1296: called on a port <var title="">source port</var>, must cause the user agent to run the following
1297: steps:</p>
1.1 ihickson 1298:
1.153 ihickson 1299: <ol><li><p>Let <var title="">target port</var> be the port with which <var title="">source port</var>
1300: is entangled, if any.</li>
1.1 ihickson 1301:
1.88 ihickson 1302: <li>
1303:
1304: <p>Let <var title="">new ports</var> be an empty array.</p>
1305:
1306: </li>
1307:
1308: <li>
1.1 ihickson 1309:
1.153 ihickson 1310: <p>Let <var title="">transfer map</var> be an empty association list of
1311: <code>Transferable</code> objects to placeholder objects.</p>
1.1 ihickson 1312:
1.88 ihickson 1313: </li>
1.1 ihickson 1314:
1.88 ihickson 1315: <li>
1.1 ihickson 1316:
1.153 ihickson 1317: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these
1318: substeps:</p>
1.1 ihickson 1319:
1320: <ol><li>
1321:
1.153 ihickson 1322: <p>If any object is listed in <var title="">transfer</var> more than once, or any of the
1323: <code>Transferable</code> objects listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then throw a
1324: <code>DataCloneError</code> exception and abort these steps.</p>
1.1 ihickson 1325:
1.88 ihickson 1326: </li>
1.1 ihickson 1327:
1.88 ihickson 1328: <li>
1329:
1.153 ihickson 1330: <p>If any of the objects in <var title="">transfer</var> are either the <var title="">source
1331: port</var> or the <var title="">target port</var> (if any), then throw a
1332: <code>DataCloneError</code> exception and abort these steps.</p>
1.88 ihickson 1333:
1.89 ihickson 1334: </li>
1.1 ihickson 1335:
1.84 ihickson 1336: <li>
1337:
1.153 ihickson 1338: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a
1339: mapping from <var title="">x</var> to a new unique placeholder object created for <var title="">x</var> to <var title="">transfer map</var>, and if <var title="">x</var> is a
1340: <code><a href="#messageport">MessagePort</a></code> object, also append the placeholder object to the <var title="">new
1.105 ihickson 1341: ports</var> array.</p>
1.84 ihickson 1342:
1343: </li>
1344:
1.89 ihickson 1345: </ol></li>
1346:
1347: <li>
1.1 ihickson 1348:
1.153 ihickson 1349: <p>Let <var title="">message clone</var> be the result of obtaining a <span>structured
1350: clone</span> of the <var title="">message</var> argument, with <var title="">transfer map</var>
1351: as the <i>transfer map</i>. If this throws an exception, then throw that exception and abort
1352: these steps.</p>
1.88 ihickson 1353:
1354: </li>
1355:
1.105 ihickson 1356: <li>
1357:
1.153 ihickson 1358: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these
1359: substeps:</p>
1.105 ihickson 1360:
1361: <ol><li>
1362:
1.154 ihickson 1363:
1364: <p>Let <var title="">new owner</var> be the <a href="#concept-port-owner" title="concept-port-owner">owner</a> of <var title="">target port</var>, if there
1.153 ihickson 1365: is a <var title="">target port</var>, or else some arbitrary owner. (This <var title="">new
1366: owner</var> is used when transferring objects below. If there is no <var title="">target
1367: port</var>, the <code>Transferable</code> objects given in the second argument, if any, are
1368: still <span title="transfer a Transferable object">transferred</span>, but since they are then
1369: discarded, it doesn't matter where they are transferred to.)</p>
1.105 ihickson 1370:
1371: </li>
1372:
1373:
1374: <li>
1375:
1.153 ihickson 1376: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain a new
1377: object <var title="">y</var> by <span title="transfer a Transferable
1378: object">transferring</span> the object <var title="">x</var> to <var title="">new owner</var>,
1379: and replace the placeholder object that was created for the object <var title="">x</var> by
1380: the new object <var title="">y</var> wherever the placeholder exists (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</p>
1.105 ihickson 1381:
1382: </li>
1383:
1384: </ol></li>
1.88 ihickson 1385:
1386: <li>
1387:
1.153 ihickson 1388: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span>
1389: array.</p>
1.88 ihickson 1390:
1391: </li>
1392:
1.153 ihickson 1393: <li><p>If there is no <var title="">target port</var> (i.e. if <var title="">source port</var> is
1394: not entangled), then abort these steps.</li>
1.113 ihickson 1395:
1.153 ihickson 1396: <li><p>Create an event that uses the <code><a href="#messageevent">MessageEvent</a></code> interface, with the name <code title="event-message"><a href="#event-message">message</a></code>, which does not bubble, is not cancelable, and has no
1397: default action.
1.109 ihickson 1398:
1399: <a href="#refsHTML">[HTML]</a>
1400:
1401: </li>
1.88 ihickson 1402:
1.153 ihickson 1403: <li><p>Let the <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute of the event be
1404: initialized to the value of <var title="">message clone</var>.</li>
1.88 ihickson 1405:
1.153 ihickson 1406: <li><p>Let the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code> attribute of the event be
1407: initialized to the <var title="">new ports</var> array.</li>
1.1 ihickson 1408:
1.153 ihickson 1409: <li><p>Add the event to the <a href="#port-message-queue">port message queue</a> of <var title="">target
1410: port</var>.</li>
1.1 ihickson 1411:
1.137 ihickson 1412: </ol><hr><p>The <dfn id="dom-messageport-start" title="dom-MessagePort-start"><code>start()</code></dfn> method must enable its port's
1413: <a href="#port-message-queue">port message queue</a>, if it is not already enabled.</p>
1414:
1415: <hr><p>The <dfn id="dom-messageport-close" title="dom-MessagePort-close"><code>close()</code></dfn> method, when called on a port
1.139 ihickson 1416: <var title="">local port</var> that is entangled with another port, must cause the user agent to
1.137 ihickson 1417: disentangle the two ports. If the method is called on a port that is not entangled, then the
1418: method must do nothing.</p>
1419:
1420: <hr><p>The following are the <span>event handlers</span> (and their corresponding <span title="event
1.153 ihickson 1421: handler event type">event handler event types</span>) that must be supported, as <span>event
1422: handler IDL attributes</span>, by all objects implementing the <code><a href="#messageport">MessagePort</a></code>
1423: interface:</p>
1.1 ihickson 1424:
1425: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1426: <tbody><tr><td><dfn id="handler-messageport-onmessage" title="handler-MessagePort-onmessage"><code>onmessage</code></dfn> <td> <code title="event-message"><a href="#event-message">message</a></code>
1.153 ihickson 1427: </table><p>The first time a <code><a href="#messageport">MessagePort</a></code> object's <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code> IDL attribute is set, the port's <a href="#port-message-queue">port
1428: message queue</a> must be enabled, as if the <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code>
1429: method had been called.</p>
1.1 ihickson 1430:
1.114 ihickson 1431: </div>
1432:
1433:
1.128 ihickson 1434: <h3 id="broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</h3>
1435:
1.152 ihickson 1436: <p class="critical">The API described in this section is controversial, as, in an attempt to solve
1437: an architectural memory leak, it instead exposes the details of Garbage Collection. This is a
1438: lose-lose scenario. A better solution is really needed here.</p>
1439:
1.128 ihickson 1440: <p>Broadcasting to many ports is in principle relatively simple: keep an array of
1441: <code><a href="#messageport">MessagePort</a></code> objects to send messages to, and iterate through the array to send a
1.129 ihickson 1442: message. However, this has one rather unfortunate effect: it prevents the ports from being garbage
1.128 ihickson 1443: collected, even if the other side has gone away.</p>
1444:
1445: <p>To avoid this problem, the <code><a href="#portcollection">PortCollection</a></code> object can be used. It acts as an opaque
1446: array of <code><a href="#messageport">MessagePort</a></code> objects, thus allowing the objects to be garbage collected when
1447: they stop being relevant, while still allowing scripts to iterate over the
1448: <code><a href="#messageport">MessagePort</a></code> objects.</p>
1449:
1450: <pre class="idl">[<a href="#dom-portcollection" title="dom-PortCollection">Constructor</a>] interface <dfn id="portcollection">PortCollection</dfn> {
1451: void <a href="#dom-portcollection-add" title="dom-PortCollection-add">add</a>(<a href="#messageport">MessagePort</a> port);
1452: void <a href="#dom-portcollection-remove" title="dom-PortCollection-remove">remove</a>(<a href="#messageport">MessagePort</a> port);
1453: void <a href="#dom-portcollection-clear" title="dom-PortCollection-clear">clear</a>();
1454: void <a href="#dom-portcollection-iterate" title="dom-PortCollection-iterate">iterate</a>(<a href="#portcollectioncallback">PortCollectionCallback</a> callback);
1455: };
1456:
1457: callback <dfn id="portcollectioncallback">PortCollectionCallback</dfn> = void (<a href="#messageport">MessagePort</a> port);</pre>
1458:
1459: <dl class="domintro"><dt><var title="">portCollection</var> = new <code title="dom-PortCollection"><a href="#dom-portcollection">PortCollection</a></code>()</dt>
1460:
1461: <dd>
1462:
1463: <p>Returns a new empty <code><a href="#portcollection">PortCollection</a></code> object.</p>
1464:
1465: </dd>
1466:
1467: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-add"><a href="#dom-portcollection-add">add</a></code>(<var title="">port</var>)</dt>
1468:
1469: <dd>
1470:
1471: <p>Adds <var title="">port</var> to the collection, if it isn't already present.</p>
1472:
1473: </dd>
1474:
1475: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-remove"><a href="#dom-portcollection-remove">remove</a></code>(<var title="">port</var>)</dt>
1476:
1477: <dd>
1478:
1479: <p>Removes <var title="">port</var> from the collection, if it is present.</p>
1480:
1481: </dd>
1482:
1483: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-clear"><a href="#dom-portcollection-clear">clear</a></code>()</dt>
1484:
1485: <dd>
1486:
1487: <p>Removes all ports from the collection.</p>
1488:
1489: </dd>
1490:
1491: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-iterate"><a href="#dom-portcollection-iterate">iterate</a></code>(<var title="">callback</var>)</dt>
1492:
1493: <dd>
1494:
1495: <p>Calls <var title="">callback</var> for each port in the collection.</p>
1496:
1497: </dd>
1498:
1499: </dl><div class="impl">
1500:
1501: <p>A <code><a href="#portcollection">PortCollection</a></code> object has an initially empty <dfn id="concept-portcollection-list" title="concept-PortCollection-list">list of ports</dfn>. When a <code><a href="#messageport">MessagePort</a></code> object in
1502: a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is garbage collected, it must be
1503: silently removed from that <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>. Objects
1504: in a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> are ordered chronologically by
1505: the time at which they were most recently added; the least-recently added <code><a href="#messageport">MessagePort</a></code>
1506: object is the first in the list, and the most-recently added <code><a href="#messageport">MessagePort</a></code> is the last
1507: in the list.</p>
1508:
1509: <p>The <dfn id="dom-portcollection" title="dom-PortCollection"><code>PortCollection()</code></dfn> constructor must return
1510: a new <code><a href="#portcollection">PortCollection</a></code> object (with an empty <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>).</p>
1511:
1512: <p>The <dfn id="dom-portcollection-add" title="dom-PortCollection-add"><code>add()</code></dfn> method must add the
1513: <code><a href="#messageport">MessagePort</a></code> given by the argument to the <code><a href="#portcollection">PortCollection</a></code> object's <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, unless the <code><a href="#messageport">MessagePort</a></code> is
1514: already in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1515: method does nothing. (Calling this method with a port already in the list does not move the port
1516: to the end of the list.)</p>
1517:
1518: <p>The <dfn id="dom-portcollection-remove" title="dom-PortCollection-remove"><code>remove()</code></dfn> method must remove the
1519: <code><a href="#messageport">MessagePort</a></code> given by the argument from the <code><a href="#portcollection">PortCollection</a></code> object's <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, unless the <code><a href="#messageport">MessagePort</a></code> is
1520: not in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1521: method does nothing.</p>
1522:
1523: <p>The <dfn id="dom-portcollection-clear" title="dom-PortCollection-clear"><code>clear()</code></dfn> method must remove all
1524: <code><a href="#messageport">MessagePort</a></code> objects from the <code><a href="#portcollection">PortCollection</a></code> object's <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, returning it to the initial empty state.
1525: If the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is already empty, the method
1526: does nothing.</p>
1527:
1528: <p>The <dfn id="dom-portcollection-iterate" title="dom-PortCollection-iterate"><code>iterate()</code></dfn> method must invoke its
1529: <code><a href="#portcollectioncallback">PortCollectionCallback</a></code> argument once for each <code><a href="#messageport">MessagePort</a></code> object in the
1530: object's <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in the order defined
1531: above, with each invocation being passed the corresponding <code><a href="#messageport">MessagePort</a></code> object as the
1532: callback's sole argument.</p>
1533:
1534: </div>
1535:
1536:
1537: <h3 id="ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</h3>
1.114 ihickson 1538:
1539: <div class="impl">
1.1 ihickson 1540:
1.154 ihickson 1541:
1.153 ihickson 1542: <p>When a <code><a href="#messageport">MessagePort</a></code> object <var title="">o</var> is entangled, user agents must
1543: either act as if <var title="">o</var>'s entangled <code><a href="#messageport">MessagePort</a></code> object has a strong
1.154 ihickson 1544: reference to <var title="">o</var>, or as if the <span>global object</span> specified by <var title="">o</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a> has a strong reference
1.153 ihickson 1545: to <var title="">o</var>.</p>
1.1 ihickson 1546:
1547: <div class="note">
1548:
1.153 ihickson 1549: <p>Thus, a message port can be received, given an event listener, and then forgotten, and so long
1550: as that event listener could receive a message, the channel will be maintained.</p>
1551:
1552: <p>Of course, if this was to occur on both sides of the channel, then both ports could be garbage
1553: collected, since they would not be reachable from live code, despite having a strong reference to
1554: each other.</p>
1.1 ihickson 1555:
1556: </div>
1557:
1.153 ihickson 1558: <p>Furthermore, a <code><a href="#messageport">MessagePort</a></code> object must not be garbage collected while there exists
1559: a message in a <span>task queue</span> that is to be dispatched on that <code><a href="#messageport">MessagePort</a></code>
1560: object, or while the <code><a href="#messageport">MessagePort</a></code> object's <a href="#port-message-queue">port message queue</a> is open and
1561: there exists a <code title="event-message"><a href="#event-message">message</a></code> event in that queue.</p>
1.113 ihickson 1562:
1.79 ihickson 1563:
1.113 ihickson 1564:
1.128 ihickson 1565: <p>There are no strong references from a <code><a href="#portcollection">PortCollection</a></code> object to its
1566: <code><a href="#messageport">MessagePort</a></code> objects. (That is in fact the whole point of <code><a href="#portcollection">PortCollection</a></code>
1567: objects: they allow for <code><a href="#messageport">MessagePort</a></code> objects to be referenced without preventing them
1568: from being garbage collected.)</p>
1569:
1.114 ihickson 1570: </div>
1571:
1.128 ihickson 1572: <p class="note">Authors are strongly encouraged to explicitly close <code><a href="#messageport">MessagePort</a></code>
1573: objects to disentangle them, so that their resources can be recollected. Creating many
1574: <code><a href="#messageport">MessagePort</a></code> objects and discarding them without closing them can lead to high
1575: transient memory usage since garbage collection is not necessarily performed promptly.</p>
1.114 ihickson 1576:
1577:
1578: <h2 class="no-num" id="references">References</h2>
1579:
1580: <p>All references are normative unless marked "Non-normative".</p>
1581:
1582:
1583:
1.132 ihickson 1584: <dl><dt id="refsDOM">[DOM]</dt>
1585: <dd><cite><a href="http://dom.spec.whatwg.org/">DOM</a></cite>, A. van Kesteren, A. Gregor, Ms2ger. WHATWG.</dd>
1.72 ihickson 1586:
1587: <dt id="refsHTML">[HTML]</dt>
1.127 ihickson 1588: <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML</a></cite>, I. Hickson. WHATWG.</dd>
1.111 ihickson 1589:
1.72 ihickson 1590: <dt id="refsRFC2119">[RFC2119]</dt>
1.133 ihickson 1591: <dd><cite><a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></cite>, S. Bradner. IETF.</dd>
1.1 ihickson 1592:
1.55 ihickson 1593: <dt id="refsWEBIDL">[WEBIDL]</dt>
1.133 ihickson 1594: <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, C. McCormack. W3C.</dd>
1.1 ihickson 1595:
1.114 ihickson 1596: </dl><h2 class="no-num" id="acknowledgements">Acknowledgements</h2>
1597:
1598: <p>For a full list of acknowledgements, please see the HTML
1599: specification. <a href="#refsHTML">[HTML]</a></p>
1600:
1601:
Webmaster
![[BACK]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/back.gif?vpn-1){kind=icon}
Return to Overview.html CVS log ![[TXT]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/text.gif?vpn-1){kind=icon}
![[DIR]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/dir.gif?vpn-1){kind=icon}
Up to [Public] / html5 / postmsg