Annotation of html5/postmsg/Overview.html, revision 1.136
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.116 ihickson 195: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" 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.1 ihickson 215: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
1.48 ihickson 216:
1.10 ihickson 217: <h1>HTML5 Web Messaging</h1>
1.79 ihickson 218:
1.136 ! ihickson 219: <h2 class="no-num no-toc" id="editor-s-draft-5-february-2013">Editor's Draft 5 February 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.56 ihickson 223: <dd><a class="latest-link" href="http://dev.w3.org/html5/postmsg/">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.72 ihickson 278: <input name="id" type="hidden" value="top"><input name="component" type="hidden" value="Web Messaging (editor: Ian Hickson)"><input name="response" type="hidden" value="html"><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>
284: <p><textarea cols="79" id="feedbackBox" name="text" rows="10"></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.76 ihickson 306: <input onclick="return checkFeedbackForm(form)" type="submit" value="Submit feedback"><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.136 ! ihickson 351: This specification is the 5 February 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.67 abarsto 357: February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">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.1 ihickson 394: <li><a class="no-num" href="#references">References</a></li>
395: <li><a class="no-num" href="#acknowledgements">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
487: messaging</a>, and <a href="#channel-messaging">channel messaging</a> 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.118 ihickson 496: 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 497: readonly attribute <a href="#messageport">MessagePort</a>[]? <a href="#dom-messageevent-ports" title="dom-MessageEvent-ports">ports</a>;
498: };
499:
500: dictionary <dfn id="messageeventinit">MessageEventInit</dfn> : <span>EventInit</span> {
501: any data;
502: DOMString origin;
503: DOMString lastEventId;
504: <span>WindowProxy</span>? source;
505: <a href="#messageport">MessagePort</a>[]? ports;
1.114 ihickson 506: };</pre>
507:
508: <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 509:
510: <dd>
511:
512: <p>Returns the data of the message.</p>
513:
514: </dd>
515:
516: <dt><var title="">event</var> . <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code></dt>
517:
518: <dd>
519:
1.136 ! ihickson 520: <p>Returns the origin of the message, for <span>server-sent events</span> and
! 521: <a href="#web-messaging">cross-document messaging</a>.</p>
1.1 ihickson 522:
523: </dd>
524:
525: <dt><var title="">event</var> . <code title="dom-MessageEvent-lastEventId"><a href="#dom-messageevent-lasteventid">lastEventId</a></code></dt>
526:
527: <dd>
528:
1.136 ! ihickson 529: <p>Returns the <span title="concept-event-stream-last-event-id">last event ID string</span>, for
! 530: <span>server-sent events</span>.</p>
1.1 ihickson 531:
532: </dd>
533:
534: <dt><var title="">event</var> . <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code></dt>
535:
536: <dd>
537:
1.136 ! ihickson 538: <p>Returns the <code>WindowProxy</code> of the source window, for <a href="#web-messaging">cross-document
! 539: 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>
! 540: objects.</p>
1.1 ihickson 541:
542: </dd>
543:
544: <dt><var title="">event</var> . <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code></dt>
545:
546: <dd>
547:
1.136 ! ihickson 548: <p>Returns the <code><a href="#messageport">MessagePort</a></code> array sent with the message, for <a href="#web-messaging">cross-document
! 549: messaging</a> and <a href="#channel-messaging">channel messaging</a>.</p>
1.1 ihickson 550:
551: </dd>
552:
553: </dl><div class="impl">
554:
555: <p>The <dfn id="dom-messageevent-data" title="dom-MessageEvent-data"><code>data</code></dfn>
1.96 ihickson 556: attribute must return the value it was initialized to. When the
557: object is created, this attribute must be initialized to null. It
558: represents the message being sent.</p>
1.1 ihickson 559:
560: <p>The <dfn id="dom-messageevent-origin" title="dom-MessageEvent-origin"><code>origin</code></dfn> attribute
1.96 ihickson 561: must return the value it was initialized to. When the object is
562: created, this attribute must be initialized to the empty string. It
1.1 ihickson 563: represents, in <span>server-sent events</span> and
1.44 ihickson 564: <a href="#web-messaging">cross-document messaging</a>, the <span>origin</span> of
1.1 ihickson 565: the document that sent the message (typically the scheme, hostname,
566: and port of the document, but not its path or fragment
567: identifier).</p>
568:
569: <p>The <dfn id="dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId"><code>lastEventId</code></dfn>
1.96 ihickson 570: attribute must return the value it was initialized to. When the
571: object is created, this attribute must be initialized to the empty
572: string. It represents, in <span>server-sent events</span>, the <span title="concept-event-stream-last-event-id">last event ID
1.1 ihickson 573: string</span> of the event source.</p>
574:
575: <p>The <dfn id="dom-messageevent-source" title="dom-MessageEvent-source"><code>source</code></dfn> attribute
1.96 ihickson 576: must return the value it was initialized to. When the object is
577: created, this attribute must be initialized to null. It represents,
578: in <a href="#web-messaging">cross-document messaging</a>, the
1.1 ihickson 579: <code>WindowProxy</code> of the <span>browsing context</span> of the
1.118 ihickson 580: <code>Window</code> object from which the message came; and in the
581: <code title="event-connect">connect</code> events used by <span title="SharedWorkerGlobalScope">shared workers</span>, the newly
582: connecting <code><a href="#messageport">MessagePort</a></code>.</p>
1.1 ihickson 583:
584: <p>The <dfn id="dom-messageevent-ports" title="dom-MessageEvent-ports"><code>ports</code></dfn>
1.96 ihickson 585: attribute must return the value it was initialized to. When the
586: object is created, this attribute must be initialized to null.
587: It represents, in <a href="#web-messaging">cross-document messaging</a> and
1.84 ihickson 588: <a href="#channel-messaging">channel messaging</a> the <code><a href="#messageport">MessagePort</a></code> array
1.1 ihickson 589: being sent, if any.</p>
590:
1.114 ihickson 591: </div>
592:
593:
594: <h2 id="web-messaging"><span class="secno">4 </span><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h2>
595:
596: <p>Web browsers, for security and privacy reasons, prevent documents
1.1 ihickson 597: in different domains from affecting each other; that is, cross-site
1.114 ihickson 598: scripting is disallowed.</p>
599:
600: <p>While this is an important security feature, it prevents pages
1.1 ihickson 601: from different domains from communicating even when those pages are
602: not hostile. This section introduces a messaging system that allows
603: documents to communicate with each other regardless of their source
604: domain, in a way designed to not enable cross-site scripting
1.114 ihickson 605: attacks.</p>
606:
607: <div class="impl">
1.1 ihickson 608:
1.44 ihickson 609: <p>The <span>task source</span> for the <span title="concept-task">tasks</span> in <a href="#web-messaging">cross-document
1.1 ihickson 610: messaging</a> is the <dfn id="posted-message-task-source">posted message task source</dfn>.</p>
611:
1.114 ihickson 612: </div>
613:
614:
615: <h3 id="introduction"><span class="secno">4.1 </span>Introduction</h3>
616:
617: <p><i>This section is non-normative.</i></p>
618:
619: <div class="example">
1.1 ihickson 620:
621: <p>For example, if document A contains an <code>iframe</code>
622: element that contains document B, and script in document A calls
1.35 ihickson 623: <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> on the
1.1 ihickson 624: <code>Window</code> object of document B, then a message event will
625: be fired on that object, marked as originating from the
626: <code>Window</code> of document A. The script in document A might
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:
632: <p>To register an event handler for incoming events, the script
633: would use <code title="">addEventListener()</code> (or similar
634: mechanisms). For example, the script in document B might look
635: like:</p>
636:
637: <pre>window.addEventListener('message', receiver, false);
638: function receiver(e) {
639: if (e.origin == 'http://example.com') {
640: if (e.data == 'Hello world') {
641: e.source.postMessage('Hello', e.origin);
642: } else {
643: alert(e.data);
644: }
645: }
646: }</pre>
647:
648: <p>This script first checks the domain is the expected domain, and
649: then looks at the message, which it either displays to the user, or
650: responds to by sending a message back to the document which sent
651: the message in the first place.</p>
652:
1.114 ihickson 653: </div>
654:
655:
656:
657: <h3 id="security-postmsg"><span class="secno">4.2 </span>Security</h3>
658:
659: <div class="impl">
1.1 ihickson 660:
1.72 ihickson 661: <h4 id="authors"><span class="secno">4.2.1 </span>Authors</h4>
1.1 ihickson 662:
1.114 ihickson 663: </div>
664:
665: <p class="warning" id="security-4">Use of this API requires extra
1.28 ihickson 666: care to protect users from hostile entities abusing a site for their
1.114 ihickson 667: own purposes.</p>
668:
669: <p>Authors should check the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute to ensure
1.1 ihickson 670: that messages are only accepted from domains that they expect to
671: receive messages from. Otherwise, bugs in the author's message
1.114 ihickson 672: handling code could be exploited by hostile sites.</p>
673:
674: <p>Furthermore, even after checking the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute, authors
1.1 ihickson 675: should also check that the data in question is of the expected
676: format. Otherwise, if the source of the event has been attacked
677: using a cross-site scripting flaw, further unchecked processing of
1.35 ihickson 678: information sent using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method could
1.114 ihickson 679: result in the attack being propagated into the receiver.</p>
680:
681: <p>Authors should not use the wildcard keyword (*) in the <var title="">targetOrigin</var> argument in messages that contain any
1.1 ihickson 682: confidential information, as otherwise there is no way to guarantee
683: that the message is only delivered to the recipient to which it was
1.114 ihickson 684: intended.</p>
685:
686: <hr><p>Authors who accept messages from any origin are encouraged to
1.108 ihickson 687: consider the risks of a denial-of-service attack. An attacker could
688: send a high volume of messages; if the receiving page performs
689: expensive computation or causes network traffic to be sent for each
690: such message, the attacker's message could be multplied into a
691: denial-of-service attack. Authors are encouraged to employ rate
692: limiting (only accepting a certain number of messages per minute) to
1.114 ihickson 693: make such attacks impractical.</p>
694:
695:
696: <div class="impl">
1.1 ihickson 697:
1.72 ihickson 698: <h4 id="user-agents"><span class="secno">4.2.2 </span>User agents</h4>
1.1 ihickson 699:
700: <p>The integrity of this API is based on the inability for scripts
701: of one <span>origin</span> to post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in other
702: origins (those that are not the <span title="same
703: origin">same</span>).</p>
704:
705: <p class="note">Implementors are urged to take extra care in the
706: implementation of this feature. It allows authors to transmit
707: information from one domain to another domain, which is normally
708: disallowed for security reasons. It also requires that UAs be
709: careful to allow access to certain properties but not others.</p>
710:
1.108 ihickson 711: <hr><p>User agents are also encouraged to consider rate-limiting message
712: traffic between different <span title="origin">origins</span>, to
713: protect naïve sites from denial-of-service attacks.</p>
714:
1.114 ihickson 715: </div>
716:
717:
718:
719: <h3 id="posting-messages"><span class="secno">4.3 </span>Posting messages</h3>
720:
721: <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 722:
723: <dd>
724:
1.113 ihickson 725: <p>Posts a message to the given window. Messages can be structured
726: objects, e.g. nested objects and arrays, can contain JavaScript
727: values (strings, numbers, <code>Date</code>s, etc), and can
728: contain certain data objects such as <code>File</code>
729: <code>Blob</code>, <code>FileList</code>, and
730: <code>ArrayBuffer</code> objects.</p>
731:
732: <p>Objects listed in <var title="">transfer</var> are transferred,
733: not just cloned, meaning that they are no longer usable on the
734: sending side.</p>
1.1 ihickson 735:
736: <p>If the origin of the target window doesn't match the given
737: origin, the message is discarded, to avoid information leakage. To
738: send the message to the target regardless of origin, set the
1.11 ihickson 739: target origin to "<code title="">*</code>". To restrict the
740: message to same-origin targets only, without needing to explicitly
1.72 ihickson 741: state the origin, set the target origin to "<code title="">/</code>".</p>
1.1 ihickson 742:
1.98 ihickson 743: <p>Throws a <code>DataCloneError</code> if <var title="">transfer</var> array contains duplicate objects or if
1.88 ihickson 744: <var title="">message</var> could not be cloned.</p>
1.1 ihickson 745:
746: </dd>
747:
1.54 ihickson 748: </dl><p class="note">When posting a message to a <code>Window</code> of a
749: <span>browsing context</span> that has just been navigated to a new
750: <code>Document</code> is likely to result in the message not
751: receiving its intended recipient: the scripts in the target
752: <span>browsing context</span> have to have had time to set up
753: listeners for the messages. Thus, for instance, in situations where
754: a message is to be sent to the <code>Window</code> of newly created
755: child <code>iframe</code>, authors are advised to have the child
756: <code>Document</code> post a message to their parent announcing
757: their readiness to receive messages, and for the parent to wait for
1.114 ihickson 758: this message before beginning posting messages.</p>
759:
760: <div class="impl">
1.1 ihickson 761:
1.103 ihickson 762: <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
763: arguments) on a <code>Window</code> object, the user agent must
764: follow these steps:</p>
1.1 ihickson 765:
766: <ol><li>
767:
768: <p>If the value of the <var title="">targetOrigin</var> argument
1.72 ihickson 769: is neither a single U+002A ASTERISK character (*), a single U+002F
770: SOLIDUS character (/), nor an <span>absolute URL</span>, then
1.98 ihickson 771: throw a <code>SyntaxError</code> exception and abort the overall
1.72 ihickson 772: set of steps.</p>
1.1 ihickson 773:
774: </li>
775:
776: <li>
777:
1.88 ihickson 778: <p>Let <var title="">new ports</var> be an empty array.</p>
1.1 ihickson 779:
780: </li>
781:
782: <li>
783:
1.88 ihickson 784: <p>Let <var title="">transfer map</var> be an empty association
1.105 ihickson 785: list of <code>Transferable</code> objects to placeholder
786: objects.</p>
1.1 ihickson 787:
788: </li>
789:
790: <li>
791:
1.103 ihickson 792: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these substeps:</p>
1.88 ihickson 793:
794: <ol><li>
795:
796: <p>If any object is listed in <var title="">transfer</var> more
797: than once, or any of the <code>Transferable</code> objects
1.101 ihickson 798: listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then
799: throw a <code>DataCloneError</code> exception and abort these
800: steps.</p>
1.88 ihickson 801:
802: </li>
803:
804: <li>
805:
1.105 ihickson 806: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a mapping from <var title="">x</var> to a new unique placeholder object created for
807: <var title="">x</var> to <var title="">transfer map</var>, and
808: if <var title="">x</var> is a <code><a href="#messageport">MessagePort</a></code> object,
809: also append the placeholder object to the <var title="">new
810: ports</var> array.</p>
1.88 ihickson 811:
812: </li>
813:
814: </ol></li>
815:
816: <li>
1.1 ihickson 817:
1.105 ihickson 818: <p>Let <var title="">message clone</var> be the result of
819: obtaining a <span>structured clone</span> of the <var title="">message</var> argument, with <var title="">transfer
820: map</var> as the <i>transfer map</i>. If this throws an exception,
821: then throw that exception and abort these steps.</p>
1.1 ihickson 822:
823: </li>
824:
1.106 ihickson 825: <li>
826:
1.105 ihickson 827: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these substeps:</p>
828:
829: <ol><li>
830:
831: <p>Let <var title="">new owner</var> be the <code>Window</code>
832: object on which the method was invoked.</p>
833:
834: </li>
835:
836: <li>
837:
838: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain a new object <var title="">y</var> by <span title="transfer a Transferable
839: object">transferring</span> the object <var title="">x</var> to
840: <var title="">new owner</var>, and replace the placeholder
841: object that was created for the object <var title="">x</var> by
842: the new object <var title="">y</var> wherever the placeholder
843: exists (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</p>
844:
845: </li>
846:
1.106 ihickson 847: </ol></li>
848:
849: <li>
1.1 ihickson 850:
1.105 ihickson 851: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span> array.</p>
1.84 ihickson 852:
853: </li>
854:
855: <li>
856:
1.35 ihickson 857: <p>Return from the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method, but
1.1 ihickson 858: asynchronously continue running these steps.</p>
859:
860: </li>
861:
862: <li>
863:
1.72 ihickson 864: <p>If the <var title="">targetOrigin</var> argument is a single
865: literal U+002F SOLIDUS character (/), and the
866: <code>Document</code> of the <code>Window</code> object on which
867: the method was invoked does not have the <span>same origin</span>
868: as the <span>entry script</span>'s <span title="script's
869: document">document</span>, then abort these steps silently.</p>
870:
1.11 ihickson 871: <p>Otherwise, if the <var title="">targetOrigin</var> argument is
872: an <span>absolute URL</span>, and the <code>Document</code> of the
873: <code>Window</code> object on which the method was invoked does
874: not have the <span>same origin</span> as <var title="">targetOrigin</var>, then abort these steps silently.</p>
875:
876: <p>Otherwise, the <var title="">targetOrigin</var> argument is a
877: single literal U+002A ASTERISK character (*), and no origin check
878: is made.</p>
1.1 ihickson 879:
880: </li>
881:
882: <li>
883:
1.124 ihickson 884: <p>Create a <span title="concept-events-trusted">trusted</span> event that uses the
885: <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
886: default action. The <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute must be
887: 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
888: <span>origin</span> of the script that invoked the method, the <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code> attribute must be initialized to the
889: <span>script's global object</span>'s <code>WindowProxy</code> object, 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 890:
891: <a href="#refsHTML">[HTML]</a>
892:
893: </p>
1.113 ihickson 894:
1.1 ihickson 895: </li>
896:
897: <li>
898:
1.130 ihickson 899: <p><span>Queue a task</span> to <span title="concept-event-dispatch">dispatch</span> the event
900: created in the previous step at the <code>Window</code> object on which the method was invoked.
901: The <span>task source</span> for this <span title="concept-task">task</span> is the <a href="#posted-message-task-source">posted
902: message task source</a>.</p>
1.1 ihickson 903:
904: </li>
905:
1.114 ihickson 906: </ol></div>
907:
908:
909:
910:
911: <h2 id="channel-messaging"><span class="secno">5 </span><dfn>Channel messaging</dfn></h2>
912:
913: <h3 id="introduction-0"><span class="secno">5.1 </span>Introduction</h3>
914:
915: <p><i>This section is non-normative.</i></p>
916:
917: <p>To enable independent pieces of code (e.g. running in different
1.1 ihickson 918: <span title="browsing context">browsing contexts</span>) to
919: communicate directly, authors can use <a href="#channel-messaging">channel
1.114 ihickson 920: messaging</a>.</p>
921:
1.119 ihickson 922: <p>Communication channels in this mechanism are implemented as
1.1 ihickson 923: two-ways pipes, with a port at each end. Messages sent in one port
924: are delivered at the other port, and vice-versa. Messages are
1.114 ihickson 925: asynchronous, and delivered as DOM events.</p>
926:
927: <p>To create a connection (two "entangled" ports), the <code title="">MessageChannel()</code> constructor is called:</p>
928:
929: <pre>var channel = new MessageChannel();</pre>
930:
931: <p>One of the ports is kept as the local port, and the other port is
932: sent to the remote code, e.g. using <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code>:</p>
933:
934: <pre>otherWindow.postMessage('hello', 'http://example.com', [channel.port2]);</pre>
935:
936: <p>To send messages, the <code title="dom-MessagePort-postMessage"><a href="#dom-messageport-postmessage">postMessage()</a></code> method on
937: the port is used:</p>
938:
939: <pre>channel.port1.postMessage('hello');</pre>
940:
941: <p>To receive messages, one listens to <code title="event-message"><a href="#event-message">message</a></code> events:</p>
942:
943: <pre>channel.port1.onmessage = handleMessage;
1.1 ihickson 944: function handleMessage(event) {
945: // message is in event.data
946: // ...
1.114 ihickson 947: }</pre>
948:
949: <p>Data sent on a port can be structured data; for example here an
950: array of strings is passed:</p>
951:
952: <pre>port1.postMessage(['hello', 'world'], 'http://example.com');</pre>
953:
954:
1.121 ihickson 955: <h4 id="examples"><span class="secno">5.1.1 </span>Examples</h4>
956:
957: <p><i>This section is non-normative.</i></p>
958:
959: <div class="example">
960:
961: <p>In this example, two JavaScript libraries are connected to each
962: other using <code><a href="#messageport">MessagePort</a></code>s. This allows the libraries to
963: later be hosted in different frames, or in <code>Worker</code>
964: objects, without any change to the APIs.</p>
965:
966: <pre><script src="contacts.js"></script> <!-- exposes a contacts object -->
967: <script src="compose-mail.js"></script> <!-- exposes a composer object -->
968: <script>
969: var channel = new MessageChannel();
970: composer.addContactsProvider(channel.port1);
971: contacts.registerConsumer(channel.port2);
972: </script></pre>
973:
974: <p>Here's what the "addContactsProvider()" function's
975: implementation could look like:</p>
976:
977: <pre>function addContactsProvider(port) {
978: port.onmessage = function (event) {
979: switch (event.data.messageType) {
980: 'search-result': handleSearchResult(event.data.results); break;
981: 'search-done': handleSearchDone(); break;
982: 'search-error': handleSearchError(event.data.message); break;
983: // ...
984: }
985: };
986: };</pre>
987:
988: <p>Alternatively, it could be implemented as follows:</p>
989:
990: <pre>function addContactsProvider(port) {
991: port.addEventListener('message', function (event) {
992: if (event.data.messageType == 'search-result')
993: handleSearchResult(event.data.results);
994: });
995: port.addEventListener('message', function (event) {
996: if (event.data.messageType == 'search-done')
997: handleSearchDone();
998: });
999: port.addEventListener('message', function (event) {
1000: if (event.data.messageType == 'search-error')
1001: handleSearchError(event.data.message);
1002: });
1003: // ...
1004: port.start();
1005: };</pre>
1006:
1007: <p>The key difference is that when using <code title="dom-EventTarget-addEventListener">addEventListener()</code>,
1008: the <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method must
1009: also be invoked. When using <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code>, the call to
1010: <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> is implied.</p>
1011:
1012: <p>The <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method,
1013: whether called explicitly or implicitly (by setting <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code>), starts the
1014: flow of messages: messages posted on message ports are initially
1015: paused, so that they don't get dropped on the floor before the
1016: script has had a chance to set up its handlers.</p>
1017:
1018: </div>
1019:
1020:
1021: <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 1022:
1023: <p><i>This section is non-normative.</i></p>
1024:
1025: <p>Ports can be viewed as a way to expose limited capabilities (in
1.100 ihickson 1026: the object-capability model sense) to other actors in the system.
1027: This can either be a weak capability system, where the ports are
1028: merely used as a convenient model within a particular origin, or as
1029: a strong capability model, where they are provided by one origin
1030: <var title="">provider</var> as the only mechanism by which another
1031: origin <var title="">consumer</var> can effect change in or obtain
1.114 ihickson 1032: information from <var title="">provider</var>.</p>
1033:
1034: <p>For example, consider a situation in which a social Web site
1.100 ihickson 1035: embeds in one <code>iframe</code> the user's e-mail contacts
1036: provider (an address book site, from a second origin), and in a
1037: second <code>iframe</code> a game (from a third origin). The outer
1038: social site and the game in the second <code>iframe</code> cannot
1039: access anything inside the first <code>iframe</code>; together they
1.114 ihickson 1040: can only:</p>
1041:
1042: <ul class="brief"><li><span>Navigate</span> the <code>iframe</code> to a new
1.100 ihickson 1043: <span>URL</span>, such as the same <span>URL</span> but with a
1044: different fragment identifier, causing the <code>Window</code> in
1045: the <code>iframe</code> to receive a <code title="event-hashchange">hashchange</code> event.</li>
1046:
1047: <li>Resize the <code>iframe</code>, causing the <code>Window</code>
1048: in the <code>iframe</code> to receive a <code title="event-resize">resize</code> event.</li>
1049:
1050:
1051:
1.107 ihickson 1052: <li>Send a <code title="event-message"><a href="#event-message">message</a></code> event to
1.100 ihickson 1053: the <code>Window</code> in the <code>iframe</code> using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">window.postMessage()</a></code>
1054: API.</li>
1055:
1056: </ul><p>The contacts provider can use these methods, most particularly
1057: the third one, to provide an API that can be accessed by other
1058: origins to manipulate the user's address book. For example, it could
1059: respond to a message "<code title="">add-contact Guillaume Tell
1060: <tell@pomme.example.net></code>" by adding the given person and
1.114 ihickson 1061: e-mail address to the user's address book.</p>
1062:
1063: <p>To avoid any site on the Web being able to manipulate the user's
1.100 ihickson 1064: contacts, the contacts provider might only allow certain trusted
1.114 ihickson 1065: sites, such as the social site, to do this.</p>
1066:
1067: <p>Now suppose the game wanted to add a contact to the user's
1.100 ihickson 1068: address book, and that the social site was willing to allow it to do
1069: so on its behalf, essentially "sharing" the trust that the contacts
1070: provider had with the social site. There are several ways it could
1071: do this; most simply, it could just proxy messages between the game
1072: site and the contacts site. However, this solution has a number of
1073: difficulties: it requires the social site to either completely trust
1074: the game site not to abuse the privilege, or it requires that the
1075: social site verify each request to make sure it's not a request that
1076: it doesn't want to allow (such as adding multiple contacts, reading
1077: the contacts, or deleting them); it also requires some additional
1078: complexity if there's ever the possibility of multiple games
1.114 ihickson 1079: simultaneously trying to interact with the contacts provider.</p>
1080:
1081: <p>Using message channels and <code><a href="#messageport">MessagePort</a></code> objects,
1.100 ihickson 1082: however, all of these problems can go away. When the game tells the
1083: social site that it wants to add a contact, the social site can ask
1084: the contacts provider not for it to add a contact, but for the
1085: <em>capability</em> to add a single contact. The contacts provider
1086: then creates a pair of <code><a href="#messageport">MessagePort</a></code> objects, and sends
1087: one of them back to the social site, who forwards it on to the game.
1088: The game and the contacts provider then have a direct connection,
1089: and the contacts provider knows to only honor a single "add contact"
1090: request, nothing else. In other words, the game has been granted the
1.114 ihickson 1091: capability to add a single contact.</p>
1092:
1093:
1.121 ihickson 1094: <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 1095:
1096: <p><i>This section is non-normative.</i></p>
1097:
1098: <p>Continuing the example from the previous section, consider the
1.100 ihickson 1099: contacts provider in particular. While an initial implementation
1100: might have simply used <code>XMLHttpRequest</code> objects in the
1101: service's <code>iframe</code>, an evolution of the service might
1102: instead want to use a <span title="SharedWorker">shared
1.114 ihickson 1103: worker</span> with a single <code>WebSocket</code> connection.</p>
1104:
1105: <p>If the initial design used <code><a href="#messageport">MessagePort</a></code> objects to
1.100 ihickson 1106: grant capabilities, or even just to allow multiple simultaneous
1107: independent sessions, the service implementation can switch from the
1108: <code>XMLHttpRequest</code>s-in-each-<code>iframe</code> model to
1109: the shared-<code>WebSocket</code> model without changing the API at
1110: all: the ports on the service provider side can all be forwarded to
1111: the shared worker without it affecting the users of the API in the
1.114 ihickson 1112: slightest.</p>
1113:
1114:
1115:
1116: <h3 id="message-channels"><span class="secno">5.2 </span>Message channels</h3>
1117:
1118: <pre class="idl">[<a href="#dom-messagechannel" title="dom-MessageChannel">Constructor</a>]
1.1 ihickson 1119: interface <dfn id="messagechannel">MessageChannel</dfn> {
1120: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port1" title="dom-channel-port1">port1</a>;
1121: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port2" title="dom-channel-port2">port2</a>;
1.114 ihickson 1122: };</pre>
1123:
1124: <dl class="domintro"><dt><var title="">channel</var> = new <code title="dom-MessageChannel"><a href="#dom-messagechannel">MessageChannel</a></code>()</dt>
1.1 ihickson 1125:
1126: <dd>
1127:
1128: <p>Returns a new <code><a href="#messagechannel">MessageChannel</a></code> object with two new <code><a href="#messageport">MessagePort</a></code> objects.</p>
1129:
1130: </dd>
1131:
1132: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port1">port1</code></dt>
1133:
1134: <dd>
1135:
1136: <p>Returns the first <code><a href="#messageport">MessagePort</a></code> object.</p>
1137:
1138: </dd>
1139:
1140: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port2">port2</code></dt>
1141:
1142: <dd>
1143:
1144: <p>Returns the second <code><a href="#messageport">MessagePort</a></code> object.</p>
1145:
1146: </dd>
1147:
1148: </dl><div class="impl">
1149:
1150: <p>When the <dfn id="dom-messagechannel" title="dom-MessageChannel"><code>MessageChannel()</code></dfn>
1151: constructor is called, it must run the following algorithm:</p>
1152:
1153: <ol><li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a>
1154: owned by the <span>script's global object</span>, and let <var title="">port1</var> be that object.</li>
1155:
1156: <li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a>
1157: owned by the <span>script's global object</span>, and let <var title="">port2</var> be that object.</li>
1158:
1159: <li><p><a href="#entangle">Entangle</a> the <var title="">port1</var> and <var title="">port2</var> objects.</li>
1160:
1161: <li><p>Instantiate a new <code><a href="#messagechannel">MessageChannel</a></code> object, and
1162: let <var title="">channel</var> be that object.</li>
1163:
1164: <li><p>Let the <code title="dom-channel-port1"><a href="#dom-channel-port1">port1</a></code>
1165: attribute of the <var title="">channel</var> object be <var title="">port1</var>.</p>
1166:
1167: <li><p>Let the <code title="dom-channel-port2"><a href="#dom-channel-port2">port2</a></code>
1168: attribute of the <var title="">channel</var> object be <var title="">port2</var>.</p>
1169:
1170: <li><p>Return <var title="">channel</var>.</li>
1171:
1172: </ol><p>This constructor must be visible when the <span>script's global
1173: object</span> is either a <code>Window</code> object or an object
1.135 ihickson 1174: implementing the <code>WorkerGlobalScope</code> interface.</p>
1.1 ihickson 1175:
1176: <p>The <dfn id="dom-channel-port1" title="dom-channel-port1"><code>port1</code></dfn> and
1177: <dfn id="dom-channel-port2" title="dom-channel-port2"><code>port2</code></dfn> attributes
1178: must return the values they were assigned when the
1179: <code><a href="#messagechannel">MessageChannel</a></code> object was created.</p>
1180:
1.114 ihickson 1181: </div>
1182:
1183:
1184:
1185: <h3 id="message-ports"><span class="secno">5.3 </span>Message ports</h3>
1186:
1187: <p>Each channel has two message ports. Data sent through one port is
1188: received by the other port, and vice versa.</p>
1189:
1190: <pre class="idl">interface <dfn id="messageport">MessagePort</dfn> : <span>EventTarget</span> {
1.113 ihickson 1191: void <a href="#dom-messageport-postmessage" title="dom-MessagePort-postMessage">postMessage</a>(any message, optional sequence<<span>Transferable</span>> transfer);
1192: void <a href="#dom-messageport-start" title="dom-MessagePort-start">start</a>();
1.1 ihickson 1193: void <a href="#dom-messageport-close" title="dom-MessagePort-close">close</a>();
1194:
1195: // event handlers
1.120 ihickson 1196: attribute <span>EventHandler</span> <a href="#handler-messageport-onmessage" title="handler-MessagePort-onmessage">onmessage</a>;
1.1 ihickson 1197: };
1.114 ihickson 1198: <a href="#messageport">MessagePort</a> implements <span>Transferable</span>;</pre>
1199:
1200: <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 1201:
1202: <dd>
1203:
1.88 ihickson 1204: <p>Posts a message through the channel. Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning
1205: that they are no longer usable on the sending side.</p>
1.1 ihickson 1206:
1.98 ihickson 1207: <p>Throws a <code>DataCloneError</code> if <var title="">transfer</var> array contains duplicate objects or the
1.88 ihickson 1208: source or target ports, or if <var title="">message</var> could
1209: not be cloned.</p>
1.1 ihickson 1210:
1211: </dd>
1212:
1213: <dt><var title="">port</var> . <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start</a></code>()</dt>
1214:
1215: <dd>
1216:
1217: <p>Begins dispatching messages received on the port.</p>
1218:
1219: </dd>
1220:
1221: <dt><var title="">port</var> . <code title="dom-MessagePort-close"><a href="#dom-messageport-close">close</a></code>()</dt>
1222:
1223: <dd>
1224:
1225: <p>Disconnects the port, so that it is no longer active.</p>
1226:
1227: </dd>
1228:
1229: </dl><div class="impl">
1230:
1231: <p>Each <code><a href="#messageport">MessagePort</a></code> object can be entangled with
1232: another (a symmetric relationship). Each <code><a href="#messageport">MessagePort</a></code>
1233: object also has a <span>task source</span> called the <dfn id="port-message-queue">port
1.112 ihickson 1234: message queue</dfn>, initially empty. A <a href="#port-message-queue">port message
1.1 ihickson 1235: queue</a> can be enabled or disabled, and is initially
1236: disabled. Once enabled, a port can never be disabled again (though
1237: messages in the queue can get moved to another queue or removed
1.134 ihickson 1238: altogether, which has much the same effect).
1239: A <code><a href="#messageport">MessagePort</a></code> also has a <dfn id="has-been-shipped">has been shipped</dfn> flag. It must initially be
1240: false.</p>
1241:
1242: <p>Each <span>event loop</span> has a <span>task source</span> called the <dfn id="unshipped-port-message-queue">unshipped port
1243: message queue</dfn>. This is a virtual <span>task source</span>: it must act as if it contained
1244: the <span title="concept-task">tasks</span> of each <a href="#port-message-queue">port message queue</a> of each
1245: <code><a href="#messageport">MessagePort</a></code> whose <a href="#has-been-shipped">has been shipped</a> flag is false, in the order in which
1246: they were added to their respective <span>task source</span>. When a <span title="concept-task">task</span> would be removed from the <a href="#unshipped-port-message-queue">unshipped port message
1247: queue</a>, it must instead be removed from its <a href="#port-message-queue">port message queue</a>.</p>
1248:
1249: <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
1250: message queue</a> must be ignored for the purposes of the <span>event loop</span>. (The
1251: <a href="#unshipped-port-message-queue">unshipped port message queue</a> is used instead.)</p>
1252:
1253: <p class="note">The <a href="#has-been-shipped">has been shipped</a> flag is set to true when a port, its twin, or
1254: the object it was cloned from, is or has been <span title="transfer a transferable
1255: object">transferred</span>. When a <code><a href="#messageport">MessagePort</a></code>'s <a href="#has-been-shipped">has been shipped</a> flag
1256: is true, its <a href="#port-message-queue">port message queue</a> acts as a first-class <span>task source</span>,
1257: unaffected to any <a href="#unshipped-port-message-queue">unshipped port message queue</a>.</p>
1.1 ihickson 1258:
1259: <p>When the user agent is to <dfn id="create-a-new-messageport-object">create a new
1260: <code>MessagePort</code> object</dfn> owned by a <span>script's
1261: global object</span> object <var title="">owner</var>, it must
1262: instantiate a new <code><a href="#messageport">MessagePort</a></code> object, and let its owner
1263: be <var title="">owner</var>.</p>
1264:
1.88 ihickson 1265: <p>When the user agent is to <dfn id="entangle">entangle</dfn> two
1.1 ihickson 1266: <code><a href="#messageport">MessagePort</a></code> objects, it must run the following
1267: steps:</p>
1268:
1269: <ol><li>
1270:
1271: <p>If one of the ports is already entangled, then disentangle it
1272: and the port that it was entangled with.</p>
1273:
1274: <p class="note">If those two previously entangled ports were the
1275: two ports of a <code><a href="#messagechannel">MessageChannel</a></code> object, then that
1276: <code><a href="#messagechannel">MessageChannel</a></code> object no longer represents an actual
1277: channel: the two ports in that object are no longer entangled.</p>
1278:
1279: </li>
1280:
1281: <li><p>Associate the two ports to be entangled, so that they form
1282: the two parts of a new channel. (There is no
1283: <code><a href="#messagechannel">MessageChannel</a></code> object that represents this
1284: channel.)</li>
1285:
1.88 ihickson 1286: </ol><p>When the user agent is to <dfn id="clone-a-port">clone a port</dfn> <var title="">original port</var>, with the clone being owned by <var title="">owner</var>, it must run the following steps, which return
1.1 ihickson 1287: a new <code><a href="#messageport">MessagePort</a></code> object. These steps must be run
1288: atomically.</p>
1289:
1.134 ihickson 1290: <ol><li><p>Set <var title="">original port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1291: true.</li>
1292:
1293: <li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a>
1.1 ihickson 1294: owned by <var title="">owner</var>, and let <var title="">new
1295: port</var> be that object.</li>
1296:
1.134 ihickson 1297: <li><p>Set <var title="">new port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to true.</li>
1298:
1.1 ihickson 1299: <li><p>Move all the events in the <a href="#port-message-queue">port message queue</a>
1300: of <var title="">original port</var> to the <a href="#port-message-queue">port message
1301: queue</a> of <var title="">new port</var>, if any, leaving the
1302: <var title="">new port</var>'s <a href="#port-message-queue">port message queue</a> in
1303: its initial disabled state.</li>
1304:
1305: <li>
1306:
1307: <p>If the <var title="">original port</var> is entangled with
1308: another port, then run these substeps:</p>
1309:
1310: <ol><li><p>Let the <var title="">remote port</var> be the port with
1311: which the <var title="">original port</var> is entangled.</li>
1312:
1.134 ihickson 1313: <li><p>Set <var title="">remote port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1314: true.</li>
1315:
1.1 ihickson 1316: <li><p><a href="#entangle">Entangle</a> the <var title="">remote port</var>
1317: and <var title="">new port</var> objects. The <var title="">original port</var> object will be disentangled by this
1318: process.</li>
1319:
1320: </ol></li>
1321:
1322: <li><p>Return <var title="">new port</var>. It is the
1323: clone.</li>
1324:
1.88 ihickson 1325: </ol><p id="transferMessagePort">To <span title="transfer a Transferable
1326: object">transfer</span> a <code><a href="#messageport">MessagePort</a></code> object <var title="">old</var> to a new owner <var title="">owner</var>, a user
1.101 ihickson 1327: agent must <a href="#clone-a-port" title="clone a port">clone</a> the <var title="">old</var> object with the clone being owned by <var title="">owner</var>, thus obtaining <var title="">new</var>, must
1328: <span title="concept-Transferable-neutered">neuter</span> the <var title="">old</var> port, and must finally return <var title="">new</var>.</p>
1.88 ihickson 1329:
1330: <hr><p>The <dfn id="dom-messageport-postmessage" title="dom-MessagePort-postMessage"><code>postMessage()</code></dfn>
1.1 ihickson 1331: method, when called on a port <var title="">source port</var>, must
1332: cause the user agent to run the following steps:</p>
1333:
1334: <ol><li><p>Let <var title="">target port</var> be the port with which
1335: <var title="">source port</var> is entangled, if any.</li>
1336:
1.88 ihickson 1337: <li>
1338:
1339: <p>Let <var title="">new ports</var> be an empty array.</p>
1340:
1341: </li>
1342:
1343: <li>
1.1 ihickson 1344:
1.88 ihickson 1345: <p>Let <var title="">transfer map</var> be an empty association
1.105 ihickson 1346: list of <code>Transferable</code> objects to placeholder
1347: objects.</p>
1.1 ihickson 1348:
1.88 ihickson 1349: </li>
1.1 ihickson 1350:
1.88 ihickson 1351: <li>
1.1 ihickson 1352:
1.88 ihickson 1353: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these substeps:</p>
1.1 ihickson 1354:
1355: <ol><li>
1356:
1.88 ihickson 1357: <p>If any object is listed in <var title="">transfer</var> more
1358: than once, or any of the <code>Transferable</code> objects
1.104 ihickson 1359: listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then
1360: throw a <code>DataCloneError</code> exception and abort these
1361: steps.</p>
1.1 ihickson 1362:
1.88 ihickson 1363: </li>
1.1 ihickson 1364:
1.88 ihickson 1365: <li>
1366:
1367: <p>If any of the objects in <var title="">transfer</var> are
1368: either the <var title="">source port</var> or the <var title="">target port</var> (if any), then throw a
1.98 ihickson 1369: <code>DataCloneError</code> exception and abort these
1.89 ihickson 1370: steps.</p>
1.88 ihickson 1371:
1.89 ihickson 1372: </li>
1.1 ihickson 1373:
1.84 ihickson 1374: <li>
1375:
1.105 ihickson 1376: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a mapping from <var title="">x</var> to a new unique placeholder object created for
1377: <var title="">x</var> to <var title="">transfer map</var>, and
1378: if <var title="">x</var> is a <code><a href="#messageport">MessagePort</a></code> object,
1379: also append the placeholder object to the <var title="">new
1380: ports</var> array.</p>
1.84 ihickson 1381:
1382: </li>
1383:
1.89 ihickson 1384: </ol></li>
1385:
1386: <li>
1.1 ihickson 1387:
1.105 ihickson 1388: <p>Let <var title="">message clone</var> be the result of
1389: obtaining a <span>structured clone</span> of the <var title="">message</var> argument, with <var title="">transfer
1390: map</var> as the <i>transfer map</i>. If this throws an exception,
1391: then throw that exception and abort these steps.</p>
1.88 ihickson 1392:
1393: </li>
1394:
1.105 ihickson 1395: <li>
1396:
1397: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these substeps:</p>
1398:
1399: <ol><li>
1400:
1401: <p>Let <var title="">new owner</var> be the owner of <var title="">target port</var>, if there is a <var title="">target
1.125 ihickson 1402: port</var>, or else some arbitrary owner. (This <var title="">new owner</var> is used when transferring objects below.
1.105 ihickson 1403: If there is no <var title="">target port</var>, the
1404: <code>Transferable</code> objects given in the second argument,
1405: if any, are still <span title="transfer a Transferable
1.125 ihickson 1406: object">transferred</span>, but since they are then discarded, it
1407: doesn't matter where they are transferred to.)</p>
1.105 ihickson 1408:
1409: </li>
1410:
1411:
1412: <li>
1413:
1414: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain a new object <var title="">y</var> by <span title="transfer a Transferable
1415: object">transferring</span> the object <var title="">x</var> to
1416: <var title="">new owner</var>, and replace the placeholder
1417: object that was created for the object <var title="">x</var> by
1418: the new object <var title="">y</var> wherever the placeholder
1419: exists (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</p>
1420:
1421: </li>
1422:
1423: </ol></li>
1.88 ihickson 1424:
1425: <li>
1426:
1.105 ihickson 1427: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span> array.</p>
1.88 ihickson 1428:
1429: </li>
1430:
1.96 ihickson 1431: <li><p>If there is no <var title="">target port</var> (i.e. if <var title="">source port</var> is not entangled), then abort these
1432: steps.</li>
1.113 ihickson 1433:
1.88 ihickson 1434: <li><p>Create an event that uses the <code><a href="#messageevent">MessageEvent</a></code>
1435: interface, with the name <code title="event-message"><a href="#event-message">message</a></code>, which does not bubble, is not
1.109 ihickson 1436: cancelable, and has no default action.
1437:
1438: <a href="#refsHTML">[HTML]</a>
1439:
1440: </li>
1.88 ihickson 1441:
1442: <li><p>Let the <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code>
1.96 ihickson 1443: attribute of the event be initialized to the value of <var title="">message clone</var>.</li>
1.88 ihickson 1444:
1445: <li><p>Let the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code>
1.96 ihickson 1446: attribute of the event be initialized to the <var title="">new
1447: ports</var> array.</li>
1.1 ihickson 1448:
1449: <li><p>Add the event to the <a href="#port-message-queue">port message queue</a> of <var title="">target port</var>.</li>
1450:
1.89 ihickson 1451: </ol><hr><p>The <dfn id="dom-messageport-start" title="dom-MessagePort-start"><code>start()</code></dfn>
1.1 ihickson 1452: method must enable its port's <a href="#port-message-queue">port message queue</a>, if it
1453: is not already enabled.</p>
1454:
1455: <p>When a port's <a href="#port-message-queue">port message queue</a> is enabled, the
1456: <span>event loop</span> must use it as one of its <span title="task
1457: source">task sources</span>.</p>
1458:
1459: <p class="note">If the <code>Document</code> of the port's event
1460: listeners' <span title="script's global object">global object</span>
1461: is not <span>fully active</span>, then the messages are lost.</p>
1.79 ihickson 1462:
1.1 ihickson 1463:
1464: <hr><p>The <dfn id="dom-messageport-close" title="dom-MessagePort-close"><code>close()</code></dfn>
1465: method, when called on a port <var title="">local port</var> that is
1466: entangled with another port, must cause the user agents to
1467: disentangle the two ports. If the method is called on a port that is
1468: not entangled, then the method must do nothing.</p>
1469:
1470: <hr><p>The following are the <span>event handlers</span> (and their
1471: corresponding <span title="event handler event type">event handler
1472: event types</span>) that must be supported, as IDL attributes, by
1473: all objects implementing the <code><a href="#messageport">MessagePort</a></code> interface:</p>
1474:
1475: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1476: <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>
1477: </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
1478: is set, the port's <a href="#port-message-queue">port message queue</a> must be enabled,
1479: as if the <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method
1480: had been called.</p>
1481:
1.114 ihickson 1482: </div>
1483:
1484:
1.128 ihickson 1485: <h3 id="broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</h3>
1486:
1487: <p>Broadcasting to many ports is in principle relatively simple: keep an array of
1488: <code><a href="#messageport">MessagePort</a></code> objects to send messages to, and iterate through the array to send a
1.129 ihickson 1489: message. However, this has one rather unfortunate effect: it prevents the ports from being garbage
1.128 ihickson 1490: collected, even if the other side has gone away.</p>
1491:
1492: <p>To avoid this problem, the <code><a href="#portcollection">PortCollection</a></code> object can be used. It acts as an opaque
1493: array of <code><a href="#messageport">MessagePort</a></code> objects, thus allowing the objects to be garbage collected when
1494: they stop being relevant, while still allowing scripts to iterate over the
1495: <code><a href="#messageport">MessagePort</a></code> objects.</p>
1496:
1497: <pre class="idl">[<a href="#dom-portcollection" title="dom-PortCollection">Constructor</a>] interface <dfn id="portcollection">PortCollection</dfn> {
1498: void <a href="#dom-portcollection-add" title="dom-PortCollection-add">add</a>(<a href="#messageport">MessagePort</a> port);
1499: void <a href="#dom-portcollection-remove" title="dom-PortCollection-remove">remove</a>(<a href="#messageport">MessagePort</a> port);
1500: void <a href="#dom-portcollection-clear" title="dom-PortCollection-clear">clear</a>();
1501: void <a href="#dom-portcollection-iterate" title="dom-PortCollection-iterate">iterate</a>(<a href="#portcollectioncallback">PortCollectionCallback</a> callback);
1502: };
1503:
1504: callback <dfn id="portcollectioncallback">PortCollectionCallback</dfn> = void (<a href="#messageport">MessagePort</a> port);</pre>
1505:
1506: <dl class="domintro"><dt><var title="">portCollection</var> = new <code title="dom-PortCollection"><a href="#dom-portcollection">PortCollection</a></code>()</dt>
1507:
1508: <dd>
1509:
1510: <p>Returns a new empty <code><a href="#portcollection">PortCollection</a></code> object.</p>
1511:
1512: </dd>
1513:
1514: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-add"><a href="#dom-portcollection-add">add</a></code>(<var title="">port</var>)</dt>
1515:
1516: <dd>
1517:
1518: <p>Adds <var title="">port</var> to the collection, if it isn't already present.</p>
1519:
1520: </dd>
1521:
1522: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-remove"><a href="#dom-portcollection-remove">remove</a></code>(<var title="">port</var>)</dt>
1523:
1524: <dd>
1525:
1526: <p>Removes <var title="">port</var> from the collection, if it is present.</p>
1527:
1528: </dd>
1529:
1530: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-clear"><a href="#dom-portcollection-clear">clear</a></code>()</dt>
1531:
1532: <dd>
1533:
1534: <p>Removes all ports from the collection.</p>
1535:
1536: </dd>
1537:
1538: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-iterate"><a href="#dom-portcollection-iterate">iterate</a></code>(<var title="">callback</var>)</dt>
1539:
1540: <dd>
1541:
1542: <p>Calls <var title="">callback</var> for each port in the collection.</p>
1543:
1544: </dd>
1545:
1546: </dl><div class="impl">
1547:
1548: <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
1549: a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is garbage collected, it must be
1550: silently removed from that <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>. Objects
1551: in a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> are ordered chronologically by
1552: the time at which they were most recently added; the least-recently added <code><a href="#messageport">MessagePort</a></code>
1553: object is the first in the list, and the most-recently added <code><a href="#messageport">MessagePort</a></code> is the last
1554: in the list.</p>
1555:
1556: <p>The <dfn id="dom-portcollection" title="dom-PortCollection"><code>PortCollection()</code></dfn> constructor must return
1557: 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>
1558:
1559: <p>The <dfn id="dom-portcollection-add" title="dom-PortCollection-add"><code>add()</code></dfn> method must add the
1560: <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
1561: already in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1562: method does nothing. (Calling this method with a port already in the list does not move the port
1563: to the end of the list.)</p>
1564:
1565: <p>The <dfn id="dom-portcollection-remove" title="dom-PortCollection-remove"><code>remove()</code></dfn> method must remove the
1566: <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
1567: not in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1568: method does nothing.</p>
1569:
1570: <p>The <dfn id="dom-portcollection-clear" title="dom-PortCollection-clear"><code>clear()</code></dfn> method must remove all
1571: <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.
1572: If the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is already empty, the method
1573: does nothing.</p>
1574:
1575: <p>The <dfn id="dom-portcollection-iterate" title="dom-PortCollection-iterate"><code>iterate()</code></dfn> method must invoke its
1576: <code><a href="#portcollectioncallback">PortCollectionCallback</a></code> argument once for each <code><a href="#messageport">MessagePort</a></code> object in the
1577: object's <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in the order defined
1578: above, with each invocation being passed the corresponding <code><a href="#messageport">MessagePort</a></code> object as the
1579: callback's sole argument.</p>
1580:
1581: </div>
1582:
1583:
1584: <h3 id="ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</h3>
1.114 ihickson 1585:
1586: <div class="impl">
1.1 ihickson 1587:
1588: <p>When a <code><a href="#messageport">MessagePort</a></code> object <var title="">o</var> is
1589: entangled, user agents must either act as if <var title="">o</var>'s
1590: entangled <code><a href="#messageport">MessagePort</a></code> object has a strong reference to
1591: <var title="">o</var>, or as if <var title="">o</var>'s owner has a
1592: strong reference to <var title="">o</var>.</p>
1593:
1594: <div class="note">
1595:
1596: <p>Thus, a message port can be received, given an event listener,
1597: and then forgotten, and so long as that event listener could
1598: receive a message, the channel will be maintained.</p>
1599:
1600: <p>Of course, if this was to occur on both sides of the channel,
1601: then both ports could be garbage collected, since they would not be
1602: reachable from live code, despite having a strong reference to each
1603: other.</p>
1604:
1605: </div>
1606:
1607: <p>Furthermore, a <code><a href="#messageport">MessagePort</a></code> object must not be
1608: garbage collected while there exists a message in a <span>task
1609: queue</span> that is to be dispatched on that
1610: <code><a href="#messageport">MessagePort</a></code> object, or while the
1611: <code><a href="#messageport">MessagePort</a></code> object's <a href="#port-message-queue">port message queue</a> is
1612: open and there exists a <code title="event-message"><a href="#event-message">message</a></code>
1613: event in that queue.</p>
1.79 ihickson 1614:
1.113 ihickson 1615:
1.79 ihickson 1616:
1.113 ihickson 1617:
1.128 ihickson 1618: <p>There are no strong references from a <code><a href="#portcollection">PortCollection</a></code> object to its
1619: <code><a href="#messageport">MessagePort</a></code> objects. (That is in fact the whole point of <code><a href="#portcollection">PortCollection</a></code>
1620: objects: they allow for <code><a href="#messageport">MessagePort</a></code> objects to be referenced without preventing them
1621: from being garbage collected.)</p>
1622:
1.114 ihickson 1623: </div>
1624:
1.128 ihickson 1625: <p class="note">Authors are strongly encouraged to explicitly close <code><a href="#messageport">MessagePort</a></code>
1626: objects to disentangle them, so that their resources can be recollected. Creating many
1627: <code><a href="#messageport">MessagePort</a></code> objects and discarding them without closing them can lead to high
1628: transient memory usage since garbage collection is not necessarily performed promptly.</p>
1.114 ihickson 1629:
1630:
1631:
1632: <h2 class="no-num" id="references">References</h2>
1633:
1634: <p>All references are normative unless marked "Non-normative".</p>
1635:
1636:
1637:
1.132 ihickson 1638: <dl><dt id="refsDOM">[DOM]</dt>
1639: <dd><cite><a href="http://dom.spec.whatwg.org/">DOM</a></cite>, A. van Kesteren, A. Gregor, Ms2ger. WHATWG.</dd>
1.72 ihickson 1640:
1641: <dt id="refsHTML">[HTML]</dt>
1.127 ihickson 1642: <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML</a></cite>, I. Hickson. WHATWG.</dd>
1.111 ihickson 1643:
1.72 ihickson 1644: <dt id="refsRFC2119">[RFC2119]</dt>
1.133 ihickson 1645: <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 1646:
1.55 ihickson 1647: <dt id="refsWEBIDL">[WEBIDL]</dt>
1.133 ihickson 1648: <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, C. McCormack. W3C.</dd>
1.1 ihickson 1649:
1.114 ihickson 1650: </dl><h2 class="no-num" id="acknowledgements">Acknowledgements</h2>
1651:
1652: <p>For a full list of acknowledgements, please see the HTML
1653: specification. <a href="#refsHTML">[HTML]</a></p>
1654:
1655:
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