Skip to content

Commit

Permalink
Add a domintro block for WebSocket interface
Browse files Browse the repository at this point in the history 
This change adds a domintro block in the section that defines the WebSocket
interface and also the section that defines the CloseEvent interface.
Additionally, it adds markup to cause more implementor-specific parts of the
“Web sockets” section of the spec to be supressed in the developer edition.
  • Loading branch information
@sideshowbarker @domenic
sideshowbarker authored and domenic committed Oct 27, 2017
1 parent 7a579c1 commit 4ea65dc
Showing 1 changed file with 173 additions and 45 deletions.
218 changes: 173 additions & 45 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93294,7 +93294,7 @@ loadMySprites().then(runDemo);</pre>

<h2 split-filename="comms" id="comms">Communication</h2>

<h3>The <code>MessageEvent</code> interfaces</h3>
<h3>The <code>MessageEvent</code> interface</h3>

<p>Messages in <span>server-sent events</span>, <span>Web sockets</span>, <span>cross-document
messaging</span>, <span>channel messaging</span>, and <span>broadcast channels</span> use the
Expand Down Expand Up @@ -94260,22 +94260,115 @@ interface <dfn>WebSocket</dfn> : <span>EventTarget</span> {
void <span data-x="dom-WebSocket-send">send</span>(<span data-x="idl-ArrayBufferView">ArrayBufferView</span> data);
};</pre>

<p>Each <code>WebSocket</code> object has an associated <dfn
<p w-nodev>Each <code>WebSocket</code> object has an associated <dfn
data-x="concept-websocket-url">url</dfn> (a <span>URL record</span>).

<dl class="domintro">

<dt><var>socket</var> = new <code subdfn data-x="dom-WebSocket">WebSocket</code>(<var>url</var> [, <var>protocols</var> ] )</dt>
<dd>
<p>Creates a new <code>WebSocket</code> object, immediately establishing the associated
WebSocket connection.</p>

<p><var>url</var> is a string giving the <span>URL</span> over which the connection is
established. Only "<code data-x="">ws</code>" or "<code data-x="">wss</code>" schemes are
allowed; others will cause a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>. URLs with <span data-x="concept-url-fragment">fragments</span>
will also cause such an exception.</p>

<p><var>protocols</var> 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 have to match the requirements for elements that comprise the value of <code
data-x="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code> fields as defined by the
WebSocket protocol specification. <ref spec=WSP></p>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-send">send</code>( <var>data</var> )</dt>

<dd>
<p>Transmits <var>data</var> using the WebSocket connection. <var>data</var> can be a string, a
<code>Blob</code>, an <code data-x="idl-ArrayBuffer">ArrayBuffer</code>, or an <code
data-x="idl-ArrayBufferView">ArrayBufferView</code>.</p>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-close">close</code>( [ <var>code</var> ] [, <var>reason</var> ] )</dt>

<dd>
<p>Closes the WebSocket connection, optionally using <var>code</var> as the <span
data-x="concept-websocket-close-code">the WebSocket connection close code</span> and
<var>reason</var> as the <span data-x="concept-websocket-close-reason">the WebSocket connection
close reason</span>.</p>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-url">url</code></dt>

<dd>
<p>Returns the <span data-x="concept-websocket-url">URL that was used</span> to establish the
WebSocket connection.</p>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-readyState">readyState</code></dt>

<dd>
<p>Returns the state of the <code>WebSocket</code> object's connection. It can have the values
described below.</p>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-bufferedAmount">bufferedAmount</code></dt>

<dd>
<p>Returns the number of bytes of application data (UTF-8 text and binary data) that have been
queued using <code data-x="dom-WebSocket-send">send()</code> but not yet been transmitted to the
network.</p>

<p>If the WebSocket connection is closed, this attribute's value will only increase with each
call to the <code data-x="dom-WebSocket-send">send()</code> method. (The number does not reset
to zero once the connection closes.)</p>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-extensions">extensions</code></dt>

<dd>
<p>Returns the extensions selected by the server, if any.</p>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-protocol">protocol</code></dt>

<dd>
<p>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>
</dd>

<dt><var>socket</var> . <code subdfn data-x="dom-WebSocket-binaryType">binaryType</code> [ = <var>value</var> ]</dt>

<dd>
<p>Returns a string that indicates how binary data from the <code>WebSocket</code> object is
exposed to scripts:</p>

<dl>
<dt>"<code data-x="dom-BinaryType-blob">blob</code>"</dt>
<dd>
<p>Binary data is returned in <code>Blob</code> form.</p>
</dd>
<dt>"<code data-x="dom-BinaryType-arraybuffer">arraybuffer</code>"</dt>
<dd>
<p>Binary data is returned in <code data-x="idl-ArrayBuffer">ArrayBuffer</code> form.</p>
</dd>
</dl>

<p>Can be set, to change how binary data is returned. The default is "<code
data-x="dom-BinaryType-blob">blob</code>".</p>

</dd>

</dl>

<div w-nodev>

<p>The <dfn><code data-x="dom-WebSocket">WebSocket(<var>url</var>,
<var>protocols</var>)</code></dfn> constructor takes one or two arguments. The first argument,
<var>url</var>, specifies the <span>URL</span> to which to connect. The second,
<var>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 data-x="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code> fields as defined by the
WebSocket protocol specification. <ref spec=WSP></p>

<p>The <code data-x="dom-WebSocket">WebSocket(<var>url</var>, <var>protocols</var>)</code>
constructor, when invoked, must run these steps:</p>
<var>protocols</var>)</code></dfn> constructor, when invoked, must run these steps:</p>

<ol>
<li><p>Let <var>urlRecord</var> be the result of applying the <span>URL parser</span> to
Expand Down Expand Up @@ -94329,6 +94422,11 @@ interface <dfn>WebSocket</dfn> : <span>EventTarget</span> {
<p>The <dfn><code data-x="dom-WebSocket-readyState">readyState</code></dfn> attribute represents
the state of the connection. It can have the following values:</p>

</div>

<p w-nohtml>The <code data-x="dom-WebSocket-readyState">readyState</code> attribute can have the
following values:</p>

<dl>

<dt><dfn><code data-x="dom-WebSocket-CONNECTING">CONNECTING</code></dfn> (numeric value 0)</dt>
Expand All @@ -94351,24 +94449,19 @@ interface <dfn>WebSocket</dfn> : <span>EventTarget</span> {

</dl>

<div w-nodev>

<p>When the object is created its <code data-x="dom-WebSocket-readyState">readyState</code> must be
set to <code data-x="dom-WebSocket-CONNECTING">CONNECTING</code> (0).</p>

<p>The <dfn><code data-x="dom-WebSocket-extensions">extensions</code></dfn> attribute must
initially return the empty string. After <i data-x="concept-websocket-established">the WebSocket
connection is established</i>, its value might change, as defined below.</p>

<p class="note">The <code data-x="dom-WebSocket-extensions">extensions</code> attribute returns
the extensions selected by the server, if any.</p>

<p>The <dfn><code data-x="dom-WebSocket-protocol">protocol</code></dfn> attribute must initially
return the empty string. After <i data-x="concept-websocket-established">the WebSocket connection
is established</i>, its value might change, as defined below.</p>

<p class="note">The <code data-x="dom-WebSocket-protocol">protocol</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>

<p>The <dfn><code data-x="dom-WebSocket-close">close(<var>code</var>,
<var>reason</var>)</code></dfn> method, when invoked, must run these steps:</p>

Expand Down Expand Up @@ -94480,6 +94573,8 @@ interface <dfn>WebSocket</dfn> : <span>EventTarget</span> {

</ol>

</div>

<p class="note">The <code data-x="dom-WebSocket-close">close()</code> method does not discard
previously sent messages before starting the WebSocket closing handshake &mdash; even if, in
practice, the user agent is still busy sending those messages, the handshake will only start after
Expand All @@ -94488,16 +94583,14 @@ interface <dfn>WebSocket</dfn> : <span>EventTarget</span> {

<hr>

<p>The <dfn><code data-x="dom-WebSocket-bufferedAmount">bufferedAmount</code></dfn> attribute must
<p w-nodev>The <dfn><code data-x="dom-WebSocket-bufferedAmount">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 data-x="dom-WebSocket-send">send()</code> but that, as of the last time the
<span>event loop</span> reached <a href="#step1">step 1</a>, 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 in the background <span>in parallel</span> 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 data-x="dom-WebSocket-send">send()</code> method (the number does not reset to zero once
the connection closes).</p>
hardware.</p>

<div class="example">

Expand All @@ -94522,16 +94615,15 @@ socket.onopen = function () {

<hr>

<div w-nodev>

<p>When a <code>WebSocket</code> object is created, its <dfn><code
data-x="dom-WebSocket-binaryType">binaryType</code></dfn> IDL attribute must be set to the string
"<code data-x="dom-BinaryType-blob">blob</code>". On getting, it must return the last value it was
set to. On setting, the user agent must set the IDL attribute to the new value.</p>

<p class="note">This attribute allows authors to control how binary data is exposed to scripts. By
setting the attribute to "<dfn><code data-x="dom-BinaryType-blob">blob</code></dfn>", binary data
is returned in <code>Blob</code> form; by setting it to "<dfn><code
data-x="dom-BinaryType-arraybuffer">arraybuffer</code></dfn>", it is returned in
<code data-x="idl-ArrayBuffer">ArrayBuffer</code> form. User agents can use this as a hint for
"<code data-x="dom-BinaryType-blob">blob</code>". On getting, it must return the last
value it was set to. On setting, the user agent must set the IDL attribute to the new value.</p>

<p class="note">User agents can use the
<code data-x="dom-WebSocket-binaryType">binaryType</code> attribute as a hint for
how to handle incoming binary data: if the attribute is set to "<code
data-x="dom-BinaryType-blob">blob</code>", it is safe to spool it to disk, and if it is set to
"<code data-x="dom-BinaryType-arraybuffer">arraybuffer</code>", it is likely more efficient to
Expand Down Expand Up @@ -94631,12 +94723,14 @@ socket.onopen = function () {

</dl>

</div>

<hr>

<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) that must be supported, as <span>event
handler IDL attributes</span>, by all objects implementing the <code>WebSocket</code>
interface:</p>
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>WebSocket</code> interface:</p>

<table>
<thead>
Expand All @@ -94649,6 +94743,7 @@ socket.onopen = function () {
</table>


<div w-nodev>

<h4>Feedback from the protocol</h4>

Expand Down Expand Up @@ -94702,15 +94797,15 @@ socket.onopen = function () {
<dd>a new <code data-x="idl-DOMSTring">DOMString</code> containing <var>data</var></dd>

<dt><var>type</var> indicates that the data is Binary and <code
data-x="dom-WebSocket-binaryType">binaryType</code> is "<code
data-x="dom-BinaryType-blob">blob</code>"</dt>
data-x="dom-WebSocket-binaryType">binaryType</code> is "<dfn><code
data-x="dom-BinaryType-blob">blob</code></dfn>"</dt>
<dd>a new <code>Blob</code> object, created in the <span
data-x="concept-relevant-realm">relevant Realm</span> of the <code>WebSocket</code> object,
that represents <var>data</var> as its raw data <ref spec=FILEAPI></dd>

<dt><var>type</var> indicates that the data is Binary and <code
data-x="dom-WebSocket-binaryType">binaryType</code> is "<code
data-x="dom-BinaryType-arraybuffer">arraybuffer</code>"</dt>
data-x="dom-WebSocket-binaryType">binaryType</code> is "<dfn><code
data-x="dom-BinaryType-arraybuffer">arraybuffer</code></dfn>"</dt>
<dd>a new <code data-x="idl-ArrayBuffer">ArrayBuffer</code> object, created in the <span
data-x="concept-relevant-realm">relevant Realm</span> of the <code>WebSocket</code> object,
whose contents are <var>data</var></dd>
Expand Down Expand Up @@ -94741,6 +94836,8 @@ socket.onopen = function () {
stalling the main thread while it created the <code data-x="idl-ArrayBuffer">ArrayBuffer</code>
object.</p>

</div>

<div class="example">

<p>Here is an example of how to define a handler for the <code
Expand All @@ -94760,6 +94857,8 @@ socket.onopen = function () {

<hr>

<div w-nodev>

<p>When <i data-x="concept-websocket-closing-handshake">the WebSocket closing handshake is
started</i>, the user agent must <span>queue a task</span> to change the <code
data-x="dom-WebSocket-readyState">readyState</code> attribute's value to <code
Expand Down Expand Up @@ -94841,24 +94940,30 @@ socket.onopen = function () {
<p>The <span>task source</span> for all <span data-x="concept-task">tasks</span> <span data-x="queue
a task">queued</span> in this section is the <dfn>WebSocket task source</dfn>.</p>

</div>


<h4>Ping and Pong frames</h4>

<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>

<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 solicit pongs whenever appropriate for the server's needs.</p>
<p w-nodev>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 solicit pongs whenever appropriate for the server's
needs.</p>

<!-- v2: we'll probably add a way to make the client send pings and automatically terminate the
connection if they don't get a pong within an author-provided timeout; see
https://www.w3.org/Bugs/Public/show_bug.cgi?id=17264 -->


<h4>The <code>CloseEvent</code> interfaces</h4>
<h4>The <code>CloseEvent</code> interface</h4>

<p><code>WebSocket</code> objects use the <code>CloseEvent</code> interface for their <code
data-x="event-close">close</code> events:</p>

<pre class="idl">[Constructor(DOMString type, optional <span>CloseEventInit</span> eventInitDict), Exposed=(Window,Worker)]
interface <dfn>CloseEvent</dfn> : <span>Event</span> {
Expand All @@ -94873,6 +94978,27 @@ dictionary <dfn>CloseEventInit</dfn> : <span>EventInit</span> {
USVString reason = "";
};</pre>

<dl class="domintro">

<dt><var>event</var> . <code subdfn data-x="dom-CloseEvent-wasClean">wasClean</code></dt>
<dd>
<p>Returns true if the connection closed cleanly; false otherwise.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-CloseEvent-code">code</code></dt>
<dd>
<p>Returns the WebSocket connection close code provided by the server.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-CloseEvent-reason">reason</code></dt>
<dd>
<p>Returns the WebSocket connection close reason provided by the server.</p>
</dd>

</dl>

<div w-nodev>

<p>The <dfn><code data-x="dom-CloseEvent-wasClean">wasClean</code></dfn> attribute must return the
value it was initialized to. It represents whether the connection closed cleanly or not.</p>

Expand Down Expand Up @@ -94954,6 +95080,8 @@ dictionary <dfn>CloseEventInit</dfn> : <span>EventInit</span> {

</dl>

</div>


<h3 split-filename="web-messaging" id="web-messaging"><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h3>

Expand Down

0 comments on commit 4ea65dc

Please sign in to comment.