Annotation of html5/postmsg/Overview.html, revision 1.95
1.79 ihickson 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"><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; }
53: dl.switch { padding-left: 2em; }
54: dl.switch > dt { text-indent: -1.5em; }
55: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
56: dl.triple { padding: 0 0 0 1em; }
57: dl.triple dt, dl.triple dd { margin: 0; display: inline }
58: dl.triple dt:after { content: ':'; }
59: dl.triple dd:after { content: '\A'; white-space: pre; }
60: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
61: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
62: a .diff-new { border-bottom: 1px blue solid; }
63:
64: h2 { page-break-before: always; }
65: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
66: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
67:
1.64 ihickson 68: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
69: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 ihickson 70:
71: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
72: div.head p { margin: 0; }
73: div.head h1 { margin: 0; }
74: div.head .logo { float: right; margin: 0 1em; }
75: div.head .logo img { border: none } /* remove border from top image */
76: div.head dl { margin: 1em 0; }
77: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
78:
79: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
80: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
81: body > .toc > li > * { margin-bottom: 0.5em; }
82: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
83: .toc, .toc li { list-style: none; }
84:
85: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
86: .brief li { margin: 0; padding: 0; }
87: .brief li p { margin: 0; padding: 0; }
88:
89: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
90: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
91: .category-list li { display: inline; }
92: .category-list li:not(:last-child)::after { content: ', '; }
93: .category-list li > span, .category-list li > a { text-transform: lowercase; }
94: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
95:
96: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
97: .XXX > :first-child { margin-top: 0; }
98: p .XXX { line-height: 3em; }
99: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
100: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
101: .annotation :link, .annotation :visited { color: inherit; }
102: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
103: .annotation span { border: none ! important; }
104: .note { color: green; background: transparent; font-family: sans-serif; }
105: .warning { color: red; background: transparent; }
106: .note, .warning { font-weight: bolder; font-style: italic; }
1.91 ihickson 107: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.1 ihickson 108: p.note, div.note { padding: 0.5em 2em; }
109: span.note { padding: 0 2em; }
110: .note p:first-child, .warning p:first-child { margin-top: 0; }
111: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
112: .warning:before { font-style: normal; }
113: p.note:before { content: 'Note: '; }
114: p.warning:before { content: '\26A0 Warning! '; }
115:
116: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
117: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
118: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.57 ihickson 119: .bookkeeping dt { margin: 0.5em 2em 0; }
120: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 ihickson 121:
122: h4 { position: relative; z-index: 3; }
123: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
124: .element {
125: background: #EEEEFF;
126: color: black;
127: margin: 0 0 1em 0.15em;
128: padding: 0 1em 0.25em 0.75em;
129: border-left: solid #9999FF 0.25em;
130: position: relative;
131: z-index: 1;
132: }
133: .element:before {
134: position: absolute;
135: z-index: 2;
136: top: 0;
137: left: -1.15em;
138: height: 2em;
139: width: 0.9em;
140: background: #EEEEFF;
141: content: ' ';
142: border-style: none none solid solid;
143: border-color: #9999FF;
144: border-width: 0.25em;
145: }
146:
147: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
148: td > .example:only-child { margin: 0 0 0 0.1em; }
149:
150: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
151: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
152: ul.domTree li li { list-style: none; }
153: 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; }
154: 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; }
155: ul.domTree span { font-style: italic; font-family: serif; }
156: ul.domTree .t1 code { color: purple; font-weight: bold; }
157: ul.domTree .t2 { font-style: normal; font-family: monospace; }
158: ul.domTree .t2 .name { color: black; font-weight: bold; }
159: ul.domTree .t2 .value { color: blue; font-weight: normal; }
160: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
161: ul.domTree .t7 code, .domTree .t8 code { color: green; }
162: ul.domTree .t10 code { color: teal; }
163:
1.7 ihickson 164: body.dfnEnabled dfn { cursor: pointer; }
165: .dfnPanel {
166: display: inline;
167: position: absolute;
168: z-index: 10;
169: height: auto;
170: width: auto;
171: padding: 0.5em 0.75em;
172: font: small sans-serif, Droid Sans Fallback;
173: background: #DDDDDD;
174: color: black;
175: border: outset 0.2em;
176: }
177: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
178: .dfnPanel :link, .dfnPanel :visited { color: black; }
179: .dfnPanel p { font-weight: bolder; }
180: .dfnPanel * + p { margin-top: 0.25em; }
181: .dfnPanel li { list-style-position: inside; }
182:
1.1 ihickson 183: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
184: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
185: #configUI p label { display: block; }
186: #configUI #updateUI, #configUI .loginUI { text-align: center; }
187: #configUI input[type=button] { display: block; margin: auto; }
1.56 ihickson 188:
1.66 ihickson 189: fieldset { margin: 1em; padding: 0.5em 1em; }
190: fieldset > legend + * { margin-top: 0; }
1.63 ihickson 191: fieldset > :last-child { margin-bottom: 0; }
1.66 ihickson 192: fieldset p { margin: 0.5em 0; }
1.63 ihickson 193:
1.72 ihickson 194: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><script type="text/javascript">
1.1 ihickson 195: function getCookie(name) {
196: var params = location.search.substr(1).split("&");
197: for (var index = 0; index < params.length; index++) {
198: if (params[index] == name)
199: return "1";
200: var data = params[index].split("=");
201: if (data[0] == name)
202: return unescape(data[1]);
203: }
204: var cookies = document.cookie.split("; ");
205: for (var index = 0; index < cookies.length; index++) {
206: var data = cookies[index].split("=");
207: if (data[0] == name)
208: return unescape(data[1]);
209: }
210: return null;
211: }
1.81 ihickson 212: </script><div class="head" id="head">
1.1 ihickson 213: <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 214:
1.10 ihickson 215: <h1>HTML5 Web Messaging</h1>
1.79 ihickson 216:
1.95 ! ihickson 217: <h2 class="no-num no-toc" id="editor-s-draft-17-august-2011">Editor's Draft 17 August 2011</h2>
1.72 ihickson 218: <dl><dt>Latest Published Version:</dt>
1.70 abarsto 219: <dd><a href="http://www.w3.org/TR/webmessaging/">http://www.w3.org/TR/webmessaging/</a></dd>
1.1 ihickson 220: <dt>Latest Editor's Draft:</dt>
1.56 ihickson 221: <dd><a class="latest-link" href="http://dev.w3.org/html5/postmsg/">http://dev.w3.org/html5/postmsg/</a></dd>
1.82 ihickson 222:
1.1 ihickson 223: <dt>Previous Versions:</dt>
1.72 ihickson 224: <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 225: <!-- :ZZZ -->
1.72 ihickson 226: <dt>Editor:</dt>
1.1 ihickson 227: <dd><a href="mailto:ian@hixie.ch">Ian Hickson</a>, Google, Inc.</dd>
1.3 ihickson 228: </dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
1.83 ihickson 229: © 2011 <a href="http://www.w3.org/"><abbr title="World Wide
1.1 ihickson 230: Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts
1.90 ihickson 231: Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research
1.1 ihickson 232: Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C
233: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
234: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
235: and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document
236: use</a> rules apply.</p>
1.6 ihickson 237:
1.48 ihickson 238:
1.6 ihickson 239: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
1.52 ihickson 240: <p class="alt">The bulk of the text of this specification is also
1.48 ihickson 241: 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
242: reuse of the specification text.</p>
1.6 ihickson 243: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
244:
1.48 ihickson 245:
1.77 ihickson 246: </div><hr class="top"><h2 class="no-num no-toc" id="abstract">Abstract</h2><p>This specification defines two mechanisms for communicating
1.79 ihickson 247: between browsing contexts in HTML documents.<h2 class="no-num no-toc" id="status-of-this-document">Status of This document</h2><p><em>This section describes the status of this document at the
1.1 ihickson 248: time of its publication. Other documents may supersede this
1.90 ihickson 249: document. A list of current W3C publications and the
250:
251: most recently formally published <!-- DO NOT CHANGE THIS BACK TO THE STANDARD BOILERPLATE, AS IT IS INACCURATE -->
252:
253: revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
254: http://www.w3.org/TR/.</em></p><p>If you wish to make comments regarding this document in a manner
1.63 ihickson 255: that is tracked by the W3C, please submit them via using <a href="http://www.w3.org/Bugs/Public/enter_bug.cgi?product=HTML%20WG">our
1.72 ihickson 256: public bug database</a>. If you do not have an account then you can
1.65 ihickson 257: enter feedback using this form:<form action="http://www.whatwg.org/specs/web-apps/current-work/file-spam.cgi" method="post">
1.63 ihickson 258: <fieldset><legend>Feedback Comments</legend>
1.72 ihickson 259: <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 260: indicating the title of the section for which you are submitting
261: feedback, quoting the text that's wrong today if appropriate. If
262: you're suggesting a new feature, it's really important to say
263: <em>what</em> the problem you're trying to solve is. That's more
264: important than the solution, in fact.</label></p>
265: <p><textarea cols="79" id="feedbackBox" name="text" rows="10"></textarea></p>
1.66 ihickson 266: <p class="note">Please don't use section numbers as these tend to
267: change rapidly and make your feedback harder to understand.</p>
1.65 ihickson 268: <script type="text/javascript">
1.85 ihickson 269: function checkFeedbackForm(form) {
270: if (form.elements.text.value.match(/^ *</)) {
271: alert('Please don\'t start your feedback with an angle bracket, instead explain what topic your feedback is about first.');
272: return true;
273: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
274: if (form.elements.text.value.match(/^Please enter your feedback, carefully/)) {
275: alert('Please enter your feedback, explaining what is wrong, and without repeating the instructions. Thanks!');
276: return true;
277: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
278: form.action = "http://www.whatwg.org/specs/web-apps/current-work/file-bug.cgi";
279: return true;
280: } else {
281: alert('Please include significantly more detail about exactly what problem you are trying to solve.');
282: return false;
283: }
284: }
285: }
1.66 ihickson 286: </script><p>
1.76 ihickson 287: <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 288: </p>
1.72 ihickson 289: </fieldset></form><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>,
290: <a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>),
291: 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 292: <a href="http://lists.whatwg.org/pipermail/whatwg-whatwg.org/">archives</a>).
1.79 ihickson 293: All feedback is welcome.</p><p>Implementors should be aware that this specification is not
1.72 ihickson 294: stable. <strong>Implementors who are not taking part in the
295: discussions are likely to find the specification changing out from
296: under them in incompatible ways.</strong> Vendors interested in
297: implementing this specification before it eventually reaches the
298: Candidate Recommendation stage should join the aforementioned
299: mailing lists and take part in the discussions.<div id="multipage-common">
1.79 ihickson 300: </div><p>The latest
1.72 ihickson 301: stable version of the editor's draft of this specification is always
302: available on <a href="http://dev.w3.org/html5/postmsg/">the W3C CVS server</a>
303: and in the <a href="http://svn.whatwg.org/webapps/">WHATWG
304: Subversion repository</a>. The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html">latest
1.1 ihickson 305: editor's working copy</a> (which may contain unfinished text in the
306: process of being prepared) contains the latest draft text of this
307: 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.72 ihickson 308: FAQ</a>.<p>Notifications of changes to this specification are sent along
309: with notifications of changes to related specifications using the
310: following mechanisms:<dl><dt>E-mail notifications of changes</dt>
1.1 ihickson 311: <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>
312: <dt>Browsable version-control record of all changes:</dt>
313: <dd>CVSWeb interface with side-by-side diffs: <a href="http://dev.w3.org/cvsweb/html5/">http://dev.w3.org/cvsweb/html5/</a></dd>
314: <dd>Annotated summary with unified diffs: <a href="http://html5.org/tools/web-apps-tracker">http://html5.org/tools/web-apps-tracker</a></dd>
315: <dd>Raw Subversion interface: <code>svn checkout http://svn.whatwg.org/webapps/</code></dd>
1.72 ihickson 316: </dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
317: Working Group</a> is the W3C working group responsible for this
318: specification's progress along the W3C Recommendation track.
1.95 ! ihickson 319: This specification is the 17 August 2011 Editor's Draft.
1.79 ihickson 320: </p><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 321: 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 322: any patent disclosures</a> made in connection with the deliverables
323: of the group; that page also includes instructions for disclosing a
324: patent. An individual who has actual knowledge of a patent which the
325: individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
326: Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
1.6 ihickson 327: 6 of the W3C Patent Policy</a>.<h2 class="no-num no-toc" id="contents">Table of Contents</h2>
1.1 ihickson 328: <ol class="toc">
1.72 ihickson 329: <li><a href="#conformance-requirements"><span class="secno">1 </span>Conformance requirements</a>
1.1 ihickson 330: <ol>
1.72 ihickson 331: <li><a href="#dependencies"><span class="secno">1.1 </span>Dependencies</a></ol></li>
332: <li><a href="#terminology"><span class="secno">2 </span>Terminology</a></li>
333: <li><a href="#event-definitions"><span class="secno">3 </span>Event definitions</a></li>
334: <li><a href="#web-messaging"><span class="secno">4 </span>Cross-document messaging</a>
335: <ol>
336: <li><a href="#introduction"><span class="secno">4.1 </span>Introduction</a></li>
337: <li><a href="#security-postmsg"><span class="secno">4.2 </span>Security</a>
1.1 ihickson 338: <ol>
1.72 ihickson 339: <li><a href="#authors"><span class="secno">4.2.1 </span>Authors</a></li>
340: <li><a href="#user-agents"><span class="secno">4.2.2 </span>User agents</a></ol></li>
341: <li><a href="#posting-messages"><span class="secno">4.3 </span>Posting messages</a></ol></li>
342: <li><a href="#channel-messaging"><span class="secno">5 </span>Channel messaging</a>
1.1 ihickson 343: <ol>
1.72 ihickson 344: <li><a href="#introduction-0"><span class="secno">5.1 </span>Introduction</a></li>
345: <li><a href="#message-channels"><span class="secno">5.2 </span>Message channels</a></li>
346: <li><a href="#message-ports"><span class="secno">5.3 </span>Message ports</a>
1.1 ihickson 347: <ol>
1.72 ihickson 348: <li><a href="#ports-and-garbage-collection"><span class="secno">5.3.1 </span>Ports and garbage collection</a></ol></ol></li>
1.1 ihickson 349: <li><a class="no-num" href="#references">References</a></li>
350: <li><a class="no-num" href="#acknowledgements">Acknowledgements</a></ol>
1.79 ihickson 351: <hr><h2 id="conformance-requirements"><span class="secno">1 </span>Conformance requirements</h2><p>All diagrams, examples, and notes in this specification are
1.72 ihickson 352: non-normative, as are all sections explicitly marked non-normative.
1.79 ihickson 353: Everything else in this specification is normative.<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
1.72 ihickson 354: "OPTIONAL" in the normative parts of this document are to be
355: interpreted as described in RFC2119. For readability, these words do
356: not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a><p>Requirements phrased in the imperative as part of algorithms
357: (such as "strip any leading space characters" or "return false and
358: abort these steps") are to be interpreted with the meaning of the
359: key word ("must", "should", "may", etc) used in introducing the
360: algorithm.<p>Some conformance requirements are phrased as requirements on
361: attributes, methods or objects. Such requirements are to be
362: interpreted as requirements on user agents.<p>Conformance requirements phrased as algorithms or specific steps
363: may be implemented in any manner, so long as the end result is
364: equivalent. (In particular, the algorithms defined in this
365: specification are intended to be easy to follow, and not intended to
366: be performant.)<p>The only conformance class defined by this specification is user
367: agents.<p>User agents may impose implementation-specific limits on
368: otherwise unconstrained inputs, e.g. to prevent denial of service
369: attacks, to guard against running out of memory, or to work around
370: platform-specific limitations.<p>When support for a feature is disabled (e.g. as an emergency
371: measure to mitigate a security problem, or to aid in development, or
372: for performance reasons), user agents must act as if they had no
373: support for the feature whatsoever, and as if the feature was not
374: mentioned in this specification. For example, if a particular
375: feature is accessed via an attribute in a Web IDL interface, the
376: attribute itself would be omitted from the objects that implement
377: that interface — leaving the attribute on the object but
378: making it return null or throw an exception is insufficient.<h3 id="dependencies"><span class="secno">1.1 </span>Dependencies</h3><p>This specification relies on several other underlying
379: specifications.<dl><dt>HTML</dt>
380:
381: <dd>
382:
383: <p>Many fundamental concepts from HTML are used by this
384: specification. <a href="#refsHTML">[HTML]</a></p>
385:
386: </dd>
387:
388: <dt>WebIDL</dt>
389:
390: <dd>
391:
392: <p>The IDL blocks in this specification use the semantics of the
393: WebIDL specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
394:
395: </dd>
396:
397: </dl><h2 id="terminology"><span class="secno">2 </span>Terminology</h2><p>The construction "a <code title="">Foo</code> object", where
398: <code title="">Foo</code> is actually an interface, is sometimes
399: used instead of the more accurate "an object implementing the
400: interface <code title="">Foo</code>".<p>The term DOM is used to refer to the API set made available to
401: scripts in Web applications, and does not necessarily imply the
402: existence of an actual <code>Document</code> object or of any other
403: <code>Node</code> objects as defined in the DOM Core
404: specifications. <a href="#refsDOMCORE">[DOMCORE]</a><p>An IDL attribute is said to be <em>getting</em> when its value is
405: being retrieved (e.g. by author script), and is said to be
406: <em>setting</em> when a new value is assigned to it.<h2 id="event-definitions"><span class="secno">3 </span>Event definitions</h2><p>Messages in <span>server-sent events</span>, <span>Web
1.44 ihickson 407: sockets</span>, <a href="#web-messaging">cross-document messaging</a>, and
1.1 ihickson 408: <a href="#channel-messaging">channel messaging</a> use the <dfn id="event-message" title="event-message"><code>message</code></dfn> event.
409:
410: <a href="#refsEVENTSOURCE">[EVENTSOURCE]</a>
411: <a href="#refsWEBSOCKET">[WEBSOCKET]</a>
412:
1.17 ihickson 413: <p>The following interface is defined for this event:<pre class="idl">interface <dfn id="messageevent">MessageEvent</dfn> : <span>Event</span> {
1.1 ihickson 414: readonly attribute any <a href="#dom-messageevent-data" title="dom-MessageEvent-data">data</a>;
415: readonly attribute DOMString <a href="#dom-messageevent-origin" title="dom-MessageEvent-origin">origin</a>;
416: readonly attribute DOMString <a href="#dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId">lastEventId</a>;
1.87 ihickson 417: readonly attribute <span>WindowProxy</span>? <a href="#dom-messageevent-source" title="dom-MessageEvent-source">source</a>;
1.84 ihickson 418: readonly attribute <a href="#messageport">MessagePort</a>[] <a href="#dom-messageevent-ports" title="dom-MessageEvent-ports">ports</a>;
1.95 ! ihickson 419: void <a href="#dom-messageevent-initmessageevent" title="dom-MessageEvent-initMessageEvent">initMessageEvent</a>(DOMString typeArg, boolean canBubbleArg, boolean cancelableArg, any dataArg, DOMString originArg, DOMString lastEventIdArg, <span>WindowProxy</span>? sourceArg, sequence<<a href="#messageport">MessagePort</a>> portsArg);
1.1 ihickson 420: };</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code></dt>
421:
422: <dd>
423:
424: <p>Returns the data of the message.</p>
425:
426: </dd>
427:
428: <dt><var title="">event</var> . <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code></dt>
429:
430: <dd>
431:
432: <p>Returns the origin of the message, for <span>server-sent
1.44 ihickson 433: events</span> and <a href="#web-messaging">cross-document messaging</a>.</p>
1.1 ihickson 434:
435: </dd>
436:
437: <dt><var title="">event</var> . <code title="dom-MessageEvent-lastEventId"><a href="#dom-messageevent-lasteventid">lastEventId</a></code></dt>
438:
439: <dd>
440:
1.74 ihickson 441: <p>Returns the <span title="concept-event-stream-last-event-id">last event ID
442: string</span>, for <span>server-sent events</span>.</p>
1.1 ihickson 443:
444: </dd>
445:
446: <dt><var title="">event</var> . <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code></dt>
447:
448: <dd>
449:
450: <p>Returns the <code>WindowProxy</code> of the source window, for
1.44 ihickson 451: <a href="#web-messaging">cross-document messaging</a>.</p>
1.1 ihickson 452:
453: </dd>
454:
455: <dt><var title="">event</var> . <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code></dt>
456:
457: <dd>
458:
1.84 ihickson 459: <p>Returns the <code><a href="#messageport">MessagePort</a></code> array sent with the
1.44 ihickson 460: message, for <a href="#web-messaging">cross-document messaging</a> and
1.1 ihickson 461: <a href="#channel-messaging">channel messaging</a>.</p>
462:
463: </dd>
464:
465: </dl><div class="impl">
466:
467: <p>The <dfn id="dom-messageevent-initmessageevent" title="dom-MessageEvent-initMessageEvent"><code>initMessageEvent()</code></dfn>
468: method must initialize the event in a manner analogous to the
469: similarly-named method in the DOM Events interfaces. <a href="#refsDOMEVENTS">[DOMEVENTS]</a></p>
470:
471: <p>The <dfn id="dom-messageevent-data" title="dom-MessageEvent-data"><code>data</code></dfn>
472: attribute represents the message being sent.</p>
473:
474: <p>The <dfn id="dom-messageevent-origin" title="dom-MessageEvent-origin"><code>origin</code></dfn> attribute
475: represents, in <span>server-sent events</span> and
1.44 ihickson 476: <a href="#web-messaging">cross-document messaging</a>, the <span>origin</span> of
1.1 ihickson 477: the document that sent the message (typically the scheme, hostname,
478: and port of the document, but not its path or fragment
479: identifier).</p>
480:
481: <p>The <dfn id="dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId"><code>lastEventId</code></dfn>
482: attribute represents, in <span>server-sent events</span>, the <span title="concept-event-stream-last-event-id">last event ID
483: string</span> of the event source.</p>
484:
485: <p>The <dfn id="dom-messageevent-source" title="dom-MessageEvent-source"><code>source</code></dfn> attribute
1.44 ihickson 486: represents, in <a href="#web-messaging">cross-document messaging</a>, the
1.1 ihickson 487: <code>WindowProxy</code> of the <span>browsing context</span> of the
488: <code>Window</code> object from which the message came.</p>
489:
490: <p>The <dfn id="dom-messageevent-ports" title="dom-MessageEvent-ports"><code>ports</code></dfn>
1.44 ihickson 491: attribute represents, in <a href="#web-messaging">cross-document messaging</a> and
1.84 ihickson 492: <a href="#channel-messaging">channel messaging</a> the <code><a href="#messageport">MessagePort</a></code> array
1.1 ihickson 493: being sent, if any.</p>
494:
495: <p>Except where otherwise specified, when the user agent creates and
496: dispatches a <code title="event-message"><a href="#event-message">message</a></code> event in the
497: algorithms described in the following sections, the <code title="dom-MessageEvent-lastEventId"><a href="#dom-messageevent-lasteventid">lastEventId</a></code> attribute
498: must be the empty string, the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute must be the
499: empty string, the <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code> attribute must be
500: null, and the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code>
501: attribute must be null.</p>
502:
1.72 ihickson 503: </div><h2 id="web-messaging"><span class="secno">4 </span><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h2><p>Web browsers, for security and privacy reasons, prevent documents
1.1 ihickson 504: in different domains from affecting each other; that is, cross-site
505: scripting is disallowed.<p>While this is an important security feature, it prevents pages
506: from different domains from communicating even when those pages are
507: not hostile. This section introduces a messaging system that allows
508: documents to communicate with each other regardless of their source
509: domain, in a way designed to not enable cross-site scripting
510: attacks.<div class="impl">
511:
1.44 ihickson 512: <p>The <span>task source</span> for the <span title="concept-task">tasks</span> in <a href="#web-messaging">cross-document
1.1 ihickson 513: messaging</a> is the <dfn id="posted-message-task-source">posted message task source</dfn>.</p>
514:
1.72 ihickson 515: </div><h3 id="introduction"><span class="secno">4.1 </span>Introduction</h3><p><i>This section is non-normative.</i><div class="example">
1.1 ihickson 516:
517: <p>For example, if document A contains an <code>iframe</code>
518: element that contains document B, and script in document A calls
1.35 ihickson 519: <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> on the
1.1 ihickson 520: <code>Window</code> object of document B, then a message event will
521: be fired on that object, marked as originating from the
522: <code>Window</code> of document A. The script in document A might
523: look like:</p>
524:
525: <pre>var o = document.getElementsByTagName('iframe')[0];
526: o.contentWindow.postMessage('Hello world', 'http://b.example.org/');</pre>
527:
528: <p>To register an event handler for incoming events, the script
529: would use <code title="">addEventListener()</code> (or similar
530: mechanisms). For example, the script in document B might look
531: like:</p>
532:
533: <pre>window.addEventListener('message', receiver, false);
534: function receiver(e) {
535: if (e.origin == 'http://example.com') {
536: if (e.data == 'Hello world') {
537: e.source.postMessage('Hello', e.origin);
538: } else {
539: alert(e.data);
540: }
541: }
542: }</pre>
543:
544: <p>This script first checks the domain is the expected domain, and
545: then looks at the message, which it either displays to the user, or
546: responds to by sending a message back to the document which sent
547: the message in the first place.</p>
548:
1.72 ihickson 549: </div><h3 id="security-postmsg"><span class="secno">4.2 </span>Security</h3><div class="impl">
1.1 ihickson 550:
1.72 ihickson 551: <h4 id="authors"><span class="secno">4.2.1 </span>Authors</h4>
1.1 ihickson 552:
1.28 ihickson 553: </div><p class="warning" id="security-4">Use of this API requires extra
554: care to protect users from hostile entities abusing a site for their
555: own purposes.<p>Authors should check the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute to ensure
1.1 ihickson 556: that messages are only accepted from domains that they expect to
557: receive messages from. Otherwise, bugs in the author's message
558: handling code could be exploited by hostile sites.<p>Furthermore, even after checking the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute, authors
559: should also check that the data in question is of the expected
560: format. Otherwise, if the source of the event has been attacked
561: using a cross-site scripting flaw, further unchecked processing of
1.35 ihickson 562: information sent using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method could
1.1 ihickson 563: result in the attack being propagated into the receiver.<p>Authors should not use the wildcard keyword (*) in the <var title="">targetOrigin</var> argument in messages that contain any
564: confidential information, as otherwise there is no way to guarantee
565: that the message is only delivered to the recipient to which it was
566: intended.<div class="impl">
567:
1.72 ihickson 568: <h4 id="user-agents"><span class="secno">4.2.2 </span>User agents</h4>
1.1 ihickson 569:
570: <p>The integrity of this API is based on the inability for scripts
571: of one <span>origin</span> to post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in other
572: origins (those that are not the <span title="same
573: origin">same</span>).</p>
574:
575: <p class="note">Implementors are urged to take extra care in the
576: implementation of this feature. It allows authors to transmit
577: information from one domain to another domain, which is normally
578: disallowed for security reasons. It also requires that UAs be
579: careful to allow access to certain properties but not others.</p>
580:
1.88 ihickson 581: </div><h3 id="posting-messages"><span class="secno">4.3 </span>Posting messages</h3><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 582:
583: <dd>
584:
1.88 ihickson 585: <p>Posts a message to the given window. Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning
586: that they are no longer usable on the sending side.</p>
1.1 ihickson 587:
588: <p>If the origin of the target window doesn't match the given
589: origin, the message is discarded, to avoid information leakage. To
590: send the message to the target regardless of origin, set the
1.11 ihickson 591: target origin to "<code title="">*</code>". To restrict the
592: message to same-origin targets only, without needing to explicitly
1.72 ihickson 593: state the origin, set the target origin to "<code title="">/</code>".</p>
1.1 ihickson 594:
1.88 ihickson 595: <p>Throws a <code>DATA_CLONE_ERR</code> if <var title="">transfer</var> array contains duplicate objects or if
596: <var title="">message</var> could not be cloned.</p>
1.1 ihickson 597:
598: </dd>
599:
1.54 ihickson 600: </dl><p class="note">When posting a message to a <code>Window</code> of a
601: <span>browsing context</span> that has just been navigated to a new
602: <code>Document</code> is likely to result in the message not
603: receiving its intended recipient: the scripts in the target
604: <span>browsing context</span> have to have had time to set up
605: listeners for the messages. Thus, for instance, in situations where
606: a message is to be sent to the <code>Window</code> of newly created
607: child <code>iframe</code>, authors are advised to have the child
608: <code>Document</code> post a message to their parent announcing
609: their readiness to receive messages, and for the parent to wait for
610: this message before beginning posting messages.<div class="impl">
1.1 ihickson 611:
1.88 ihickson 612: <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
1.1 ihickson 613: arguments) on a <code>Window</code> object, the user agent must
1.88 ihickson 614: follow these steps:</p>
1.1 ihickson 615:
616: <ol><li>
617:
618: <p>If the value of the <var title="">targetOrigin</var> argument
1.72 ihickson 619: is neither a single U+002A ASTERISK character (*), a single U+002F
620: SOLIDUS character (/), nor an <span>absolute URL</span>, then
621: throw a <code>SYNTAX_ERR</code> exception and abort the overall
622: set of steps.</p>
1.1 ihickson 623:
624: </li>
625:
626: <li>
627:
1.88 ihickson 628: <p>Let <var title="">new ports</var> be an empty array.</p>
1.1 ihickson 629:
630: </li>
631:
632: <li>
633:
1.88 ihickson 634: <p>Let <var title="">transfer map</var> be an empty association
635: list of pairs of <code>Transferable</code> objects.</p>
1.1 ihickson 636:
637: </li>
638:
639: <li>
640:
1.88 ihickson 641: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these substeps:</p>
642:
643: <ol><li>
644:
645: <p>If any object is listed in <var title="">transfer</var> more
646: than once, or any of the <code>Transferable</code> objects
647: listed in <var title="">transfer</var> have already been <span title="transfer a Transferable object">transfered</span> once
648: before, then throw a <code>DATA_CLONE_ERR</code> exception and
649: abort these steps.</p>
650:
651: </li>
652:
653: <li>
654:
655: <p>If the <var title="">transfer</var> argument is present, then
656: for each object in <var title="">transfer</var> in turn, obtain
657: a new object by <span title="transfer a Transferable
658: object">transferring</span> the object to the
659: <code>Window</code> object on which the method was invoked, and
660: add a mapping from the old object to the new transferred object
661: to <var title="">transfer map</var>. If the objects are
662: <code><a href="#messageport">MessagePort</a></code> objects, also append the new
663: transferred object to the <var title="">new ports</var>
664: array.</p>
665:
666: </li>
667:
668: </ol></li>
669:
670: <li>
1.1 ihickson 671:
1.88 ihickson 672: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span> array.</p>
1.1 ihickson 673:
674: </li>
675:
676: <li>
677:
1.88 ihickson 678: <p>Let <var title="">message clone</var> be the result of
679: obtaining a <span>structured clone</span> of the <var title="">message</var> argument, with <var title="">transfer
680: map</var> as the <i>transfer map</i>. If this throws an exception,
681: then throw that exception and abort these steps.</p>
1.84 ihickson 682:
683: </li>
684:
685: <li>
686:
1.35 ihickson 687: <p>Return from the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method, but
1.1 ihickson 688: asynchronously continue running these steps.</p>
689:
690: </li>
691:
692: <li>
693:
1.72 ihickson 694: <p>If the <var title="">targetOrigin</var> argument is a single
695: literal U+002F SOLIDUS character (/), and the
696: <code>Document</code> of the <code>Window</code> object on which
697: the method was invoked does not have the <span>same origin</span>
698: as the <span>entry script</span>'s <span title="script's
699: document">document</span>, then abort these steps silently.</p>
700:
1.11 ihickson 701: <p>Otherwise, if the <var title="">targetOrigin</var> argument is
702: an <span>absolute URL</span>, and the <code>Document</code> of the
703: <code>Window</code> object on which the method was invoked does
704: not have the <span>same origin</span> as <var title="">targetOrigin</var>, then abort these steps silently.</p>
705:
706: <p>Otherwise, the <var title="">targetOrigin</var> argument is a
707: single literal U+002A ASTERISK character (*), and no origin check
708: is made.</p>
1.1 ihickson 709:
710: </li>
711:
712: <li>
713:
714: <p>Create an event that uses the <code><a href="#messageevent">MessageEvent</a></code>
715: interface, with the event name <code title="event-message"><a href="#event-message">message</a></code>, which does not bubble, is
716: not cancelable, and has no default action. The <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute must be set to
717: 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
718: set to the <span title="Unicode serialization of an
719: origin">Unicode serialization</span> of the <span>origin</span> of
1.35 ihickson 720: the script that invoked the method, the <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code> attribute must be
1.25 ihickson 721: set to the <span>script's global object</span>'s
1.35 ihickson 722: <code>WindowProxy</code> object, and the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code> attribute must be set
1.79 ihickson 723: to the <var title="">new ports</var> array.</p>
1.1 ihickson 724: </li>
725:
726: <li>
727:
728: <p><span>Queue a task</span> to dispatch the event created in the
729: previous step at the <code>Window</code> object on which the
730: method was invoked. The <span>task source</span> for this <span title="concept-task">task</span> is the <a href="#posted-message-task-source">posted message task
731: source</a>.</p>
732:
733: </li>
734:
1.72 ihickson 735: </ol></div><h2 id="channel-messaging"><span class="secno">5 </span><dfn>Channel messaging</dfn></h2><h3 id="introduction-0"><span class="secno">5.1 </span>Introduction</h3><p><i>This section is non-normative.</i><p>To enable independent pieces of code (e.g. running in different
1.1 ihickson 736: <span title="browsing context">browsing contexts</span>) to
737: communicate directly, authors can use <a href="#channel-messaging">channel
738: messaging</a>.<p>Communication channels in this mechanisms are implemented as
739: two-ways pipes, with a port at each end. Messages sent in one port
740: are delivered at the other port, and vice-versa. Messages are
741: asynchronous, and delivered as DOM events.<p>To create a connection (two "entangled" ports), the <code title="">MessageChannel()</code> constructor is called:<pre>var channel = new MessageChannel();</pre><p>One of the ports is kept as the local port, and the other port is
1.35 ihickson 742: sent to the remote code, e.g. using <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code>:<pre>otherWindow.postMessage('hello', 'http://example.com', [channel.port2]);</pre><p>To send messages, the <code title="dom-MessagePort-postMessage"><a href="#dom-messageport-postmessage">postMessage()</a></code> method on
1.1 ihickson 743: the port is used:<pre>channel.port1.postMessage('hello');</pre><p>To receive messages, one listens to <code title="event-message"><a href="#event-message">message</a></code> events:<pre>channel.port1.onmessage = handleMessage;
744: function handleMessage(event) {
745: // message is in event.data
746: // ...
1.72 ihickson 747: }</pre><h3 id="message-channels"><span class="secno">5.2 </span>Message channels</h3><pre class="idl">[<a href="#dom-messagechannel" title="dom-MessageChannel">Constructor</a>]
1.1 ihickson 748: interface <dfn id="messagechannel">MessageChannel</dfn> {
749: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port1" title="dom-channel-port1">port1</a>;
750: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port2" title="dom-channel-port2">port2</a>;
751: };</pre><dl class="domintro"><dt><var title="">channel</var> = new <code title="dom-MessageChannel"><a href="#dom-messagechannel">MessageChannel</a></code>()</dt>
752:
753: <dd>
754:
755: <p>Returns a new <code><a href="#messagechannel">MessageChannel</a></code> object with two new <code><a href="#messageport">MessagePort</a></code> objects.</p>
756:
757: </dd>
758:
759: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port1">port1</code></dt>
760:
761: <dd>
762:
763: <p>Returns the first <code><a href="#messageport">MessagePort</a></code> object.</p>
764:
765: </dd>
766:
767: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port2">port2</code></dt>
768:
769: <dd>
770:
771: <p>Returns the second <code><a href="#messageport">MessagePort</a></code> object.</p>
772:
773: </dd>
774:
775: </dl><div class="impl">
776:
777: <p>When the <dfn id="dom-messagechannel" title="dom-MessageChannel"><code>MessageChannel()</code></dfn>
778: constructor is called, it must run the following algorithm:</p>
779:
780: <ol><li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a>
781: owned by the <span>script's global object</span>, and let <var title="">port1</var> be that object.</li>
782:
783: <li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a>
784: owned by the <span>script's global object</span>, and let <var title="">port2</var> be that object.</li>
785:
786: <li><p><a href="#entangle">Entangle</a> the <var title="">port1</var> and <var title="">port2</var> objects.</li>
787:
788: <li><p>Instantiate a new <code><a href="#messagechannel">MessageChannel</a></code> object, and
789: let <var title="">channel</var> be that object.</li>
790:
791: <li><p>Let the <code title="dom-channel-port1"><a href="#dom-channel-port1">port1</a></code>
792: attribute of the <var title="">channel</var> object be <var title="">port1</var>.</p>
793:
794: <li><p>Let the <code title="dom-channel-port2"><a href="#dom-channel-port2">port2</a></code>
795: attribute of the <var title="">channel</var> object be <var title="">port2</var>.</p>
796:
797: <li><p>Return <var title="">channel</var>.</li>
798:
799: </ol><p>This constructor must be visible when the <span>script's global
800: object</span> is either a <code>Window</code> object or an object
801: implementing the <code>WorkerUtils</code> interface.</p>
802:
803: <p>The <dfn id="dom-channel-port1" title="dom-channel-port1"><code>port1</code></dfn> and
804: <dfn id="dom-channel-port2" title="dom-channel-port2"><code>port2</code></dfn> attributes
805: must return the values they were assigned when the
806: <code><a href="#messagechannel">MessageChannel</a></code> object was created.</p>
807:
1.72 ihickson 808: </div><h3 id="message-ports"><span class="secno">5.3 </span>Message ports</h3><p>Each channel has two message ports. Data sent through one port is
1.92 ihickson 809: received by the other port, and vice versa.<pre class="idl">interface <dfn id="messageport">MessagePort</dfn> : <span>EventTarget</span> {
1.95 ! ihickson 810: void <a href="#dom-messageport-postmessage" title="dom-MessagePort-postMessage">postMessage</a>(any message, optional sequence<<span>Transferable</span>> transfer); void <a href="#dom-messageport-start" title="dom-MessagePort-start">start</a>();
1.1 ihickson 811: void <a href="#dom-messageport-close" title="dom-MessagePort-close">close</a>();
812:
813: // event handlers
1.87 ihickson 814: attribute <span>Function</span>? <a href="#handler-messageport-onmessage" title="handler-MessagePort-onmessage">onmessage</a>;
1.1 ihickson 815: };
1.88 ihickson 816: <a href="#messageport">MessagePort</a> implements <span>Transferable</span>;</pre><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 817:
818: <dd>
819:
1.88 ihickson 820: <p>Posts a message through the channel. Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning
821: that they are no longer usable on the sending side.</p>
1.1 ihickson 822:
1.88 ihickson 823: <p>Throws a <code>DATA_CLONE_ERR</code> if <var title="">transfer</var> array contains duplicate objects or the
824: source or target ports, or if <var title="">message</var> could
825: not be cloned.</p>
1.1 ihickson 826:
827: </dd>
828:
829: <dt><var title="">port</var> . <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start</a></code>()</dt>
830:
831: <dd>
832:
833: <p>Begins dispatching messages received on the port.</p>
834:
835: </dd>
836:
837: <dt><var title="">port</var> . <code title="dom-MessagePort-close"><a href="#dom-messageport-close">close</a></code>()</dt>
838:
839: <dd>
840:
841: <p>Disconnects the port, so that it is no longer active.</p>
842:
843: </dd>
844:
845: </dl><div class="impl">
846:
847: <p>Each <code><a href="#messageport">MessagePort</a></code> object can be entangled with
848: another (a symmetric relationship). Each <code><a href="#messageport">MessagePort</a></code>
849: object also has a <span>task source</span> called the <dfn id="port-message-queue">port
850: message queue</dfn>, initial empty. A <a href="#port-message-queue">port message
851: queue</a> can be enabled or disabled, and is initially
852: disabled. Once enabled, a port can never be disabled again (though
853: messages in the queue can get moved to another queue or removed
854: altogether, which has much the same effect).</p>
855:
856: <p>When the user agent is to <dfn id="create-a-new-messageport-object">create a new
857: <code>MessagePort</code> object</dfn> owned by a <span>script's
858: global object</span> object <var title="">owner</var>, it must
859: instantiate a new <code><a href="#messageport">MessagePort</a></code> object, and let its owner
860: be <var title="">owner</var>.</p>
861:
1.88 ihickson 862: <p>When the user agent is to <dfn id="entangle">entangle</dfn> two
1.1 ihickson 863: <code><a href="#messageport">MessagePort</a></code> objects, it must run the following
864: steps:</p>
865:
866: <ol><li>
867:
868: <p>If one of the ports is already entangled, then disentangle it
869: and the port that it was entangled with.</p>
870:
871: <p class="note">If those two previously entangled ports were the
872: two ports of a <code><a href="#messagechannel">MessageChannel</a></code> object, then that
873: <code><a href="#messagechannel">MessageChannel</a></code> object no longer represents an actual
874: channel: the two ports in that object are no longer entangled.</p>
875:
876: </li>
877:
878: <li><p>Associate the two ports to be entangled, so that they form
879: the two parts of a new channel. (There is no
880: <code><a href="#messagechannel">MessageChannel</a></code> object that represents this
881: channel.)</li>
882:
1.88 ihickson 883: </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 884: a new <code><a href="#messageport">MessagePort</a></code> object. These steps must be run
885: atomically.</p>
886:
887: <ol><li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a>
888: owned by <var title="">owner</var>, and let <var title="">new
889: port</var> be that object.</li>
890:
891: <li><p>Move all the events in the <a href="#port-message-queue">port message queue</a>
892: of <var title="">original port</var> to the <a href="#port-message-queue">port message
893: queue</a> of <var title="">new port</var>, if any, leaving the
894: <var title="">new port</var>'s <a href="#port-message-queue">port message queue</a> in
895: its initial disabled state.</li>
896:
897: <li>
898:
899: <p>If the <var title="">original port</var> is entangled with
900: another port, then run these substeps:</p>
901:
902: <ol><li><p>Let the <var title="">remote port</var> be the port with
903: which the <var title="">original port</var> is entangled.</li>
904:
905: <li><p><a href="#entangle">Entangle</a> the <var title="">remote port</var>
906: and <var title="">new port</var> objects. The <var title="">original port</var> object will be disentangled by this
907: process.</li>
908:
909: </ol></li>
910:
911: <li><p>Return <var title="">new port</var>. It is the
912: clone.</li>
913:
1.88 ihickson 914: </ol><p id="transferMessagePort">To <span title="transfer a Transferable
915: 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
916: agent must <a href="#clone-a-port" title="clone a port">clone</a> the <var title="">old</var> object with the cloned being owned by <var title="">owner</var>, and must return the resulting object.</p>
917:
918: <hr><p>The <dfn id="dom-messageport-postmessage" title="dom-MessagePort-postMessage"><code>postMessage()</code></dfn>
1.1 ihickson 919: method, when called on a port <var title="">source port</var>, must
920: cause the user agent to run the following steps:</p>
921:
922: <ol><li><p>Let <var title="">target port</var> be the port with which
923: <var title="">source port</var> is entangled, if any.</li>
924:
1.88 ihickson 925: <li><p>Let <var title="">new owner</var> be the owner of <var title="">target port</var>, if there is a <var title="">target
926: port</var>, or else some arbitrary owner. (This <var title="">new
927: owner</var> is used when transfering objects below. If there is no
928: <var title="">target port</var>, the <code>Transferable</code>
929: objects given in the second argument, if any, are still <span title="transfer a Transferable object">transfered</span>, but since
930: they are then discarded, it doesn't matter where they are
931: transfered to.)</li>
1.1 ihickson 932:
1.88 ihickson 933: <li>
934:
935: <p>Let <var title="">new ports</var> be an empty array.</p>
936:
937: </li>
938:
939: <li>
1.1 ihickson 940:
1.88 ihickson 941: <p>Let <var title="">transfer map</var> be an empty association
942: list of pairs of <code>Transferable</code> objects.</p>
1.1 ihickson 943:
1.88 ihickson 944: </li>
1.1 ihickson 945:
1.88 ihickson 946: <li>
1.1 ihickson 947:
1.88 ihickson 948: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these substeps:</p>
1.1 ihickson 949:
950: <ol><li>
951:
1.88 ihickson 952: <p>If any object is listed in <var title="">transfer</var> more
953: than once, or any of the <code>Transferable</code> objects
954: listed in <var title="">transfer</var> have already been <span title="transfer a Transferable object">transfered</span> once
955: before, then throw a <code>DATA_CLONE_ERR</code> exception and
956: abort these steps.</p>
1.1 ihickson 957:
1.88 ihickson 958: </li>
1.1 ihickson 959:
1.88 ihickson 960: <li>
961:
962: <p>If any of the objects in <var title="">transfer</var> are
963: either the <var title="">source port</var> or the <var title="">target port</var> (if any), then throw a
964: <code>DATA_CLONE_ERR</code> exception and abort these
1.89 ihickson 965: steps.</p>
1.88 ihickson 966:
1.89 ihickson 967: </li>
1.1 ihickson 968:
1.84 ihickson 969: <li>
970:
1.88 ihickson 971: <p>If the <var title="">transfer</var> argument is present, then
972: for each object in <var title="">transfer</var> in turn, obtain
973: a new object by <span title="transfer a Transferable
974: object">transferring</span> the object to <var title="">new
975: owner</var>, and add a mapping from the old object to the new
976: transferred object to <var title="">transfer map</var>. If the
977: objects are <code><a href="#messageport">MessagePort</a></code> objects, also append the
978: new transferred object to the <var title="">new ports</var>
979: array.</p>
1.84 ihickson 980:
981: </li>
982:
1.89 ihickson 983: </ol></li>
984:
985: <li>
1.1 ihickson 986:
1.88 ihickson 987: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span> array.</p>
988:
989: </li>
990:
991: <li><p>Let <var title="">message</var> be the method's first
992: argument.</li>
993:
994: <li>
995:
996: <p>Let <var title="">message clone</var> be the result of
997: obtaining a <span>structured clone</span> of the <var title="">message</var> argument, with <var title="">transfer
998: map</var> as the <i>transfer map</i>. If this throws an exception,
999: then throw that exception and abort these steps.</p>
1000:
1001: </li>
1002:
1003: <li><p>Create an event that uses the <code><a href="#messageevent">MessageEvent</a></code>
1004: interface, with the name <code title="event-message"><a href="#event-message">message</a></code>, which does not bubble, is not
1005: cancelable, and has no default action.</li>
1006:
1007: <li><p>Let the <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code>
1008: attribute of the event have the value of <var title="">message
1009: clone</var>.</li>
1010:
1011: <li><p>Let the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code>
1012: attribute of the event be the <var title="">new ports</var>
1013: array.</li>
1.1 ihickson 1014:
1.86 ihickson 1015: <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
1016: steps.</li>
1.1 ihickson 1017: <li><p>Add the event to the <a href="#port-message-queue">port message queue</a> of <var title="">target port</var>.</li>
1018:
1.89 ihickson 1019: </ol><hr><p>The <dfn id="dom-messageport-start" title="dom-MessagePort-start"><code>start()</code></dfn>
1.1 ihickson 1020: method must enable its port's <a href="#port-message-queue">port message queue</a>, if it
1021: is not already enabled.</p>
1022:
1023: <p>When a port's <a href="#port-message-queue">port message queue</a> is enabled, the
1024: <span>event loop</span> must use it as one of its <span title="task
1025: source">task sources</span>.</p>
1026:
1027: <p class="note">If the <code>Document</code> of the port's event
1028: listeners' <span title="script's global object">global object</span>
1029: is not <span>fully active</span>, then the messages are lost.</p>
1.79 ihickson 1030:
1.1 ihickson 1031:
1032: <hr><p>The <dfn id="dom-messageport-close" title="dom-MessagePort-close"><code>close()</code></dfn>
1033: method, when called on a port <var title="">local port</var> that is
1034: entangled with another port, must cause the user agents to
1035: disentangle the two ports. If the method is called on a port that is
1036: not entangled, then the method must do nothing.</p>
1037:
1038: <hr><p>The following are the <span>event handlers</span> (and their
1039: corresponding <span title="event handler event type">event handler
1040: event types</span>) that must be supported, as IDL attributes, by
1041: all objects implementing the <code><a href="#messageport">MessagePort</a></code> interface:</p>
1042:
1043: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1044: <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>
1045: </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
1046: is set, the port's <a href="#port-message-queue">port message queue</a> must be enabled,
1047: as if the <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method
1048: had been called.</p>
1049:
1.72 ihickson 1050: </div><h4 id="ports-and-garbage-collection"><span class="secno">5.3.1 </span>Ports and garbage collection</h4><div class="impl">
1.1 ihickson 1051:
1052: <p>When a <code><a href="#messageport">MessagePort</a></code> object <var title="">o</var> is
1053: entangled, user agents must either act as if <var title="">o</var>'s
1054: entangled <code><a href="#messageport">MessagePort</a></code> object has a strong reference to
1055: <var title="">o</var>, or as if <var title="">o</var>'s owner has a
1056: strong reference to <var title="">o</var>.</p>
1057:
1058: <div class="note">
1059:
1060: <p>Thus, a message port can be received, given an event listener,
1061: and then forgotten, and so long as that event listener could
1062: receive a message, the channel will be maintained.</p>
1063:
1064: <p>Of course, if this was to occur on both sides of the channel,
1065: then both ports could be garbage collected, since they would not be
1066: reachable from live code, despite having a strong reference to each
1067: other.</p>
1068:
1069: </div>
1070:
1071: <p>Furthermore, a <code><a href="#messageport">MessagePort</a></code> object must not be
1072: garbage collected while there exists a message in a <span>task
1073: queue</span> that is to be dispatched on that
1074: <code><a href="#messageport">MessagePort</a></code> object, or while the
1075: <code><a href="#messageport">MessagePort</a></code> object's <a href="#port-message-queue">port message queue</a> is
1076: open and there exists a <code title="event-message"><a href="#event-message">message</a></code>
1077: event in that queue.</p>
1.79 ihickson 1078:
1079:
1.1 ihickson 1080: </div><p class="note">Authors are strongly encouraged to explicitly close
1081: <code><a href="#messageport">MessagePort</a></code> objects to disentangle them, so that their
1082: resources can be recollected. Creating many <code><a href="#messageport">MessagePort</a></code>
1083: objects and discarding them without closing them can lead to high
1.79 ihickson 1084: memory usage.<h2 class="no-num" id="references">References</h2><p>All references are normative unless marked "Non-normative".</p><dl><dt id="refsDOMCORE">[DOMCORE]</dt>
1.75 ihickson 1085: <dd><cite><a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html">Web DOM Core</a></cite>, A. van Kesteren. W3C.</dd>
1.72 ihickson 1086:
1087: <dt id="refsDOMEVENTS">[DOMEVENTS]</dt>
1.79 ihickson 1088: <dd><cite><a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html">Document
1.1 ihickson 1089: Object Model (DOM) Level 3 Events Specification</a></cite>,
1.8 ihickson 1090: D. Schepers. W3C.</dd>
1.1 ihickson 1091:
1092: <dt id="refsEVENTSOURCE">[EVENTSOURCE]</dt>
1.79 ihickson 1093: <dd><cite><a href="http://dev.w3.org/html5/eventsource/">Server-Sent
1.8 ihickson 1094: Events</a></cite>, I. Hickson. W3C.</dd>
1.1 ihickson 1095:
1.72 ihickson 1096: <dt id="refsHTML">[HTML]</dt>
1097: <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML</a></cite>,
1098: I. Hickson. WHATWG.</dd>
1099:
1100: <dt id="refsRFC2119">[RFC2119]</dt>
1101: <dd><cite><a href="http://tools.ietf.org/html/rfc2119">Key words for use in
1102: RFCs to Indicate Requirement Levels</a></cite>, S. Bradner. IETF.</dd>
1.1 ihickson 1103:
1.55 ihickson 1104: <dt id="refsWEBIDL">[WEBIDL]</dt>
1.79 ihickson 1105: <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web
1.55 ihickson 1106: IDL</a></cite>, C. McCormack. W3C.</dd>
1107:
1.1 ihickson 1108: <dt id="refsWEBSOCKET">[WEBSOCKET]</dt>
1.79 ihickson 1109: <dd><cite><a href="http://dev.w3.org/html5/websockets/">The WebSocket
1.8 ihickson 1110: API</a></cite>, I. Hickson. W3C.</dd>
1.1 ihickson 1111:
1.72 ihickson 1112: </dl><h2 class="no-num" id="acknowledgements">Acknowledgements</h2><p>For a full list of acknowledgements, please see the HTML
1113: specification. <a href="#refsHTML">[HTML]</a>
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