Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[giow] (0) WebSockets: binary data (first draft)
git-svn-id: http://svn.whatwg.org/webapps@6151 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
Hixie committed May 26, 2011
1 parent fca36ba commit 6e72262
Show file tree
Hide file tree
Showing 2 changed files with 370 additions and 59 deletions.
195 changes: 169 additions & 26 deletions complete.html
Expand Up @@ -239,7 +239,7 @@

<header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1>Web Applications 1.0</h1>
<h2 class="no-num no-toc">Living Standard &mdash; Last Updated 24 May 2011</h2>
<h2 class="no-num no-toc">Living Standard &mdash; Last Updated 26 May 2011</h2>
</hgroup><dl><dt>Multiple-page version:</dt>
<dd><a href=http://www.whatwg.org/specs/web-apps/current-work/complete/>http://www.whatwg.org/specs/web-apps/current-work/complete/</a></dd>
<dt>One-page version:</dt>
Expand Down Expand Up @@ -78822,12 +78822,17 @@ <h4 id=the-websocket-interface><span class=secno>11.3.2 </span>The <code><a href

// networking
attribute <a href=#function>Function</a> <a href=#handler-websocket-onopen title=handler-WebSocket-onopen>onopen</a>;
attribute <a href=#function>Function</a> <a href=#handler-websocket-onmessage title=handler-WebSocket-onmessage>onmessage</a>;
attribute <a href=#function>Function</a> <a href=#handler-websocket-onerror title=handler-WebSocket-onerror>onerror</a>;
attribute <a href=#function>Function</a> <a href=#handler-websocket-onclose title=handler-WebSocket-onclose>onclose</a>;
readonly attribute DOMString <a href=#dom-websocket-protocol title=dom-WebSocket-protocol>protocol</a>;
void <a href=#dom-websocket-send title=dom-WebSocket-send>send</a>(in DOMString data);
void <a href=#dom-websocket-close title=dom-WebSocket-close>close</a>();

// messaging
attribute <a href=#function>Function</a> <a href=#handler-websocket-onmessage title=handler-WebSocket-onmessage>onmessage</a>;
attribute Object <a href=#dom-websocket-binarytype title=dom-WebSocket-binaryType>binaryType</a>;
void <a href=#dom-websocket-send title=dom-WebSocket-send>send</a>(in DOMString data);
void <a href=#dom-websocket-send title=dom-WebSocket-send>send</a>(in <span>ArrayBuffer</span> data);
void <a href=#dom-websocket-send title=dom-WebSocket-send>send</a>(in <a href=#blob>Blob</a> data);
};
<a href=#websocket>WebSocket</a> implements <a href=#eventtarget>EventTarget</a>;</pre>

Expand Down Expand Up @@ -78965,21 +78970,6 @@ <h4 id=the-websocket-interface><span class=secno>11.3.2 </span>The <code><a href
conjunction with the array form of the constructor's second argument
to perform subprotocol negotiation.</p>

<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
raise an <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception. Otherwise, if the
<var title="">data</var> argument has any unpaired surrogates, then
it must raise <code><a href=#syntax_err>SYNTAX_ERR</a></code>. If the connection is
established, and the string has no unpaired surrogates, and <span title="the WebSocket closing handshake has started">the WebSocket
closing handshake has not yet started</span>, then the user agent
must <span>send <var title="">data</var> using the WebSocket</span>;
if the data cannot be sent, e.g. because it would need to be
buffered but the buffer is full, the user agent must <span>close the
WebSocket connection</span>. Any invokation of this method that does
not raise 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=#refsWSP>[WSP]</a></p>

<p>The <dfn id=dom-websocket-close title=dom-WebSocket-close><code>close()</code></dfn>
method must run the first matching steps from the following list:</p>

Expand Down Expand Up @@ -79086,7 +79076,108 @@ <h4 id=the-websocket-interface><span class=secno>11.3.2 </span>The <code><a href

</div>

<hr><p>The following are the <a href=#event-handlers>event handlers</a> that must be
<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 <code><a href=#blob>Blob</a></code> interface object
associated with the same global object as the <code title=dom-WebSocket><a href=#dom-websocket>WebSocket</a></code> constructor used to create
the <code><a href=#websocket>WebSocket</a></code> object. On getting, it must return the
last value it was set to. On setting, if the new value is either the
<code><a href=#blob>Blob</a></code> or <code>ArrayBuffer</code> interface object
associated with the same global object as the <code title=dom-WebSocket><a href=#dom-websocket>WebSocket</a></code> constructor used to create
the <code><a href=#websocket>WebSocket</a></code> object, then set the IDL attribute to
this new value. Otherwise, throw a <code><a href=#not_supported_err>NOT_SUPPORTED_ERR</a></code>
exception.</p>

<p class=note>This attribute allows authors to control how binary
data is exposed to scripts. By setting the attribute to
<code><a href=#blob>Blob</a></code>, binary data is returned in <code><a href=#blob>Blob</a></code>
form; by setting it to <code>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><a href=#blob>Blob</a></code>, it is safe to spool it to disk, and if it is set
to <code>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>

<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
raise an <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception. Otherwise, the
user agent must run the appropriate set of steps from the following
list:</p>

<dl><dt>If the argument is a string</dt>

<dd>

<p>If the <var title="">data</var> argument has any unpaired
surrogates, then raise an <code><a href=#syntax_err>SYNTAX_ERR</a></code> exception. If
the connection is established, and the string has no unpaired
surrogates, and <span title="the WebSocket closing handshake has
started">the WebSocket closing handshake has not yet
started</span>, then the user agent must <span>send <var title="">data</var> using the WebSocket</span> 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
<span>close the WebSocket connection</span>. Any invokation of
this method with a string argument that does not raise 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=#refsWSP>[WSP]</a></p>

</dd>


<dt>If the argument is a <code><a href=#blob>Blob</a></code> object</dt>

<dd>

<p>If the connection is established, and <span title="The
WebSocket Closing Handshake is Started">the WebSocket closing
handshake has not yet started</span>, then the user agent must
<span>send <var title="">data</var> using the WebSocket</span>
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 <span>close the WebSocket connection</span>. The
data to be sent is the raw data represented by the
<code><a href=#blob>Blob</a></code> object. <!-- that sentence is meant to invoke
"This interface represents immutable raw data." --> Any invokation
of this method with a <code><a href=#blob>Blob</a></code> argument that does not
raise 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><a href=#blob>Blob</a></code> object's raw data,
in bytes. <!-- that sentence is meant to invoke the same as
Blob.size --> <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 the connection is established, and <span title="The
WebSocket Closing Handshake is Started">the WebSocket closing
handshake has not yet started</span>, then the user agent must
<span>send <var title="">data</var> using the WebSocket</span>
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 <span>close the WebSocket connection</span>. The
data to be sent is the data stored in the buffer described by the
<code>ArrayBuffer</code> object. <!-- that sentence is meant to
invoke "The ArrayBuffer type describes a buffer used to store data
for the array buffer views." at the top of the Typed Array spec
--> Any invokation of this method with an <code>ArrayBuffer</code>
argument that does not raise 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.
<!-- that sentence is meant to invoke the same as
ArrayBuffer.byteLength --> <a href=#refsWSP>[WSP]</a> <a href=#refsTYPEDARRAY>[TYPEDARRAY]</a></p>

</dd>

</dl><hr><p>The following are the <a href=#event-handlers>event handlers</a> that must be
supported, as IDL attributes, by all objects implementing the
<code><a href=#websocket>WebSocket</a></code> interface:</p>

Expand Down Expand Up @@ -79120,13 +79211,62 @@ <h4 id=the-websocket-interface><span class=secno>11.3.2 </span>The <code><a href
and then <a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-open>open</code> at the <code><a href=#websocket>WebSocket</a></code> object.
<a href=#refsWSP>[WSP]</a></p>

<p>When <i>a WebSocket message has been received</i> with text <var title="">data</var>, the user agent must create an event that uses
the <code><a href=#messageevent>MessageEvent</a></code> interface, with the event name <code title=event-message><a href=#event-message>message</a></code>, which does not bubble, is not
cancelable, has no default action, and whose <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute is set to <var title="">data</var>, and <a href=#queue-a-task>queue a task</a> to check to see
if the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code>
attribute's value is <code title=dom-WebSocket-OPEN><a href=#dom-websocket-open>OPEN</a></code>
(1) or <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2), and
if so, dispatch the event at the <code><a href=#websocket>WebSocket</a></code> object. <a href=#refsWSP>[WSP]</a></p>
<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 <a href=#queue-a-task>queue a task</a> to follow these steps: <a href=#refsWSP>[WSP]</a></p>

<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) or <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2), then abort these
steps.</p>

</li>

<li>

<p>Let <var title="">event</var> be an event that uses the
<code><a href=#messageevent>MessageEvent</a></code> interface, with the event name <code title=event-message><a href=#event-message>message</a></code>, which does not bubble, is
not cancelable, and has no default action.</p>

</li>

<li>

<p>If <var title="">type</var> indicates that the data is Text,
then set <var title="">event</var>'s <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></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><a href=#blob>Blob</a></code>, then set <var title="">event</var>'s
<code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute to a new
<code><a href=#blob>Blob</a></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>ArrayBuffer</code>, then set <var title="">event</var>'s <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></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 <a href=#task-queue title="task queue">task queues</a>
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><a href=#blob>Blob</a></code> when the data arrived, and the user agent
spooled all the data to disk, but just before running the above
<a href=#concept-task title=concept-task>task</a> for this particular message
the script switched <code title=dom-WebSocket-binaryType><a href=#dom-websocket-binarytype>binaryType</a></code> to
<code>ArrayBuffer</code>, the user agent would want to page the data
back to RAM before running this <a href=#concept-task title=concept-task>task</a> so as to avoid stalling the main
thread while it created the <code>ArrayBuffer</code> object.</p>

<p>When <i>a WebSocket error has been detected</i>, the user agent
must <a href=#queue-a-task>queue a task</a> to check to see if the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's value
Expand Down Expand Up @@ -99093,6 +99233,9 @@ <h3 class="no-num">Reflecting IDL attributes</h3>
<dt id=refsTURN>[TURN]</dt>
<dd><cite><a href=http://tools.ietf.org/html/rfc5766>Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)</a></cite>, R. Mahy, P. Matthews, J. Rosenberg. 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=refsUAAG>[UAAG]</dt>
<dd>(Non-normative) <cite><a href=http://www.w3.org/TR/UAAG20/>Web Content Accessibility
Guidelines (UAAG) 2.0</a></cite>, J. Allan, K. Ford, J. Richards,
Expand Down

0 comments on commit 6e72262

Please sign in to comment.