You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1110 lines
69 KiB
1110 lines
69 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"><html lang="en-US-x-Hixie"><title>The WebSocket API</title><style type="text/css">
|
|
pre { margin-left: 2em; white-space: pre-wrap; }
|
|
h2 { margin: 3em 0 1em 0; }
|
|
h3 { margin: 2.5em 0 1em 0; }
|
|
h4 { margin: 2.5em 0 0.75em 0; }
|
|
h5, h6 { margin: 2.5em 0 1em; }
|
|
h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
|
|
h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
|
|
p { margin: 1em 0; }
|
|
hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
|
|
dl, dd { margin-top: 0; margin-bottom: 0; }
|
|
dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
|
|
dt + dt { margin-top: 0; }
|
|
dd dt { margin-top: 0.25em; margin-bottom: 0; }
|
|
dd p { margin-top: 0; }
|
|
dd dl + p { margin-top: 1em; }
|
|
dd table + p { margin-top: 1em; }
|
|
p + * > li, dd li { margin: 1em 0; }
|
|
dt, dfn { font-weight: bold; font-style: normal; }
|
|
i, em { font-style: italic; }
|
|
dt dfn { font-style: italic; }
|
|
pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
|
|
pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
|
|
pre em { font-weight: bolder; font-style: normal; }
|
|
@media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
|
|
var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
|
|
table { border-collapse: collapse; border-style: hidden hidden none hidden; }
|
|
table thead, table tbody { border-bottom: solid; }
|
|
table tbody th:first-child { border-left: solid; }
|
|
table tbody th { text-align: left; }
|
|
table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
|
|
blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
|
|
|
|
.bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
|
|
.matrix, .matrix td { border: none; text-align: right; }
|
|
.matrix { margin-left: 2em; }
|
|
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
|
|
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
|
|
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
|
|
|
|
.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
|
|
img.extra, p.overview { float: right; }
|
|
pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
|
|
pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
|
|
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 }
|
|
pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
|
|
pre.css:first-line { color: #AAAA50; }
|
|
dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
|
|
hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
|
|
dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
|
|
dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
|
|
dl.domintro dd p { margin: 0.5em 0; }
|
|
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; }
|
|
dl.switch { padding-left: 2em; }
|
|
dl.switch > dt { text-indent: -1.5em; }
|
|
dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
|
|
dl.triple { padding: 0 0 0 1em; }
|
|
dl.triple dt, dl.triple dd { margin: 0; display: inline }
|
|
dl.triple dt:after { content: ':'; }
|
|
dl.triple dd:after { content: '\A'; white-space: pre; }
|
|
.diff-old { text-decoration: line-through; color: silver; background: transparent; }
|
|
.diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
|
|
a .diff-new { border-bottom: 1px blue solid; }
|
|
|
|
h2 { page-break-before: always; }
|
|
h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
|
|
h1 + h2, hr + h2.no-toc { page-break-before: auto; }
|
|
|
|
p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
|
|
li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]) { border-bottom: solid #9999CC; }
|
|
|
|
div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
|
|
div.head p { margin: 0; }
|
|
div.head h1 { margin: 0; }
|
|
div.head .logo { float: right; margin: 0 1em; }
|
|
div.head .logo img { border: none } /* remove border from top image */
|
|
div.head dl { margin: 1em 0; }
|
|
div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
|
|
|
|
body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
|
|
body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
|
|
body > .toc > li > * { margin-bottom: 0.5em; }
|
|
body > .toc > li > * > li > * { margin-bottom: 0.25em; }
|
|
.toc, .toc li { list-style: none; }
|
|
|
|
.brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
|
|
.brief li { margin: 0; padding: 0; }
|
|
.brief li p { margin: 0; padding: 0; }
|
|
|
|
.category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
|
|
.category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
|
|
.category-list li { display: inline; }
|
|
.category-list li:not(:last-child)::after { content: ', '; }
|
|
.category-list li > span, .category-list li > a { text-transform: lowercase; }
|
|
.category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
|
|
|
|
.XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
|
|
.XXX > :first-child { margin-top: 0; }
|
|
p .XXX { line-height: 3em; }
|
|
.annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
|
|
.annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
|
|
.annotation :link, .annotation :visited { color: inherit; }
|
|
.annotation :link:hover, .annotation :visited:hover { background: transparent; }
|
|
.annotation span { border: none ! important; }
|
|
.note { color: green; background: transparent; font-family: sans-serif; }
|
|
.warning { color: red; background: transparent; }
|
|
.note, .warning { font-weight: bolder; font-style: italic; }
|
|
.note em, .warning em, .note i, .warning i { font-style: normal; }
|
|
p.note, div.note { padding: 0.5em 2em; }
|
|
span.note { padding: 0 2em; }
|
|
.note p:first-child, .warning p:first-child { margin-top: 0; }
|
|
.note p:last-child, .warning p:last-child { margin-bottom: 0; }
|
|
.warning:before { font-style: normal; }
|
|
p.note:before { content: 'Note: '; }
|
|
p.warning:before { content: '\26A0 Warning! '; }
|
|
|
|
.bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
|
|
.bookkeeping { font-size: 0.8em; margin: 2em 0; }
|
|
.bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
|
|
.bookkeeping dt { margin: 0.5em 2em 0; }
|
|
.bookkeeping dd { margin: 0 3em 0.5em; }
|
|
|
|
h4 { position: relative; z-index: 3; }
|
|
h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
|
|
.element {
|
|
background: #EEEEFF;
|
|
color: black;
|
|
margin: 0 0 1em 0.15em;
|
|
padding: 0 1em 0.25em 0.75em;
|
|
border-left: solid #9999FF 0.25em;
|
|
position: relative;
|
|
z-index: 1;
|
|
}
|
|
.element:before {
|
|
position: absolute;
|
|
z-index: 2;
|
|
top: 0;
|
|
left: -1.15em;
|
|
height: 2em;
|
|
width: 0.9em;
|
|
background: #EEEEFF;
|
|
content: ' ';
|
|
border-style: none none solid solid;
|
|
border-color: #9999FF;
|
|
border-width: 0.25em;
|
|
}
|
|
|
|
.example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
|
|
td > .example:only-child { margin: 0 0 0 0.1em; }
|
|
|
|
ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
|
|
ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
|
|
ul.domTree li li { list-style: none; }
|
|
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; }
|
|
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; }
|
|
ul.domTree span { font-style: italic; font-family: serif; }
|
|
ul.domTree .t1 code { color: purple; font-weight: bold; }
|
|
ul.domTree .t2 { font-style: normal; font-family: monospace; }
|
|
ul.domTree .t2 .name { color: black; font-weight: bold; }
|
|
ul.domTree .t2 .value { color: blue; font-weight: normal; }
|
|
ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
|
|
ul.domTree .t7 code, .domTree .t8 code { color: green; }
|
|
ul.domTree .t10 code { color: teal; }
|
|
|
|
body.dfnEnabled dfn { cursor: pointer; }
|
|
.dfnPanel {
|
|
display: inline;
|
|
position: absolute;
|
|
z-index: 10;
|
|
height: auto;
|
|
width: auto;
|
|
padding: 0.5em 0.75em;
|
|
font: small sans-serif, Droid Sans Fallback;
|
|
background: #DDDDDD;
|
|
color: black;
|
|
border: outset 0.2em;
|
|
}
|
|
.dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
|
|
.dfnPanel :link, .dfnPanel :visited { color: black; }
|
|
.dfnPanel p { font-weight: bolder; }
|
|
.dfnPanel * + p { margin-top: 0.25em; }
|
|
.dfnPanel li { list-style-position: inside; }
|
|
|
|
#configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
|
|
#configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
|
|
#configUI p label { display: block; }
|
|
#configUI #updateUI, #configUI .loginUI { text-align: center; }
|
|
#configUI input[type=button] { display: block; margin: auto; }
|
|
|
|
fieldset { margin: 1em; padding: 0.5em 1em; }
|
|
fieldset > legend + * { margin-top: 0; }
|
|
fieldset > :last-child { margin-bottom: 0; }
|
|
fieldset p { margin: 0.5em 0; }
|
|
|
|
</style><link href="http://www.w3.org/StyleSheets/TR/W3C-CR" rel="stylesheet" type="text/css"><script type="text/javascript">
|
|
function getCookie(name) {
|
|
var params = location.search.substr(1).split("&");
|
|
for (var index = 0; index < params.length; index++) {
|
|
if (params[index] == name)
|
|
return "1";
|
|
var data = params[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
var cookies = document.cookie.split("; ");
|
|
for (var index = 0; index < cookies.length; index++) {
|
|
var data = cookies[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
return null;
|
|
}
|
|
</script><div class="head" id="head">
|
|
<p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
|
|
|
|
<h1>The WebSocket API</h1>
|
|
|
|
<h2 class="no-num no-toc" id="cr-december-2011">W3C Candidate Recommendation 08 December 2011</h2>
|
|
<dl>
|
|
<dt>This Version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/2011/CR-websockets-20111208/">http://www.w3.org/TR/2011/CR-websockets-20111208/</a></dd>
|
|
<dt>Latest Published Version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/websockets/">http://www.w3.org/TR/websockets/</a></dd>
|
|
<dt>Latest Editor's Draft:</dt>
|
|
<dd><a class="latest-link" href="http://dev.w3.org/html5/websockets/">http://dev.w3.org/html5/websockets/</a></dd>
|
|
|
|
<dt>Previous Versions:</dt>
|
|
<dd><a href="http://www.w3.org/TR/2011/WD-websockets-20110929/">http://www.w3.org/TR/2011/WD-websockets-20110929/</a></dd>
|
|
<dd><a href="http://www.w3.org/TR/2011/WD-websockets-20110419/">http://www.w3.org/TR/2011/WD-websockets-20110419/</a></dd>
|
|
<dd><a href="http://www.w3.org/TR/2009/WD-websockets-20091222/">http://www.w3.org/TR/2009/WD-websockets-20091222/</a></dd>
|
|
<dd><a href="http://www.w3.org/TR/2009/WD-websockets-20090423/">http://www.w3.org/TR/2009/WD-websockets-20090423/</a></dd>
|
|
<dd><a href="http://www.w3.org/TR/2009/WD-websockets-20091029/">http://www.w3.org/TR/2009/WD-websockets-20091029/</a></dd>
|
|
<!-- :ZZZ -->
|
|
<dt>Editor:</dt>
|
|
<dd><a href="mailto:ian@hixie.ch">Ian Hickson</a>, Google, Inc.</dd>
|
|
</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
|
|
© 2011 <a href="http://www.w3.org/"><abbr title="World Wide
|
|
Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts
|
|
Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research
|
|
Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C
|
|
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
|
|
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
|
|
and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document
|
|
use</a> rules apply.</p>
|
|
|
|
|
|
<!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
|
|
<p class="alt">The bulk of the text of this specification is also
|
|
available in the WHATWG <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html#network">Web Applications 1.0</a> specification, under a license that permits
|
|
reuse of the specification text.</p>
|
|
<!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
|
|
|
|
|
|
</div><hr class="top"><h2 class="no-num no-toc" id="abstract">Abstract</h2><p>This specification defines an API that enables Web pages to use
|
|
the WebSocket protocol for two-way communication with a remote
|
|
host.<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
|
|
time of its publication. Other documents may supersede this
|
|
document. A list of current W3C publications and the
|
|
|
|
latest <!-- DO NOT CHANGE THIS BACK TO THE STANDARD BOILERPLATE, AS IT IS INACCURATE -->
|
|
|
|
revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
|
|
http://www.w3.org/TR/.</em></p><p>If you wish to make comments regarding this document in a manner
|
|
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
|
|
public bug database</a>. If you do not have an account then you can
|
|
enter feedback using this form:<form action="http://www.whatwg.org/specs/web-apps/current-work/file-spam.cgi" method="post">
|
|
<fieldset><legend>Feedback Comments</legend>
|
|
<input name="id" type="hidden" value="top"><input name="component" type="hidden" value="WebSocket API (editor: Ian Hickson)"><input name="response" type="hidden" value="html"><p><label for="feedbackBox">Please enter your feedback, carefully
|
|
indicating the title of the section for which you are submitting
|
|
feedback, quoting the text that's wrong today if appropriate. If
|
|
you're suggesting a new feature, it's really important to say
|
|
<em>what</em> the problem you're trying to solve is. That's more
|
|
important than the solution, in fact.</label></p>
|
|
<p><textarea cols="79" id="feedbackBox" name="text" rows="10"></textarea></p>
|
|
<p class="note">Please don't use section numbers as these tend to
|
|
change rapidly and make your feedback harder to understand.</p>
|
|
<script type="text/javascript">
|
|
function checkFeedbackForm(form) {
|
|
if (form.elements.text.value.match(/^ *</)) {
|
|
alert('Please don\'t start your feedback with an angle bracket, instead explain what topic your feedback is about first.');
|
|
return true;
|
|
} else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
|
|
if (form.elements.text.value.match(/^Please enter your feedback, carefully/)) {
|
|
alert('Please enter your feedback, explaining what is wrong, and without repeating the instructions. Thanks!');
|
|
return true;
|
|
} else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
|
|
form.action = "http://www.whatwg.org/specs/web-apps/current-work/file-bug.cgi";
|
|
return true;
|
|
} else {
|
|
alert('Please include significantly more detail about exactly what problem you are trying to solve.');
|
|
return false;
|
|
}
|
|
}
|
|
}
|
|
</script><p>
|
|
<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>
|
|
</p>
|
|
</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>,
|
|
<a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>),
|
|
or <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a> (<a href="http://lists.whatwg.org/listinfo.cgi/whatwg-whatwg.org">subscribe</a>,
|
|
<a href="http://lists.whatwg.org/pipermail/whatwg-whatwg.org/">archives</a>).
|
|
All feedback is welcome.</p>
|
|
|
|
<!-- <p>Implementors should be aware that this specification is not
|
|
stable. <strong>Implementors who are not taking part in the
|
|
discussions are likely to find the specification changing out from
|
|
under them in incompatible ways.</strong> Vendors interested in
|
|
implementing this specification before it eventually reaches the
|
|
Candidate Recommendation stage should join the aforementioned
|
|
mailing lists and take part in the discussions.<div id="multipage-common">
|
|
</div><p>The latest
|
|
stable version of the editor's draft of this specification is always
|
|
available on <a href="http://dev.w3.org/html5/websockets/">the W3C CVS server</a>
|
|
and in the <a href="http://svn.whatwg.org/webapps/">WHATWG
|
|
Subversion repository</a>. The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html">latest
|
|
editor's working copy</a> (which may contain unfinished text in the
|
|
process of being prepared) contains the latest draft text of this
|
|
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
|
|
FAQ</a>.
|
|
-->
|
|
|
|
<p>Notifications of changes to this specification are sent along
|
|
with notifications of changes to related specifications using the
|
|
following mechanisms:<dl><dt>E-mail notifications of changes</dt>
|
|
<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>
|
|
<dt>Browsable version-control record of all changes:</dt>
|
|
<dd>CVSWeb interface with side-by-side diffs: <a href="http://dev.w3.org/cvsweb/html5/">http://dev.w3.org/cvsweb/html5/</a></dd>
|
|
<dd>Annotated summary with unified diffs: <a href="http://html5.org/tools/web-apps-tracker">http://html5.org/tools/web-apps-tracker</a></dd>
|
|
<dd>Raw Subversion interface: <code>svn checkout http://svn.whatwg.org/webapps/</code></dd>
|
|
</dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
|
|
Working Group</a> is the W3C working group responsible for this
|
|
specification's progress along the W3C Recommendation track.
|
|
This specification is the 08 December 2011 Candidate Recommendation.
|
|
Comments for the 29 September 2011 Last Call Working Draft are tracked in the
|
|
<a href="http://www.w3.org/2008/webapps/wiki/Websockets-Comments-LC-29Sep2011">comment tracking document</a>. Section 7 of this specification was previously included in the WebSocket Protocol specification.</p>
|
|
<p>This specification is being developed in conjunction with an
|
|
Internet Draft for a wire protocol, the WebSocket Protocol,
|
|
available from the following location:</p>
|
|
<!--
|
|
<ul><li>WebSocket Protocol Internet-Draft: <a href="http://www.whatwg.org/specs/web-socket-protocol/">http://www.whatwg.org/specs/web-socket-protocol/</a></li>
|
|
-->
|
|
<ul><li>WebSocket Protocol Internet-Draft: <a href="https://datatracker.ietf.org/doc/draft-ietf-hybi-thewebsocketprotocol/">https://datatracker.ietf.org/doc/draft-ietf-hybi-thewebsocketprotocol/</a></li>
|
|
</ul>
|
|
|
|
<!-- Not sure why this paragraph is duplicated below ...
|
|
|
|
<p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
|
|
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
|
|
any patent disclosures</a> made in connection with the deliverables
|
|
of the group; that page also includes instructions for disclosing a
|
|
patent. An individual who has actual knowledge of a patent which the
|
|
individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
|
|
Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
|
|
6 of the W3C Patent Policy</a>.</p>
|
|
-->
|
|
|
|
<p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
|
|
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
|
|
any patent disclosures</a> made in connection with the deliverables
|
|
of the group; that page also includes instructions for disclosing a
|
|
patent. An individual who has actual knowledge of a patent which the
|
|
individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
|
|
Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
|
|
6 of the W3C Patent Policy</a>.
|
|
|
|
<h3 class="no-num no-toc" id="crec">Candidate Recommendation Exit Criteria</h3>
|
|
|
|
<p>To exit the Candidate Recommendation (CR) stage, the following criteria
|
|
must have been met:
|
|
|
|
<ol>
|
|
<li>There will be at least two interoperable implementations passing all
|
|
approved test cases in the
|
|
<a href="http://w3c-test.org/webapps/WebSockets/tests/">test suite</a>
|
|
for this specification. An implementation is to be available (i.e. for
|
|
download), shipping (i.e. not private), and not experimental (i.e. intended
|
|
for a wide audience). The working group will decide when the test suite is
|
|
of sufficient quality to test interoperability and will produce an
|
|
implementation report (hosted together with the test suite).
|
|
|
|
<li>A minimum of three months of the CR stage will have elapsed (i.e. not
|
|
until after 08 March 2012). This is to ensure that enough time is given
|
|
for any remaining major errors to be caught. The CR period will be extended
|
|
if implementations are slow to appear.
|
|
</ol>
|
|
|
|
|
|
<h2 class="no-num no-toc" id="contents">Table of Contents</h2>
|
|
<ol class="toc">
|
|
<li><a href="#network-intro"><span class="secno">1 </span>Introduction</a></li>
|
|
<li><a href="#conformance-requirements"><span class="secno">2 </span>Conformance requirements</a>
|
|
<ol>
|
|
<li><a href="#dependencies"><span class="secno">2.1 </span>Dependencies</a></ol></li>
|
|
<li><a href="#terminology"><span class="secno">3 </span>Terminology</a></li>
|
|
<li><a href="#the-websocket-interface"><span class="secno">4 </span>The <code>WebSocket</code> interface</a></li>
|
|
<li><a href="#feedback-from-the-protocol"><span class="secno">5 </span>Feedback from the protocol</a></li>
|
|
<li><a href="#ping-and-pong-frames"><span class="secno">6 </span>Ping and Pong frames</a></li>
|
|
<li><a href="#parsing-websocket-urls"><span class="secno">7 </span>Parsing WebSocket URLs</a></li>
|
|
<li><a href="#event-definitions"><span class="secno">8 </span>Event definitions</a></li>
|
|
<li><a href="#garbage-collection"><span class="secno">9 </span>Garbage collection</a></li>
|
|
<li><a class="no-num" href="#references">References</a></li>
|
|
<li><a class="no-num" href="#acknowledgements">Acknowledgements</a></ol>
|
|
<hr><h2 id="network-intro"><span class="secno">1 </span>Introduction</h2><p><i>This section is non-normative.</i><p>To enable Web applications to maintain bidirectional
|
|
communications with server-side processes, this specification
|
|
introduces the <code><a href="#websocket">WebSocket</a></code> interface.<p class="note">This interface does not allow for raw access to the
|
|
underlying network. For example, this interface could not be used to
|
|
implement an IRC client without proxying messages through a custom
|
|
server.<h2 id="conformance-requirements"><span class="secno">2 </span>Conformance requirements</h2><p>All diagrams, examples, and notes in this specification are
|
|
non-normative, as are all sections explicitly marked non-normative.
|
|
Everything else in this specification is normative.<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
|
|
"OPTIONAL" in the normative parts of this document are to be
|
|
interpreted as described in RFC2119. For readability, these words do
|
|
not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a><p>Requirements phrased in the imperative as part of algorithms
|
|
(such as "strip any leading space characters" or "return false and
|
|
abort these steps") are to be interpreted with the meaning of the
|
|
key word ("must", "should", "may", etc) used in introducing the
|
|
algorithm.<p>Some conformance requirements are phrased as requirements on
|
|
attributes, methods or objects. Such requirements are to be
|
|
interpreted as requirements on user agents.<p>Conformance requirements phrased as algorithms or specific steps
|
|
may be implemented in any manner, so long as the end result is
|
|
equivalent. (In particular, the algorithms defined in this
|
|
specification are intended to be easy to follow, and not intended to
|
|
be performant.)<p>The only conformance class defined by this specification is user
|
|
agents.<p>User agents may impose implementation-specific limits on
|
|
otherwise unconstrained inputs, e.g. to prevent denial of service
|
|
attacks, to guard against running out of memory, or to work around
|
|
platform-specific limitations.<p>When support for a feature is disabled (e.g. as an emergency
|
|
measure to mitigate a security problem, or to aid in development, or
|
|
for performance reasons), user agents must act as if they had no
|
|
support for the feature whatsoever, and as if the feature was not
|
|
mentioned in this specification. For example, if a particular
|
|
feature is accessed via an attribute in a Web IDL interface, the
|
|
attribute itself would be omitted from the objects that implement
|
|
that interface — leaving the attribute on the object but
|
|
making it return null or throw an exception is insufficient.<h3 id="dependencies"><span class="secno">2.1 </span>Dependencies</h3><p>This specification relies on several other underlying
|
|
specifications.<dl><dt>HTML</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Many fundamental concepts from HTML are used by this
|
|
specification. <a href="#refsHTML">[HTML]</a></p>
|
|
|
|
</dd>
|
|
|
|
<dt>WebIDL</dt>
|
|
|
|
<dd>
|
|
|
|
<p>The IDL blocks in this specification use the semantics of the
|
|
WebIDL specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
|
|
|
|
</dd>
|
|
|
|
</dl><h2 id="terminology"><span class="secno">3 </span>Terminology</h2><p>The construction "a <code title="">Foo</code> object", where
|
|
<code title="">Foo</code> is actually an interface, is sometimes
|
|
used instead of the more accurate "an object implementing the
|
|
interface <code title="">Foo</code>".<p>The term DOM is used to refer to the API set made available to
|
|
scripts in Web applications, and does not necessarily imply the
|
|
existence of an actual <code>Document</code> object or of any other
|
|
<code>Node</code> objects as defined in the DOM Core
|
|
specifications. <a href="#refsDOMCORE">[DOMCORE]</a><p>An IDL attribute is said to be <em>getting</em> when its value is
|
|
being retrieved (e.g. by author script), and is said to be
|
|
<em>setting</em> when a new value is assigned to it.<h2 id="the-websocket-interface"><span class="secno">4 </span>The <code><a href="#websocket">WebSocket</a></code> interface</h2><pre class="idl">[<a href="#dom-websocket" title="dom-WebSocket">Constructor</a>(DOMString url, optional DOMString protocols),
|
|
<a href="#dom-websocket" title="dom-WebSocket">Constructor</a>(DOMString url, optional DOMString[] protocols)]
|
|
interface <dfn id="websocket">WebSocket</dfn> : <span>EventTarget</span> {
|
|
readonly attribute DOMString <a href="#dom-websocket-url" title="dom-WebSocket-url">url</a>;
|
|
|
|
// ready state
|
|
const unsigned short <a href="#dom-websocket-connecting" title="dom-WebSocket-CONNECTING">CONNECTING</a> = 0;
|
|
const unsigned short <a href="#dom-websocket-open" title="dom-WebSocket-OPEN">OPEN</a> = 1;
|
|
const unsigned short <a href="#dom-websocket-closing" title="dom-WebSocket-CLOSING">CLOSING</a> = 2;
|
|
const unsigned short <a href="#dom-websocket-closed" title="dom-WebSocket-CLOSED">CLOSED</a> = 3;
|
|
readonly attribute unsigned short <a href="#dom-websocket-readystate" title="dom-WebSocket-readyState">readyState</a>;
|
|
readonly attribute unsigned long <a href="#dom-websocket-bufferedamount" title="dom-WebSocket-bufferedAmount">bufferedAmount</a>;
|
|
|
|
// networking
|
|
[TreatNonCallableAsNull] attribute <span>Function</span>? <a href="#handler-websocket-onopen" title="handler-WebSocket-onopen">onopen</a>;
|
|
[TreatNonCallableAsNull] attribute <span>Function</span>? <a href="#handler-websocket-onerror" title="handler-WebSocket-onerror">onerror</a>;
|
|
[TreatNonCallableAsNull] attribute <span>Function</span>? <a href="#handler-websocket-onclose" title="handler-WebSocket-onclose">onclose</a>;
|
|
readonly attribute DOMString <a href="#dom-websocket-extensions" title="dom-WebSocket-extensions">extensions</a>;
|
|
readonly attribute DOMString <a href="#dom-websocket-protocol" title="dom-WebSocket-protocol">protocol</a>;
|
|
void <a href="#dom-websocket-close" title="dom-WebSocket-close">close</a>([Clamp] optional unsigned short code, optional DOMString reason);
|
|
|
|
// messaging
|
|
[TreatNonCallableAsNull] attribute <span>Function</span>? <a href="#handler-websocket-onmessage" title="handler-WebSocket-onmessage">onmessage</a>;
|
|
attribute DOMString <a href="#dom-websocket-binarytype" title="dom-WebSocket-binaryType">binaryType</a>;
|
|
void <a href="#dom-websocket-send" title="dom-WebSocket-send">send</a>(DOMString data);
|
|
void <a href="#dom-websocket-send" title="dom-WebSocket-send">send</a>(<span>ArrayBuffer</span> data);
|
|
void <a href="#dom-websocket-send" title="dom-WebSocket-send">send</a>(<span>Blob</span> data);
|
|
};</pre><p>The <dfn id="dom-websocket" title="dom-WebSocket"><code>WebSocket(<var title="">url</var>, <var title="">protocols</var>)</code></dfn>
|
|
constructor takes one or two arguments. The first argument, <var title="">url</var>, specifies the <span>URL</span> to which to
|
|
connect. The second, <var title="">protocols</var>, if present, is
|
|
either a string or an array of strings. If it is a string, it is
|
|
equivalent to an array consisting of just that string; if it is
|
|
omitted, it is equivalent to the empty array. Each string in the
|
|
array is a subprotocol name. The connection will only be established
|
|
if the server reports that it has selected one of these
|
|
subprotocols. The subprotocol names must all be strings that match
|
|
the requirements for elements that comprise the value of <code title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>
|
|
header fields as defined by the WebSocket protocol specification. <a href="#refsWSP">[WSP]</a><p>When the <code>WebSocket()</code> constructor is invoked, the UA
|
|
must run these steps:<ol><li><p><i><a href="#parse-a-websocket-url-s-components">Parse a WebSocket URL's components</a></i> from the <var title="">url</var> argument, to obtain <var title="">host</var>,
|
|
<var title="">port</var>, <var title="">resource name</var>, and
|
|
<var title="">secure</var>. If this fails, throw a
|
|
<code>SyntaxError</code> exception and abort these steps. <a href="#refsWSP">[WSP]</a></li>
|
|
|
|
<li><p>If <var title="">secure</var> is false but the
|
|
<span>origin</span> of the <span>entry script</span> has a scheme
|
|
component that is itself a secure protocol, e.g. HTTPS, then throw
|
|
a <code>SecurityError</code> exception.</li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">port</var> is a port to which the user agent
|
|
is configured to block access, then throw a
|
|
<code>SecurityError</code> exception. (User agents typically block
|
|
access to well-known ports like SMTP.)</p>
|
|
|
|
|
|
|
|
<p>Access to ports 80 and 443 should not be blocked, including the
|
|
unlikely cases when <var title="">secure</var> is false but <var title="">port</var> is 443 or <var title="">secure</var> is true
|
|
but <var title="">port</var> is 80.</p>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">protocols</var> is absent, let <var title="">protocols</var> be an empty array.</p>
|
|
|
|
<p>Otherwise, if <var title="">protocols</var> is present and a
|
|
string, let <var title="">protocols</var> instead be an array
|
|
consisting of just that string.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>If any of the values in <var title="">protocols</var> occur
|
|
more than once or otherwise fail to match the requirements for
|
|
elements that comprise the value of <code title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>
|
|
header fields as defined by the WebSocket protocol specification,
|
|
then throw a <code>SyntaxError</code> exception and abort these
|
|
steps. <a href="#refsWSP">[WSP]</a></li>
|
|
|
|
<li><p>Let <var title="">origin</var> be the <span title="ASCII
|
|
serialization of an origin">ASCII serialization</span> of the
|
|
<span>origin</span> of the <span>entry script</span>,
|
|
<span>converted to ASCII lowercase</span>.</li>
|
|
|
|
<li><p>Return a new <code><a href="#websocket">WebSocket</a></code> object, and continue
|
|
these steps in the background (without blocking scripts).</li>
|
|
|
|
<li>
|
|
|
|
<p><i>Establish a WebSocket connection</i> given the set (<var title="">host</var>, <var title="">port</var>, <var title="">resource name</var>, <var title="">secure</var>), along
|
|
with the <var title="">protocols</var> list, an empty list for the
|
|
extensions, and <var title="">origin</var>. The <i>headers to send
|
|
appropriate cookies</i> must be a <code title="http-Cookie">Cookie</code> header whose value is the
|
|
<i>cookie-string</i> computed from the user's cookie store and the
|
|
URL <var title="">url</var>; for these purposes this is
|
|
<em>not</em> a "non-HTTP" API. <a href="#refsWSP">[WSP]</a> <a href="#refsCOOKIES">[COOKIES]</a></p>
|
|
|
|
<p>When the user agent <i title="validate the server's
|
|
response">validates the server's response</i> during the
|
|
"<i>establish a WebSocket connection</i>" algorithm, if the status
|
|
code received from the server is not 101 (e.g. it is a redirect),
|
|
the user agent must <i>fail the websocket connection</i>.</p>
|
|
|
|
<p class="warning">Following HTTP procedures here could introduce
|
|
serious security problems in a Web browser context. For example,
|
|
consider a host with a WebSocket server at one path and an open
|
|
HTTP redirector at another. Suddenly, any script that can be given
|
|
a particular WebSocket URL can be tricked into communicating to
|
|
(and potentially sharing secrets with) any host on the Internet,
|
|
even if the script checks that the URL has the right hostname.</p>
|
|
|
|
|
|
<p class="note">If the <i>establish a WebSocket connection</i>
|
|
algorithm fails, it triggers the <i>fail the WebSocket
|
|
connection</i> algorithm, which then invokes the <i>close the
|
|
WebSocket connection</i> algorithm, which then establishes that
|
|
<i>the WebSocket connection is closed</i>, which fires the <code title="event-close">close</code> event <a href="#closeWebSocket">as described below</a>.</p>
|
|
|
|
</li>
|
|
|
|
</ol><p>This constructor must be visible when the <span>script's global
|
|
object</span> is either a <code>Window</code> object or an object
|
|
implementing the <code>WorkerUtils</code> interface.<hr><p>The <dfn id="dom-websocket-url" title="dom-WebSocket-url"><code>url</code></dfn>
|
|
attribute must return the result of <span title="resolve a
|
|
url">resolving</span> the <span>URL</span> that was passed to the
|
|
constructor. (It doesn't matter what it is resolved relative to,
|
|
since we already know it is an <span>absolute URL</span>.)<p>The <dfn id="dom-websocket-readystate" title="dom-WebSocket-readyState"><code>readyState</code></dfn>
|
|
attribute represents the state of the connection. It can have the
|
|
following values:<dl><dt><dfn id="dom-websocket-connecting" title="dom-WebSocket-CONNECTING"><code>CONNECTING</code></dfn> (numeric value 0)</dt>
|
|
|
|
<dd>The connection has not yet been established.</dd>
|
|
|
|
<dt><dfn id="dom-websocket-open" title="dom-WebSocket-OPEN"><code>OPEN</code></dfn> (numeric value 1)</dt>
|
|
|
|
<dd><i>The WebSocket connection is established</i> and communication is possible.</dd>
|
|
|
|
<dt><dfn id="dom-websocket-closing" title="dom-WebSocket-CLOSING"><code>CLOSING</code></dfn> (numeric value 2)</dt>
|
|
|
|
<dd>The connection is going through the closing handshake.</dd>
|
|
|
|
<dt><dfn id="dom-websocket-closed" title="dom-WebSocket-CLOSED"><code>CLOSED</code></dfn> (numeric value 3)</dt>
|
|
|
|
<dd>The connection has been closed or could not be opened.</dd>
|
|
|
|
</dl><p>When the object is created its <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> must be set to
|
|
<code title="dom-WebSocket-CONNECTING"><a href="#dom-websocket-connecting">CONNECTING</a></code> (0).<p>The <dfn id="dom-websocket-extensions" title="dom-WebSocket-extensions"><code>extensions</code></dfn>
|
|
attribute must initially return the empty string. After <i>the
|
|
WebSocket connection is established</i>, its value might change, as
|
|
defined below.<p class="note">The <code title="dom-WebSocket-extensions"><a href="#dom-websocket-extensions">extensions</a></code> attribute returns
|
|
the extensions selected by the server, if any. (Currently this will
|
|
only ever be the empty string.)<p>The <dfn id="dom-websocket-protocol" title="dom-WebSocket-protocol"><code>protocol</code></dfn> attribute
|
|
must initially return the empty string. After <i>the WebSocket
|
|
connection is established</i>, its value might change, as defined
|
|
below.<p class="note">The <code title="dom-WebSocket-protocol"><a href="#dom-websocket-protocol">protocol</a></code> attribute returns the
|
|
subprotocol selected by the server, if any. It can be used in
|
|
conjunction with the array form of the constructor's second argument
|
|
to perform subprotocol negotiation.<p>The <dfn id="dom-websocket-close" title="dom-WebSocket-close"><code>close()</code></dfn>
|
|
method must run the following steps:<ol><li><p>If the method's first argument is present but is not an
|
|
integer equal to 1000 or in the range 3000 to 4999, throw an
|
|
<code>InvalidAccessError</code> exception and abort these
|
|
steps.</li>
|
|
|
|
<li><p>If the method's second argument has any unpaired surrogates,
|
|
then throw a <code>SyntaxError</code> exception and abort these
|
|
steps.</li>
|
|
|
|
<li><p>If the method's second argument is present, then let <var title="">reason</var> be the result of encoding that argument as
|
|
UTF-8. If <var title="">reason</var> is longer than 123 bytes, then
|
|
throw a <code>SyntaxError</code> exception and abort these steps.
|
|
<a href="#refsRFC3629">[RFC3629]</a></li>
|
|
|
|
<li><p>Run the first matching steps from the following list:</p>
|
|
|
|
<dl class="switch"><dt>If the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
|
|
attribute is in the <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2) or <code title="dom-WebSocket-CLOSED"><a href="#dom-websocket-closed">CLOSED</a></code> (3) state</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Do nothing.</p>
|
|
|
|
<p class="note">The connection is already closing or is already
|
|
closed. If it has not already, a <code title="event-close">close</code> event will eventually fire <a href="#closeWebSocket">as described below</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the WebSocket connection is not yet <i title="the
|
|
WebSocket connection is established">established</i> <a href="#refsWSP">[WSP]</a></dt>
|
|
|
|
<dd>
|
|
|
|
<p><i>Fail the WebSocket connection</i> and set the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's
|
|
value to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2).
|
|
<a href="#refsWSP">[WSP]</a></p>
|
|
|
|
<p class="note">The <i>fail the WebSocket connection</i>
|
|
algorithm invokes the <i>close the WebSocket
|
|
connection</i> algorithm, which then establishes that
|
|
<i>the WebSocket connection is closed</i>, which fires the
|
|
<code title="event-close">close</code> event <a href="#closeWebSocket">as described below</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the WebSocket closing handshake has not yet been <i title="the WebSocket closing handshake is
|
|
started">started</i> <a href="#refsWSP">[WSP]</a></dt>
|
|
|
|
<dd>
|
|
|
|
<p><i>Start the WebSocket closing handshake</i> and set the
|
|
<code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
|
|
attribute's value to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2). <a href="#refsWSP">[WSP]</a></p>
|
|
|
|
<p>If the first argument is present, then the status
|
|
code<!--CLOSE CODE--> to use in the WebSocket Close message must
|
|
be the integer given by the first argument. <a href="#refsWSP">[WSP]</a></p>
|
|
|
|
<p>If the second argument is also present, then <var title="">reason</var> must be provided in the Close message
|
|
after the status code<!--CLOSE CODE-->. <a href="#refsRFC3629">[RFC3629]</a> <a href="#refsWSP">[WSP]</a></p>
|
|
|
|
<p class="note">The <i>start the WebSocket closing handshake</i>
|
|
algorithm eventually invokes the <i>close the WebSocket
|
|
connection</i> algorithm, which then establishes that <i>the
|
|
WebSocket connection is closed</i>, which fires the <code title="event-close">close</code> event <a href="#closeWebSocket">as described below</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Set the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's
|
|
value to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code>
|
|
(2).</p>
|
|
|
|
<p class="note"><i>The WebSocket closing handshake is
|
|
started</i>, and will eventually invoke the <i>close the
|
|
WebSocket connection</i> algorithm, which will establish that
|
|
<i>the WebSocket connection is closed</i>, and thus the <code title="event-close">close</code> event will fire, <a href="#closeWebSocket">as described below</a>.</p>
|
|
|
|
</dd>
|
|
|
|
</dl></li>
|
|
|
|
</ol><hr><p>The <dfn id="dom-websocket-bufferedamount" title="dom-WebSocket-bufferedAmount"><code>bufferedAmount</code></dfn>
|
|
attribute must return the number of bytes of application data (UTF-8
|
|
text and binary data) that have been queued using <code title="dom-WebSocket-send"><a href="#dom-websocket-send">send()</a></code> but that, as of the last
|
|
time the <span>event loop</span> started executing a <span title="concept-task">task</span>, had not yet been transmitted to
|
|
the network. (This thus includes any text sent during the execution
|
|
of the current task, regardless of whether the user agent is able to
|
|
transmit text asynchronously with script execution.) This does not
|
|
include framing overhead incurred by the protocol, or buffering done
|
|
by the operating system or network hardware. If the connection is
|
|
closed, this attribute's value will only increase with each call to
|
|
the <code title="dom-WebSocket-send"><a href="#dom-websocket-send">send()</a></code> method (the
|
|
number does not reset to zero once the connection closes).<div class="example">
|
|
|
|
<p>In this simple example, the <code title="dom-WebSocket-bufferedAmount"><a href="#dom-websocket-bufferedamount">bufferedAmount</a></code>
|
|
attribute is used to ensure that updates are sent either at the
|
|
rate of one update every 50ms, if the network can handle that rate,
|
|
or at whatever rate the network <em>can</em> handle, if that is too
|
|
fast.</p>
|
|
|
|
<pre>var socket = new WebSocket('ws://game.example.com:12010/updates');
|
|
socket.onopen = function () {
|
|
setInterval(function() {
|
|
if (socket.bufferedAmount == 0)
|
|
socket.send(getUpdateData());
|
|
}, 50);
|
|
};</pre>
|
|
|
|
<p>The <code title="dom-WebSocket-bufferedAmount"><a href="#dom-websocket-bufferedamount">bufferedAmount</a></code>
|
|
attribute can also be used to saturate the network without sending
|
|
the data at a higher rate than the network can handle, though this
|
|
requires more careful monitoring of the value of the attribute over
|
|
time.</p>
|
|
|
|
</div><hr><p>When a <code><a href="#websocket">WebSocket</a></code> object is created, its <dfn id="dom-websocket-binarytype" title="dom-WebSocket-binaryType"><code>binaryType</code></dfn> IDL
|
|
attribute must be set to the string "<code title="">blob</code>". On
|
|
getting, it must return the last value it was set to. On setting, if
|
|
the new value is either the string "<code title="">blob</code>" or
|
|
the string "<code title="">arraybuffer</code>", then set the IDL
|
|
attribute to this new value. Otherwise, throw a
|
|
<code>SyntaxError</code> exception.<p class="note">This attribute allows authors to control how binary
|
|
data is exposed to scripts. By setting the attribute to "<code title="">blob</code>", binary data is returned in <code>Blob</code>
|
|
form; by setting it to "<code title="">arraybuffer</code>", it is
|
|
returned in <code>ArrayBuffer</code> form. User agents can use this
|
|
as a hint for how to handle incoming binary data: if the attribute
|
|
is set to "<code title="">blob</code>", it is safe to spool it to
|
|
disk, and if it is set to "<code title="">arraybuffer</code>", it is
|
|
likely more efficient to keep the data in memory. Naturally, user
|
|
agents are encouraged to use more subtle heuristics to decide
|
|
whether to keep incoming data in memory or not, e.g. based on how
|
|
big the data is or how common it is for a script to change the
|
|
attribute at the last minute. This latter aspect is important in
|
|
particular because it is quite possible for the attribute to be
|
|
changed after the user agent has received the data but before the
|
|
user agent as fired the event for it.<p>The <dfn id="dom-websocket-send" title="dom-WebSocket-send"><code>send(<var title="">data</var>)</code></dfn> method transmits data using the
|
|
connection. If the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute is
|
|
<code title="dom-WebSocket-CONNECTING"><a href="#dom-websocket-connecting">CONNECTING</a></code>, it must
|
|
throw an <code>InvalidStateError</code> exception. Otherwise, the
|
|
user agent must run the appropriate set of steps from the following
|
|
list:<dl><dt>If the argument is a string</dt>
|
|
|
|
<dd>
|
|
|
|
<p>If the <var title="">data</var> argument has any unpaired
|
|
surrogates, then throw a <code>SyntaxError</code> exception. If
|
|
<i>the WebSocket connection is established</i>, and the string has
|
|
no unpaired surrogates, and <i title="the WebSocket closing
|
|
handshake is started">the WebSocket closing handshake has not yet
|
|
started</i>, then the user agent must <i>send a WebSocket
|
|
Message</i> comprised of <var title="">data</var> using a text
|
|
frame opcode; if the data cannot be sent, e.g. because it would
|
|
need to be buffered but the buffer is full, the user agent must
|
|
<i>close the WebSocket connection</i> <a href="#concept-websocket-close-fail" title="concept-websocket-close-fail">with prejudice</a>. Any
|
|
invokation of this method with a string argument that does not
|
|
throw an exception must increase the <code title="dom-WebSocket-bufferedAmount"><a href="#dom-websocket-bufferedamount">bufferedAmount</a></code>
|
|
attribute by the number of bytes needed to express the argument as
|
|
UTF-8. <a href="#refsRFC3629">[RFC3629]</a> <a href="#refsWSP">[WSP]</a></p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the argument is a <code>Blob</code> object</dt>
|
|
|
|
<dd>
|
|
|
|
<p>If <i>the WebSocket connection is established</i>, and <i title="the WebSocket closing handshake is started">the WebSocket
|
|
closing handshake has not yet started</i>, then the user agent
|
|
must <i>send a WebSocket Message</i> comprised of <var title="">data</var> using a binary frame opcode; if the data
|
|
cannot be sent, e.g. because it would need to be buffered but the
|
|
buffer is full, the user agent must <i>close the WebSocket
|
|
connection</i> <a href="#concept-websocket-close-fail" title="concept-websocket-close-fail">with
|
|
prejudice</a>. The data to be sent is the raw data represented
|
|
by the <code>Blob</code> object. Any
|
|
invokation of this method with a <code>Blob</code> argument that
|
|
does not throw an exception must increase the <code title="dom-WebSocket-bufferedAmount"><a href="#dom-websocket-bufferedamount">bufferedAmount</a></code>
|
|
attribute by the size of the <code>Blob</code> object's raw data,
|
|
in bytes. <a href="#refsWSP">[WSP]</a> <a href="#refsFILEAPI">[FILEAPI]</a></p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the argument is an <code>ArrayBuffer</code> object</dt>
|
|
|
|
<dd>
|
|
|
|
<p>If <i>the WebSocket connection is established</i>, and <i title="the WebSocket closing handshake is started">the WebSocket
|
|
closing handshake has not yet started</i>, then the user agent
|
|
must <i>send a WebSocket Message</i> comprised of <var title="">data</var> using a binary frame opcode; if the data
|
|
cannot be sent, e.g. because it would need to be buffered but the
|
|
buffer is full, the user agent must <i>close the WebSocket
|
|
connection</i> <a href="#concept-websocket-close-fail" title="concept-websocket-close-fail">with
|
|
prejudice</a>. The data to be sent is the data stored in the
|
|
buffer described by the <code>ArrayBuffer</code> object. Any invokation of this method with an
|
|
<code>ArrayBuffer</code> argument that does not throw an exception
|
|
must increase the <code title="dom-WebSocket-bufferedAmount"><a href="#dom-websocket-bufferedamount">bufferedAmount</a></code>
|
|
attribute by the length of the <code>ArrayBuffer</code> in bytes.
|
|
<a href="#refsWSP">[WSP]</a> <a href="#refsTYPEDARRAY">[TYPEDARRAY]</a></p>
|
|
|
|
</dd>
|
|
|
|
</dl><hr><p>The following are the <span>event handlers</span> (and their
|
|
corresponding <span title="event handler event type">event handler
|
|
event types</span>) that must be supported, as IDL attributes, by
|
|
all objects implementing the <code><a href="#websocket">WebSocket</a></code> interface:<table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
|
|
<tbody><tr><td><dfn id="handler-websocket-onopen" title="handler-WebSocket-onopen"><code>onopen</code></dfn> <td> <code title="event-open">open</code>
|
|
<tr><td><dfn id="handler-websocket-onmessage" title="handler-WebSocket-onmessage"><code>onmessage</code></dfn> <td> <code title="event-message">message</code>
|
|
<tr><td><dfn id="handler-websocket-onerror" title="handler-WebSocket-onerror"><code>onerror</code></dfn> <td> <code title="event-error">error</code>
|
|
<tr><td><dfn id="handler-websocket-onclose" title="handler-WebSocket-onclose"><code>onclose</code></dfn> <td> <code title="event-close">close</code>
|
|
</table><h2 id="feedback-from-the-protocol"><span class="secno">5 </span>Feedback from the protocol</h2><p>When <i>the WebSocket connection is established</i>, the user
|
|
agent must <span>queue a task</span> to run these steps:<ol><li><p>Change the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's
|
|
value to <code title="dom-WebSocket-OPEN"><a href="#dom-websocket-open">OPEN</a></code> (1).</li>
|
|
|
|
<li><p>Change the <code title="dom-WebSocket-extensions"><a href="#dom-websocket-extensions">extensions</a></code> attribute's
|
|
value to the <i>extensions in use</i>, if is not the null value. <a href="#refsWSP">[WSP]</a></li>
|
|
|
|
<li><p>Change the <code title="dom-WebSocket-protocol"><a href="#dom-websocket-protocol">protocol</a></code> attribute's value to
|
|
the <i>subprotocol in use</i>, if is not the null value. <a href="#refsWSP">[WSP]</a></li>
|
|
|
|
<li><p>Act as if the user agent had <span title="receives a
|
|
set-cookie-string">received a set-cookie-string</span> consisting
|
|
of the <i>cookies set during the server's opening handshake</i>,
|
|
for the URL <var title="">url</var> given to the <code title="dom-WebSocket"><a href="#dom-websocket">WebSocket()</a></code> constructor. <a href="#refsCOOKIES">[COOKIES]</a> <a href="#refsRFC3629">[RFC3629]</a> <a href="#refsWSP">[WSP]</a></li>
|
|
|
|
<li><p><span>Fire a simple event</span> named <code title="event-open">open</code> at the <code><a href="#websocket">WebSocket</a></code>
|
|
object.</p>
|
|
|
|
</ol><hr><p>When <i>a WebSocket message has been received</i> with type <var title="">type</var> and data <var title="">data</var>, the user
|
|
agent must <span>queue a task</span> to follow these steps: <a href="#refsWSP">[WSP]</a><ol><li>
|
|
|
|
<p>If the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
|
|
attribute's value is not <code title="dom-WebSocket-OPEN"><a href="#dom-websocket-open">OPEN</a></code> (1), then abort these
|
|
steps.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Let <var title="">event</var> be an event that uses the
|
|
<code>MessageEvent</code> interface, with the event name <code title="event-message">message</code>, which does not bubble, is
|
|
not cancelable, and has no default action.
|
|
|
|
<a href="#refsHTML">[HTML]</a>
|
|
|
|
</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Initialize <var title="">event</var>'s <code title="dom-MessageEvent-origin">origin</code> attribute to the
|
|
<span title="Unicode serialization of an origin">Unicode
|
|
serialization</span> of the <span>origin</span> of the
|
|
<span>URL</span> that was passed to the <code><a href="#websocket">WebSocket</a></code>
|
|
object's constructor.</li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">type</var> indicates that the data is Text,
|
|
then initialize <var title="">event</var>'s <code title="dom-MessageEvent-data">data</code> attribute to <var title="">data</var>.
|
|
|
|
<p>If <var title="">type</var> indicates that the data is Binary,
|
|
and <code title="dom-WebSocket-binaryType"><a href="#dom-websocket-binarytype">binaryType</a></code> is
|
|
set to "<code title="">blob</code>", then initialize <var title="">event</var>'s <code title="dom-MessageEvent-data">data</code> attribute to a new
|
|
<code>Blob</code> object that represents <var title="">data</var>
|
|
as its raw data. <a href="#refsFILEAPI">[FILEAPI]</a></p>
|
|
|
|
<p>If <var title="">type</var> indicates that the data is Binary,
|
|
and <code title="dom-WebSocket-binaryType"><a href="#dom-websocket-binarytype">binaryType</a></code> is
|
|
set to "<code title="">arraybuffer</code>", then initialize <var title="">event</var>'s <code title="dom-MessageEvent-data">data</code> attribute to a new
|
|
read-only <code>ArrayBuffer</code> object whose contents are <var title="">data</var>. <a href="#refsTYPEDARRAY">[TYPEDARRAY]</a></p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Dispatch <var title="">event</var> at the
|
|
<code><a href="#websocket">WebSocket</a></code> object.</p>
|
|
|
|
</li>
|
|
|
|
</ol><p class="note">User agents are encouraged to check if they can
|
|
perform the above steps efficiently before they run the task,
|
|
picking tasks from other <span title="task queue">task queues</span>
|
|
while they prepare the buffers if not. For example, if the <code title="dom-WebSocket-binaryType"><a href="#dom-websocket-binarytype">binaryType</a></code> attribute was set
|
|
to "<code title="">blob</code>" when the data arrived, and the user
|
|
agent spooled all the data to disk, but just before running the
|
|
above <span title="concept-task">task</span> for this particular
|
|
message the script switched <code title="dom-WebSocket-binaryType"><a href="#dom-websocket-binarytype">binaryType</a></code> to "<code title="">arraybuffer</code>", the user agent would want to page the
|
|
data back to RAM before running this <span title="concept-task">task</span> so as to avoid stalling the main
|
|
thread while it created the <code>ArrayBuffer</code> object.<hr><p>When <i>the WebSocket closing handshake is started</i>, the user
|
|
agent must <span>queue a task</span> to change the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's value
|
|
to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2). (If the
|
|
<code title="dom-WebSocket-close"><a href="#dom-websocket-close">close()</a></code> method was called,
|
|
the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
|
|
attribute's value will already be set to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2) when this task
|
|
runs.) <a href="#refsWSP">[WSP]</a><hr><p id="closeWebSocket">When <i>the WebSocket connection is
|
|
closed</i>, possibly <i title="">cleanly</i>, the user agent must
|
|
<span>queue a task</span> to run the following substeps:<ol><li><p>Change the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's
|
|
value to <code title="dom-WebSocket-CLOSED"><a href="#dom-websocket-closed">CLOSED</a></code>
|
|
(3).</li>
|
|
|
|
<li><p>If the user agent was required to <i>fail the websocket
|
|
connection</i> or <i>the WebSocket connection is closed</i> <dfn id="concept-websocket-close-fail" title="concept-websocket-close-fail">with prejudice</dfn>,
|
|
<span>fire a simple event</span> named <code title="">error</code>
|
|
at the <code><a href="#websocket">WebSocket</a></code> object. <a href="#refsWSP">[WSP]</a></li>
|
|
|
|
<li><p>Create an event that uses the <code><a href="#closeevent">CloseEvent</a></code>
|
|
interface, with the event name <code title="event-close">close</code>, which does not bubble, is not
|
|
cancelable, has no default action, whose <code title="dom-CloseEvent-wasClean"><a href="#dom-closeevent-wasclean">wasClean</a></code> attribute is initialized to
|
|
true if the connection closed <i title="">cleanly</i> and false
|
|
otherwise, whose <code title="dom-CloseEvent-code"><a href="#dom-closeevent-code">code</a></code>
|
|
attribute is initialized to <i>the WebSocket connection close code</i>, and
|
|
whose <code title="dom-CloseEvent-reason"><a href="#dom-closeevent-reason">reason</a></code> attribute
|
|
is initialized to <i>the WebSocket connection close reason</i>
|
|
<span>decoded as UTF-8, with error handling</span>, and dispatch
|
|
the event at the <code><a href="#websocket">WebSocket</a></code> object. <a href="#refsWSP">[WSP]</a></li>
|
|
|
|
</ol><p>The <span>task source</span> for all <span title="concept-task">tasks</span> <span title="queue a
|
|
task">queued</span> in this section is the <dfn id="websocket-task-source">WebSocket task
|
|
source</dfn>.<h2 id="ping-and-pong-frames"><span class="secno">6 </span>Ping and Pong frames</h2><p>The WebSocket protocol specification defines Ping and Pong frames
|
|
that can be used for keep-alive, heart-beats, network status
|
|
probing, latency instrumentation, and so forth. These are not
|
|
currently exposed in the API.<p>User agents may send ping and unsolicited pong frames as desired,
|
|
for example in an attempt to maintain local network NAT mappings, to
|
|
detect failed connections, or to display latency metrics to the
|
|
user. User agents must not use pings or unsolicited pongs to aid the
|
|
server; it is assumed that servers will send solicit pongs whenever
|
|
appropriate for the server's needs.<h2 id="parsing-websocket-urls"><span class="secno">7 </span>Parsing WebSocket URLs</h2><p>The steps to <dfn id="parse-a-websocket-url-s-components">parse a WebSocket URL's components</dfn> from
|
|
a string <var title="">url</var> are as follows. These steps return
|
|
either a <var title="">host</var>, a <var title="">port</var>, a
|
|
<var title="">resource name</var>, and a <var title="">secure</var>
|
|
flag, or they fail.<ol><li><p>If the <var title="">url</var> string is not an
|
|
<span>absolute URL</span>, then fail this algorithm.</li>
|
|
|
|
<li>
|
|
|
|
<p><span title="resolve a url">Resolve</span> the <var title="">url</var> (as per <a href="http://www.w3.org/TR/html5/urls.html#resolving-urls">Resolving URLs</a>) string, with the <span>URL character
|
|
encoding</span> set to UTF-8. <a href="#refsRFC3629">[RFC3629]</a></p>
|
|
<p class="note">It doesn't matter what it is resolved relative to,
|
|
since we already know it is an <span>absolute URL</span> at this
|
|
point.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>If <var title="">url</var> does not have a <span title="url-scheme"><scheme></span> component whose value,
|
|
when <span>converted to ASCII lowercase</span>, is either "<code title="">ws</code>" or "<code title="">wss</code>", then fail this
|
|
algorithm.</li>
|
|
|
|
<li><p>If <var title="">url</var> has a <span title="url-fragment"><fragment></span> component, then fail
|
|
this algorithm.</li>
|
|
|
|
<li><p>If the <span title="url-scheme"><scheme></span>
|
|
component of <var title="">url</var> is "<code title="">ws</code>",
|
|
set <var title="">secure</var> to false; otherwise, the <span title="url-scheme"><scheme></span> component is "<code title="">wss</code>", set <var title="">secure</var> to
|
|
true.</li>
|
|
|
|
<li><p>Let <var title="">host</var> be the value of the <span title="url-host"><host></span> component of <var title="">url</var>, <span>converted to ASCII
|
|
lowercase</span>.</li>
|
|
<li><p>If <var title="">url</var> has a <span title="url-port"><port></span> component, then let <var title="">port</var> be that component's value; otherwise, there is
|
|
no explicit <var title="">port</var>.</li>
|
|
|
|
<li><p>If there is no explicit <var title="">port</var>, then: if
|
|
<var title="">secure</var> is false, let <var title="">port</var>
|
|
be 80, otherwise let <var title="">port</var> be 443.</li>
|
|
|
|
<li><p>Let <var title="">resource name</var> be the value of the
|
|
<span title="url-path"><path></span> component (which might
|
|
be empty) of <var title="">url</var>.</li>
|
|
<li><p>If <var title="">resource name</var> is the empty string,
|
|
set it to a single character U+002F SOLIDUS (/).</li>
|
|
|
|
<li><p>If <var title="">url</var> has a <span title="url-query"><query></span> component, then append a
|
|
single U+003F QUESTION MARK character (?) to <var title="">resource
|
|
name</var>, followed by the value of the <span title="url-query"><query></span> component.</li>
|
|
<li><p>Return <var title="">host</var>, <var title="">port</var>,
|
|
<var title="">resource name</var>, and <var title="">secure</var>.</li>
|
|
|
|
</ol><h2 id="event-definitions"><span class="secno">8 </span>Event definitions</h2><pre class="idl">[Constructor(DOMString type, optional <a href="#closeeventinit">CloseEventInit</a> eventInitDict)]
|
|
interface <dfn id="closeevent">CloseEvent</dfn> : <span>Event</span> {
|
|
readonly attribute boolean <a href="#dom-closeevent-wasclean" title="dom-CloseEvent-wasClean">wasClean</a>;
|
|
readonly attribute unsigned short <a href="#dom-closeevent-code" title="dom-CloseEvent-code">code</a>;
|
|
readonly attribute DOMString <span title="dom-WebSocket-reason">reason</span>;
|
|
};
|
|
|
|
dictionary <dfn id="closeeventinit">CloseEventInit</dfn> : <span>EventInit</span> {
|
|
boolean wasClean;
|
|
unsigned short code;
|
|
DOMString reason;
|
|
};</pre><p>The <dfn id="dom-closeevent-wasclean" title="dom-CloseEvent-wasClean"><code>wasClean</code></dfn>
|
|
attribute must return the value it was initialized to. When the
|
|
object is created, this attribute must be initialized to false. It
|
|
represents whether the connection closed cleanly or not.<p>The <dfn id="dom-closeevent-code" title="dom-CloseEvent-code"><code>code</code></dfn>
|
|
attribute must return the value it was initialized to. When the
|
|
object is created, this attribute must be initialized to zero. It
|
|
represents the WebSocket connection close code provided by the
|
|
server.<p>The <dfn id="dom-closeevent-reason" title="dom-CloseEvent-reason"><code>reason</code></dfn>
|
|
attribute must return the value it was initialized to. When the
|
|
object is created, this attribute must be initialized to empty
|
|
string. It represents the WebSocket connection close reason provided
|
|
by the server.<h2 id="garbage-collection"><span class="secno">9 </span>Garbage collection</h2><p>A <code><a href="#websocket">WebSocket</a></code> object whose <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's value
|
|
was set to <code title="dom-WebSocket-CONNECTING"><a href="#dom-websocket-connecting">CONNECTING</a></code>
|
|
(0) as of the last time the <span>event loop</span> started
|
|
executing a <span title="concept-task">task</span> must not be
|
|
garbage collected if there are any event listeners registered for
|
|
<code title="event-open">open</code> events, <code title="event-message">message</code> events, <code title="event-error">error</code> events, or <code title="event-close">close</code> events.<p>A <code><a href="#websocket">WebSocket</a></code> object whose <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's value
|
|
was set to <code title="dom-WebSocket-OPEN"><a href="#dom-websocket-open">OPEN</a></code> (1) as of
|
|
the last time the <span>event loop</span> started executing a <span title="concept-task">task</span> must not be garbage collected if
|
|
there are any event listeners registered for <code title="event-message">message</code> events, <code title="event-error">error</code>, or <code title="event-close">close</code> events.<p>A <code><a href="#websocket">WebSocket</a></code> object whose <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's value
|
|
was set to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2) as
|
|
of the last time the <span>event loop</span> started executing a
|
|
<span title="concept-task">task</span> must not be garbage collected
|
|
if there are any event listeners registered for <code title="event-error">error</code> or <code title="event-close">close</code> events.<p>A <code><a href="#websocket">WebSocket</a></code> object with <i title="the WebSocket
|
|
connection is established">an established connection</i> that has
|
|
data queued to be transmitted to the network must not be garbage
|
|
collected. <a href="#refsWSP">[WSP]</a><p>If a <code><a href="#websocket">WebSocket</a></code> object is garbage collected while its
|
|
connection is still open, the user agent must <i>start the
|
|
WebSocket closing handshake</i>, with no status code for the Close message. <a href="#refsWSP">[WSP]</a><hr><p>If a user agent is to <dfn id="make-disappear">make disappear</dfn> a
|
|
<code><a href="#websocket">WebSocket</a></code> object (this happens when a
|
|
<code>Document</code> object goes away), the user agent must follow
|
|
the first appropriate set of steps from the following list:<dl class="switch"><dt>If the WebSocket connection is not yet <i title="the WebSocket
|
|
connection is established">established</i> <a href="#refsWSP">[WSP]</a></dt>
|
|
|
|
<dd>
|
|
|
|
<p><i>Fail the WebSocket connection</i>. <a href="#refsWSP">[WSP]</a></p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the WebSocket closing handshake has not yet been <i title="the WebSocket closing handshake is started">started</i>
|
|
<a href="#refsWSP">[WSP]</a></dt>
|
|
|
|
<dd>
|
|
|
|
<p><i>Start the WebSocket closing handshake</i>, with the
|
|
status code<!--CLOSE CODE--> to use in the WebSocket Close message
|
|
being 1001. <a href="#refsWSP">[WSP]</a></p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Do nothing.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><h2 class="no-num" id="references">References</h2><p>All references are normative unless marked "Non-normative".</p><dl><dt id="refsCOOKIES">[COOKIES]</dt>
|
|
<dd><cite><a href="http://tools.ietf.org/html/rfc6265">HTTP State Management Mechanism</a></cite>, A. Barth. IETF.</dd>
|
|
|
|
<dt id="refsDOMCORE">[DOMCORE]</dt>
|
|
<dd><cite><a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html">DOM4</a></cite>, A. van Kesteren. W3C.</dd>
|
|
|
|
<dt id="refsFILEAPI">[FILEAPI]</dt>
|
|
<dd><cite><a href="http://dev.w3.org/2006/webapi/FileUpload/publish/FileAPI.html">File
|
|
API</a></cite>, A. Ranganathan. W3C.</dd>
|
|
|
|
<dt id="refsHTML">[HTML]</dt>
|
|
<dd><cite><a href="http://dev.w3.org/html5/spec/">HTML5</a></cite>,
|
|
I. Hickson. W3C.</dd>
|
|
|
|
<dt id="refsRFC2119">[RFC2119]</dt>
|
|
<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>
|
|
|
|
<dt id="refsRFC3629">[RFC3629]</dt>
|
|
<dd><cite><a href="http://tools.ietf.org/html/rfc3629">UTF-8, a
|
|
transformation format of ISO 10646</a></cite>, F. Yergeau. IETF.</dd>
|
|
|
|
<dt id="refsTYPEDARRAY">[TYPEDARRAY]</dt>
|
|
<dd><cite><a href="http://www.khronos.org/registry/typedarray/specs/latest/">Typed Array Specification</a></cite>, D. Herman, K. Russell. Khronos.</dd>
|
|
|
|
<dt id="refsWEBIDL">[WEBIDL]</dt>
|
|
<dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web
|
|
IDL</a></cite>, C. McCormack. W3C.</dd>
|
|
|
|
<dt id="refsWSP">[WSP]</dt>
|
|
<dd><cite><a href="http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol">The
|
|
WebSocket protocol</a></cite>, I. Fette. IETF.</dd>
|
|
|
|
</dl><h2 class="no-num" id="acknowledgements">Acknowledgements</h2><p>For a full list of acknowledgements, please see the HTML
|
|
specification. <a href="#refsHTML">[HTML]</a>
|