--- a/Overview_old.htm Mon Feb 11 09:40:34 2013 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1569 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html dir="ltr" lang="en"><head>
- <title>Streams API</title>
- <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
-
- <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
- <link rel="stylesheet" type="text/css" href="http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css">
- <meta name="GENERATOR" content="MSHTML 8.00.7600.16588">
-
- <!-- Styles to mimic File API spec -->
- <style type="text/css">
- table.error { border-collapse:collapse; border-style:hidden hidden none hidden }
- table.error thead { border-bottom:solid }
- table.error tbody th:first-child { border-left:solid }
- table.error td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
- </style>
-
-<style>
-
-/* --- INLINES --- */
-em.rfc2119 {
- text-transform: lowercase;
- font-variant: small-caps;
- font-style: normal;
- color: #900;
-}
-
-h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
-h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
- border: none;
-}
-
-dfn {
- font-weight: bold;
-}
-
-a.internalDFN {
- color: inherit;
- border-bottom: 1px solid #99c;
- text-decoration: none;
-}
-
-a.externalDFN {
- color: inherit;
- border-bottom: 1px dotted #ccc;
- text-decoration: none;
-}
-
-a.bibref {
- text-decoration: none;
-}
-
-cite .bibref {
- font-style: normal;
-}
-
-code {
- color: #ff4500;
-}
-
-
-/* --- --- */
-ol.algorithm { counter-reset:numsection; list-style-type: none; }
-ol.algorithm li { margin: 0.5em 0; }
-ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }
-
-/* --- TOC --- */
-.toc a, .tof a {
- text-decoration: none;
-}
-
-a .secno, a .figno {
- color: #000;
-}
-
-ul.tof, ol.tof {
- list-style: none outside none;
-}
-
-.caption {
- margin-top: 0.5em;
- font-style: italic;
-}
-
-/* --- TABLE --- */
-table.simple {
- border-spacing: 0;
- border-collapse: collapse;
- border-bottom: 3px solid #005a9c;
-}
-
-.simple th {
- background: #005a9c;
- color: #fff;
- padding: 3px 5px;
- text-align: left;
-}
-
-.simple th[scope=row] {
- background: inherit;
- color: inherit;
- border-top: 1px solid #ddd;
-}
-
-.simple td {
- padding: 3px 10px;
- border-top: 1px solid #ddd;
-}
-
-.simple tr:nth-child(even) {
- background: #f0f6ff;
-}
-
-/* --- DL --- */
-.section dd > p:first-child {
- margin-top: 0;
-}
-
-.section dd > p:last-child {
- margin-bottom: 0;
-}
-
-.section dd {
- margin-bottom: 1em;
-}
-
-.section dl.attrs dd, .section dl.eldef dd {
- margin-bottom: 0;
-}
-</style><style>/* --- EXAMPLES --- */
-div.example-title {
- min-width: 7.5em;
- color: #b9ab2d;
-}
-div.example-title span {
- text-transform: uppercase;
-}
-aside.example, div.example, div.illegal-example {
- padding: 0.5em;
- margin: 1em 0;
- position: relative;
- clear: both;
-}
-div.illegal-example { color: red }
-div.illegal-example p { color: black }
-aside.example, div.example {
- padding: .5em;
- border-left-width: .5em;
- border-left-style: solid;
- border-color: #e0cb52;
- background: #fcfaee;
-}
-
-aside.example div.example {
- border-left-width: .1em;
- border-color: #999;
- background: #fff;
-}
-aside.example div.example div.example-title {
- color: #999;
-}
-</style><style>/* --- WEB IDL --- */
-pre.idl {
- border-top: 1px solid #90b8de;
- border-bottom: 1px solid #90b8de;
- padding: 1em;
- line-height: 120%;
-}
-
-pre.idl::before {
- content: "WebIDL";
- display: block;
- width: 150px;
- background: #90b8de;
- color: #fff;
- font-family: initial;
- padding: 3px;
- font-weight: bold;
- margin: -1em 0 1em -1em;
-}
-
-.idlType {
- color: #ff4500;
- font-weight: bold;
- text-decoration: none;
-}
-
-/*.idlModule*/
-/*.idlModuleID*/
-/*.idlInterface*/
-.idlInterfaceID, .idlDictionaryID, .idlCallbackID, .idlEnumID {
- font-weight: bold;
- color: #005a9c;
-}
-
-.idlSuperclass {
- font-style: italic;
- color: #005a9c;
-}
-
-/*.idlAttribute*/
-.idlAttrType, .idlFieldType, .idlMemberType {
- color: #005a9c;
-}
-.idlAttrName, .idlFieldName, .idlMemberName {
- color: #ff4500;
-}
-.idlAttrName a, .idlFieldName a, .idlMemberName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlMethod*/
-.idlMethType, .idlCallbackType {
- color: #005a9c;
-}
-.idlMethName {
- color: #ff4500;
-}
-.idlMethName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlParam*/
-.idlParamType {
- color: #005a9c;
-}
-.idlParamName {
- font-style: italic;
-}
-
-.extAttr {
- color: #666;
-}
-
-/*.idlConst*/
-.idlConstType {
- color: #005a9c;
-}
-.idlConstName {
- color: #ff4500;
-}
-.idlConstName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlException*/
-.idlExceptionID {
- font-weight: bold;
- color: #c00;
-}
-
-.idlTypedefID, .idlTypedefType {
- color: #005a9c;
-}
-
-.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
- color: #c00;
- font-weight: normal;
-}
-
-.excName a {
- font-family: monospace;
-}
-
-.idlRaises a.idlType, .excName a.idlType {
- border-bottom: 1px dotted #c00;
-}
-
-.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
- width: 45px;
- text-align: center;
-}
-.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
-.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
-
-.idlImplements a {
- font-weight: bold;
-}
-
-dl.attributes, dl.methods, dl.constants, dl.fields, dl.dictionary-members {
- margin-left: 2em;
-}
-
-.attributes dt, .methods dt, .constants dt, .fields dt, .dictionary-members dt {
- font-weight: normal;
-}
-
-.attributes dt code, .methods dt code, .constants dt code, .fields dt code, .dictionary-members dt code {
- font-weight: bold;
- color: #000;
- font-family: monospace;
-}
-
-.attributes dt code, .fields dt code, .dictionary-members dt code {
- background: #ffffd2;
-}
-
-.attributes dt .idlAttrType code, .fields dt .idlFieldType code, .dictionary-members dt .idlMemberType code {
- color: #005a9c;
- background: transparent;
- font-family: inherit;
- font-weight: normal;
- font-style: italic;
-}
-
-.methods dt code {
- background: #d9e6f8;
-}
-
-.constants dt code {
- background: #ddffd2;
-}
-
-.attributes dd, .methods dd, .constants dd, .fields dd, .dictionary-members dd {
- margin-bottom: 1em;
-}
-
-table.parameters, table.exceptions {
- border-spacing: 0;
- border-collapse: collapse;
- margin: 0.5em 0;
- width: 100%;
-}
-table.parameters { border-bottom: 1px solid #90b8de; }
-table.exceptions { border-bottom: 1px solid #deb890; }
-
-.parameters th, .exceptions th {
- color: #fff;
- padding: 3px 5px;
- text-align: left;
- font-family: initial;
- font-weight: normal;
- text-shadow: #666 1px 1px 0;
-}
-.parameters th { background: #90b8de; }
-.exceptions th { background: #deb890; }
-
-.parameters td, .exceptions td {
- padding: 3px 10px;
- border-top: 1px solid #ddd;
- vertical-align: top;
-}
-
-.parameters tr:first-child td, .exceptions tr:first-child td {
- border-top: none;
-}
-
-.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
- width: 100px;
-}
-
-.parameters td.prmType {
- width: 120px;
-}
-
-table.exceptions table {
- border-spacing: 0;
- border-collapse: collapse;
- width: 100%;
-}
-</style>
-<!--<link href="Overview_files/W3C-ED.css" rel="stylesheet">-->
-
-</head>
-
-<body><div class="head">
- <p>
- <a href="http://www.w3.org/"><img height="48" width="72" alt="W3C" src="http://www.w3.org/Icons/w3c_home"></a>
- </p>
- <h1 class="title" id="title">Streams API</h1>
-
- <h2 id="w3c-editor-s-draft-25-october-2012"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 25 October 2012</h2>
- <dl>
-
- <dt>This version:</dt>
- <dd><a href="http://dvcs.w3.org/hg/streams-api/Overview.html">http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm</a></dd>
- <dt>Latest published version:</dt>
- <dd><a href="http://www.w3.org/TR/streams-api/">http://www.w3.org/TR/streams-api/</a></dd>
-
-
- <dt>Latest editor's draft:</dt>
- <dd><a href="http://dvcs.w3.org/hg/streams-api/Overview.html">http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm</a></dd>
-
-
-
-
-
-
-
-
- <dt>Editor:</dt>
- <dd><a href="mailto:feras.moussa@hotmail.com">Feras Moussa</a>, Invited Expert</dd>
-
-
- </dl>
-
-
-
-
-
- <p class="copyright">
- <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> ©
- 2012
-
- <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.
- <abbr title="World Wide Web Consortium">W3C</abbr> <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>
-
-
- <hr>
-</div>
-
-<section class="introductory" id="abstract"><h2>Abstract</h2>
- <!-- TODO: are all of the links and objects in the abstract formatted? -->
- <p>
- This specification provides an API for representing binary data in web applications as a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> object,
- as well as programmatically building and reading its contents. This includes:
- </p>
- <ul>
- <li>A <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> interface, which represents a sequence of data that can be read over time.</li>
- <li>A <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> interface, which provides methods to read the contents of a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> as a
- <code>Blob</code>, <code>DataURL</code>, <code>ArrayBuffer</code>, or as <code>Text</code>.</li>
- <li>A <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> interface, which allows for creating a new <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> whose contents is read from an internal buffer that was made by appending <code>Text</code>, <code>Blobs</code>, or <code>ArrayBuffers</code>.</li>
- <li>Extensions to <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-xmlhttprequest-interface">XmlHttpRequest</a> [<cite><a href="#bib-XMLHTTPREQUEST2" class="bibref">XMLHTTPREQUEST2</a></cite>] to add support for upload and download of a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.</li>
- <li>
- Extensions to <a href="http://dev.w3.org/2006/webapi/FileAPI/#FileErrorInterface">FileError</a> and
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#FileException">FileException</a> to encompass <a href="#streamerror-error">Stream Errors</a>.</li>
- <li>
- Extensions to <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-createObjectURL">createObjectURL</a> and
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-revokeObjectURL">revokeObjectURL</a> to add support for <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.</li>
- </ul>
- <p>
- Additionally, this specification defines objects to be used within
-threaded web applications for the synchronous reading of a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
- <p>
- This API is designed to be used in conjunction with other APIs and elements on the web platform, notably:
- <a href="http://dev.w3.org/2006/webapi/FileAPI">File</a> [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>],
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2">XMLHttpRequest</a>
- (e.g. with an overloaded <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-send-method"><code>send()</code></a> method
- and <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-responsetype-attribute"><code>response</code></a> object for <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> objects) [<cite><a href="#bib-XMLHTTPREQUEST2" class="bibref">XMLHTTPREQUEST2</a></cite>],
- <a href="http://dev.w3.org/html5/postmsg/#dom-window-postmessage"><code>postMessage</code></a>, and
- Web Workers [<cite><a href="#bib-WEBWORKERS" class="bibref">WEBWORKERS</a></cite>].
- </p>
-<!--End section: Abstract-->
-</section><section id="sotd" class="introductory"><h2>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 <abbr title="World Wide Web Consortium">W3C</abbr> publications and the latest revision
- of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports
- index</a> at http://www.w3.org/TR/.</em>
- </p>
-
- <p>
- This document was published by the <a href="http://www.w3.org/2008/webapps/"><abbr title="World Wide Web Consortium">W3C</abbr> Web Applications (WebApps)</a> as an Editor's Draft.
-
- If you wish to make comments regarding this document, please send them 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>).
-
-
- All feedback is welcome.
- </p>
-
- <p>
- Publication as an Editor's Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr> Membership.
- This is a draft document and may be updated, replaced or obsoleted by other documents at
- any time. It is inappropriate to cite this document as other than work in progress.
- </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 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
-
-
-
-
- <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="" 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 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
-
-
- </p>
-
-
-
-
-</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a class="tocxref" href="#introduction"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a class="tocxref" href="#stream%20interface"><span class="secno">2. </span>The Stream Interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes"><span class="secno">2.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods"><span class="secno">2.2 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#streamreader-interface"><span class="secno">3. </span>The StreamReader Interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-1"><span class="secno">3.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods-1"><span class="secno">3.2 </span>Methods</a></li><li class="tocline"><a class="tocxref" href="#constants"><span class="secno">3.3 </span>Constants</a></li><li class="tocline"><a class="tocxref" href="#streamreader-event-handler-types"><span class="secno">3.4 </span>Event Handler Attributes</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#streamreader-event-summary"><span class="secno">3.4.1 </span>Event Summary</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#streamreadersync-interface"><span class="secno">4. </span>The StreamReaderSync Interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#methods-2"><span class="secno">4.1 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#reading-empty-stream"><span class="secno">5. </span>Determining an empty Stream</a></li><li class="tocline"><a class="tocxref" href="#errors-and-exceptions"><span class="secno">6. </span>Errors and Exceptions</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#streamerror-error"><span class="secno">6.1 </span>StreamError</a></li><li class="tocline"><a class="tocxref" href="#streamexception-error"><span class="secno">6.2 </span>StreamException</a></li></ul></li><li class="tocline"><a class="tocxref" href="#streambuilder-interface"><span class="secno">7. </span>The StreamBuilder Interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-2"><span class="secno">7.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods-3"><span class="secno">7.2 </span>Methods</a></li><li class="tocline"><a class="tocxref" href="#reads-on-a-stream-from-streambuilder"><span class="secno">7.3 </span>Reads on a Stream from StreamBuilder</a></li><li class="tocline"><a class="tocxref" href="#streambuilder-event-handler-types"><span class="secno">7.4 </span>Event Handler Attributes</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#streambuilder-event-summary"><span class="secno">7.4.1 </span>Event Summary</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#error-uris_for_streams"><span class="secno">8. </span>URIs for Stream</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#creating-revoking-streamuri"><span class="secno">8.1 </span>Creating and Revoking a Stream URI</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#methods-4"><span class="secno">8.1.1 </span>Methods</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#security"><span class="secno">9. </span>Security Considerations</a></li><li class="tocline"><a class="tocxref" href="#XMLHttpRequest"><span class="secno">10. </span>Extension of XMLHttpRequest</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#addition-of-stream-responsetype"><span class="secno">10.1 </span>Addition of stream responseType</a></li><li class="tocline"><a class="tocxref" href="#readystate3-changes"><span class="secno">10.2 </span>readyState 3 changes</a></li><li class="tocline"><a class="tocxref" href="#send0"><span class="secno">10.3 </span>send()</a></li></ul></li><li class="tocline"><a class="tocxref" href="#requirements"><span class="secno">11. </span>Requirements and Use Cases</a></li><li class="tocline"><a class="tocxref" href="#acknowledgements"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a class="tocxref" href="#references"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><span class="secno">B.1 </span>Normative references</a></li></ul></li></ul></section>
-
-<section id="introduction" class="section informative">
- <!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
-
- <p>
- Web applications should have the ability to acquire and manipulate data in a wide variety of forms,
- including as a sequence of data made available over time.
- This specification defines the basic representation for <a href="#idl-def-Stream"><code>Streams</code></a>,
- errors raised by <a href="#idl-def-Stream"><code>Streams</code></a>,
- and programmatic ways to read and create <a href="#idl-def-Stream"><code>Streams</code></a>.
- </p>
- <p>
- The <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> interface represents binary data which can be obtained over time. A <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> can come from APIs
- such as <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-xmlhttprequest-interface"><code>XMLHttpRequest</code></a>, or can
- be built using <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a>.
- The <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> interface represents a way to read data
- from a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> as a <code>Blob</code>, <code>DataURL</code>, <code>ArrayBuffer</code>, or as <code>Text</code>,
- and should happen asynchronously on the user agent’s main thread,
- with an optional synchronous API used within threaded web applications.
- An asynchronous API for reading <a href="#idl-def-Stream"><code>Streams</code></a> prevents blocking and UI “freezing” on a user agent’s main thread.
- This specification defines an asynchronous API based on an event model to read and access a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>,
- which is closely based on the FileReader interface defined in the [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>].
- A <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> object provides asynchronous read methods to access the <a href="#idl-def-Stream"><code>Stream's</code></a> data as a
- <code>Blob</code>, <code>DataURL</code>, <code>ArrayBuffer</code>, or as <code>Text</code> through event handler attributes and the firing of events.
- The use of events and event handlers allows separate code blocks the ability to monitor the progress of the read
- (which is particularly useful for long <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> reads or high latency network requests)
- and error conditions that may arise during reading of a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>. An example will be illustrative.
- </p>
- <p>
- In the example below, different code blocks handle progress, error, and success conditions.
- The example demonstrates how to read a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> using <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a>.
- </p>
- <div class="example"><div class="example-title"><span>Example 1</span></div><pre class="example">function startRead(stream) {
-
- var reader = new StreamReader();
-
- // Handle progress, success, and errors
- reader.onprogress = updateProgress;
- reader.onload = loaded;
- reader.onerror = errorHandler;
-
- // Read the first 1024 bytes of the stream as UTF-8
- reader.readAsText(stream, "UTF-8", 1024);
-}
-
-function updateProgress(evt) {
- var bytesLoaded = (evt.loaded / 1024);
- // Increase bytes loaded counter
-}
-
-function loaded(evt) {
- // Obtain the read stream data
- var streamRead = evt.target.result;
-
-}
-
-function errorHandler(evt) {
- if(evt.target.error.name == "NOT_READABLE_ERR") {
- // The stream could not be read
- }
-}</pre></div>
-
- <p>
- In the example below, different code blocks handle progress, error, and success conditions.
- The example below demonstrates how to obtain a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> from <code>XMLHttpRequest</code> to begin playing a large video in <code>readystate</code> 3.
- </p>
- <div class="example"><div class="example-title"><span>Example 2</span></div><pre class="example">function handler() {
- if(this.readyState == this.LOADING) {
- var theStream = this.response;
- var streamURL = URL.createObjectURL(theStream);
- document.getElementById("myVideoTag").src = streamURL;
- }
-}
-
-var client = new XMLHttpRequest();
-client.onreadystatechange = handler;
-client.setRequestHeader('customHeader', 'value');
-client.setRequestHeader('customHeader2', 'value2');
-client.open("GET", "myvideo.h264");
-client.responseType = "stream";
-client.send();</pre></div>
-
- <p>
- In addition to reading a Stream, this specification introduces a programatic way to build a Stream with the <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> interface.
- The <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> interface represents a way to provide the data to be read from a Stream by appending the data to an internal buffer.
- <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> supports appending <code>Blob</code>, <code>ArrayBuffer</code>, and <code>Text</code> data to the buffer.
- <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> also provides an event to notify when the data available to be read from the buffer has fallen below a given threshold.
- </p>
- <p>
- The example below demonstrates how to use <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> to load a stream into the audio tag, whose data is processed and built dynamically at read time.
- The <code>thresholdReached</code> event is fired when the buffer falls below 1024 bytes.
- </p>
-
-<div class="example"><div class="example-title"><span>Example 3</span></div><pre class="example">function thresholdReached(){
- var moreData = //do work to create more data to place into the stream
-
- //if we have no more data to process and place in the stream, we close
- if(moreData == null){
- sbuilder.close();
- } else{
- sbuiler.append(moreData);
- }
-}
-
-var sbuilder = new StreamBuilder("audio/mp3", 1024);
-var sbuilder.onthresholdreached = thresholdReached;
-
-var streamURL = URL.createObjectURL(sbuilder.stream);
-document.getElementById('audioTag').src = streamURL;</pre></div>
-<!--End section: Introduction-->
-</section>
-
-<section class="section" id="stream interface">
-<!--OddPage--><h2><span class="secno">2. </span>The Stream Interface</h2>
-
- <p>
- This interface represents a raw sequence of linear data which can be read over time.
- It provides an attribute representing the type of data represented by the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
- <p>A <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> is an object that:</p>
- <ul>
- <li>Has a content type;</li>
- <li>Has unspecified length;</li>
- <li>Can generally be used in the same places <code>Blob</code> can be used, such as <code>URL.createObjectURL()</code></li>
- </ul>
- <pre class="idl"><span class="idlInterface" id="idl-def-Stream">interface <span class="idlInterfaceID">Stream</span> {
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-Stream-type">type</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Stream-close-void">close</a></span> ();</span>
-};</span></pre><section id="attributes"><h3><span class="secno">2.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-Stream-type"><code>type</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
- The ASCII-encoded string in lower case representing the media type of the <code>Stream</code>,
- expressed as an RFC2046 MIME type [<cite><a href="#bib-RFC2046" class="bibref">RFC2046</a></cite>].
- Conforming user agents <em title="should" class="rfc2119">should</em> return the MIME type of the <code>Stream</code>, if it is known.
- If conforming user agents cannot determine the media type of the <code>Stream</code>, they <em title="must" class="rfc2119">must</em> return the empty string.
- A string is a valid MIME type if it matches the media-type token defined in section 3.7 "Media Types" of RFC 2616 [<cite><a href="#bib-HTTP11" class="bibref">HTTP11</a></cite>].
- </dd></dl></section><section id="methods"><h3><span class="secno">2.2 </span>Methods</h3><dl class="methods"><dt id="widl-Stream-close-void"><code>close</code></dt><dd>
- This method should close the Stream and not allow any future reads.
-This is done by returning on the next and subsequent reads with no data.
- This is an irreversible and non-idempotent operation; once a <code>Stream</code>
- has been closed, it cannot be used again; dereferencing a Stream URI
-bound to a Stream object on which close has been called results in a <a href="http://www.w3.org/TR/FileAPI/#FiveHundredInternalServerError">500 Error</a>.
- <div><em>No parameters.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
-</section>
-<!-- End section: The Stream Interface -->
-
-<section class="section" id="streamreader-interface">
-<!--OddPage--><h2><span class="secno">3. </span>The StreamReader Interface</h2>
- <p>
- This interface provides methods to read the data of a <code>Stream</code> using progress events and event handler attributes.
- It is desirable to read data from <a href="file:///C:/Streams/idl-def-Stream">Streams</a> asynchronously in the main thread of user agents.
- This interface provides such an asynchronous API, and is specified to be used with the global object
- (<a href="http://www.w3.org/TR/2011/WD-html5-20110525/browsers.html#the-window-object">Window</a> [<cite><a href="#bib-HTML5" class="bibref">HTML5</a></cite>]).
- The <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> is designed in a way to closely follow the <abbr title="World Wide Web Consortium">W3C</abbr> <a href="http://dev.w3.org/2006/webapi/FileAPI/#FileReader-interface">FileReader</a> [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>],
- and thus only identifies changes or additions to the way <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-filereader">FileReader methods</a> behave.
- </p>
- <p>
- When the <code>StreamReader()</code> constructor is invoked, the user agent <em title="must" class="rfc2119">must</em> return a new <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> object.
- </p>
- <p>
- In environments where the global object is represented by a <code>Window</code> or a <code>WorkerGlobalScope</code> object,
- the <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> constructor <em title="must" class="rfc2119">must</em> be available.
- </p>
- <p>
- For event handler attributes, event handlers for <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> should mimic
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#event-handler-attributes-section">6.4.3 Event Handler Attributes</a> of the File API specification. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- </p>
- <p>
- For states, event handlers for <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#blobreader-state">6.4.4 FileReader States</a>
- of the File API specification, except as defined below for <a href="#widl-StreamReader-DONE"><code>DONE</code></a> (numeric value of 2). [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- </p>
- <p>
- Multiple reads on <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> should mimic
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#MultipleReads">6.4.5.1 Multiple Reads</a> of the File API specification. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- </p>
-
-
- <pre class="idl"><span class="idlInterface" id="idl-def-StreamReader">interface <span class="idlInterfaceID">StreamReader</span> : <span class="idlSuperclass"><a>EventTarget</a></span> {
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamReader-readAsBlob-void-Stream-stream-unsigned-long-long-maxSize">readAsBlob</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamReader-readAsArrayBuffer-void-Stream-stream-unsigned-long-long-maxSize">readAsArrayBuffer</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamReader-readAsText-void-Stream-stream-DOMString-encoding-optional-unsigned-long-long-maxSize">readAsText</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">encoding</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>optional unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamReader-readAsDataURL-void-Stream-Stream-unsigned-long-long-maxSize">readAsDataURL</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">Stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamReader-abort-void">abort</a></span> ();</span>
-<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#EMPTY">EMPTY</a></span> = <span class="idlConstValue">0</span>;</span>
-<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#LOADING">LOADING</a></span> = <span class="idlConstValue">1</span>;</span>
-<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#DONE">DONE</a></span> = <span class="idlConstValue">2</span>;</span>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-readyState">readyState</a></span>;</span>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-result">result</a></span>;</span>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>StreamError</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-error">error</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-onloadstart">onloadstart</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-onprogress">onprogress</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-onload">onload</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-onabort">onabort</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-onerror">onerror</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-StreamReader-onloadend">onloadend</a></span>;</span>
-};</span></pre><section id="attributes-1"><h3><span class="secno">3.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-StreamReader-error"><code>error</code> of type <span class="idlAttrType"><a>StreamError</a></span>, readonly</dt><dd></dd><dt id="widl-StreamReader-onabort"><code>onabort</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
- This event handler should mimic the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-onabort"><code>FileReader.onabort</code></a>
- event handler.
- </dd><dt id="widl-StreamReader-onerror"><code>onerror</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
- This event handler should mimic the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-onerror"><code>FileReader.onerror</code></a>
- event handler.
- </dd><dt id="widl-StreamReader-onload"><code>onload</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
- This event handler should mimic the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-onload"><code>FileReader.onload</code></a>
- event handler.
- </dd><dt id="widl-StreamReader-onloadend"><code>onloadend</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
- This event handler should mimic the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-onloadend"><code>FileReader.onloadend</code></a>
- event handler.
- </dd><dt id="widl-StreamReader-onloadstart"><code>onloadstart</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
- This event handler should mimic the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-onloadstart"><code>FileReader.onloadstart</code></a>
- event handler.
- </dd><dt id="widl-StreamReader-onprogress"><code>onprogress</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
- This event handler should mimic the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-onprogress"><code>FileReader.onprogress</code></a>
- event handler.
- </dd><dt id="widl-StreamReader-readyState"><code>readyState</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd></dd><dt id="widl-StreamReader-result"><code>result</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>
- This attribute should mimic the <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-result">FileReader.result</a> attribute, with the following addition:
- <ul>
- <li>
- On getting, if the
- <a href="#widl-StreamReader-readAsBlob-void-Stream-stream-int-maxSize">readAsBlob</a> read method is used,
- this attribute <em title="must" class="rfc2119">must</em> return a <code>Blob</code> of the data read from the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>
- with the type property set as the type of the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </li>
- </ul>
- </dd></dl></section><section id="methods-1"><h3><span class="secno">3.2 </span>Methods</h3><dl class="methods"><dt id="widl-StreamReader-abort-void"><code>abort</code></dt><dd>This method should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#abort"><code>FileReader.abort()</code></a>. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]<div><em>No parameters.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-StreamReader-readAsArrayBuffer-void-Stream-stream-unsigned-long-long-maxSize"><code>readAsArrayBuffer</code></dt><dd>
- <p></p>
- <p>
- This method should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#readAsArrayBuffer"><code>FileReader.readAsArrayBuffer()</code></a>. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- The only addition is the addition of a <code>maxSize</code> parameter, which has the following adjustment:
- </p>
- <ul>
- <li>
- If <code>maxSize</code> is less than one, through an Invalid Argument exception. Terminate these overall steps.
- </li>
- <li>
- When the stream has been fully read,
- or the number of bytes specified by <code>maxSize</code> has been reached,
- set <a class="idlType" href="#widl-StreamReader-readyState"><code>readyState</code></a> to <code>DONE</code>.
- </li>
- </ul>
- <p></p>
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <dl class="exception" title="OperationNotAllowedException">
- <dt></dt>
- <dd></dd>
- </dl>
-
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completion</td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-StreamReader-readAsBlob-void-Stream-stream-unsigned-long-long-maxSize"><code>readAsBlob</code></dt><dd>
- <p></p>
- <p>
- When this method is called, the user agent <em title="must" class="rfc2119">must</em> run the steps below (unless otherwise indicated).
- </p>
- <ol>
- <li>
- If <code>maxSize</code> is less than one, through an Invalid Argument exception. Terminate these overall steps.
- </li>
- <li>
- If <code>readyState</code> is <code>LOADING</code>, raise a <code>NOT_ALLOWED_ERR</code> exception and terminate these steps.
- </li>
- <li>
- If an error occurs during reading the <code>stream</code> parameter,
- set <a class="idlType" href="#widl-StreamReader-readyState"><code>readyState</code></a> to <code>DONE</code> and set
- <a class="idlType" href="#widl-StreamReader-result"><code>result</code></a> to <code>null</code>.
- Proceed to the error steps below.
- <ol>
- <li>
- Dispatch a progress event called <code>error</code>.
- Set the <a class="idlType" href="#widl-StreamReader-error"><code>error</code></a> attribute;
- on getting, the <a class="idlType" href="#widl-StreamReader-error"><code>error</code></a>
- attribute <em title="must" class="rfc2119">must</em> be a <a href="#streamerror-error"><code>StreamError</code></a> object with a valid error code
- that indicates the kind of file error that has occurred.
- </li>
- <li>
- Dispatch a progress event called <code>loadend</code>.
- </li>
- <li>
- Terminate this overall set of steps.
- </li>
- </ol>
- </li>
- <li>
- If no error has occurred, set <a class="idlType" href="#widl-StreamReader-readyState"><code>readyState</code></a> to <code>LOADING</code>.
- </li>
- <li>
- Fire a progress event called <code>loadstart</code>.
- </li>
- <li>
- Make progress notifications.
- </li>
- <li>
- Continue reading on the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>:
- <ol>
- <li>
- If the optional <code>maxSize</code> parameter has been set,
- set the <a class="idlType" href="#widl-StreamReader-readyState"><code>readyState</code></a> to <code>DONE</code>
- when the number of bytes read reaches <code>MAX_SIZE</code>
- or the stream has been fully read and the number of bytes is less than <code>MAX_SIZE</code>.
- </li>
- <li>
- If the optional parameter has not been set,
- set <a class="idlType" href="#widl-StreamReader-readyState"><code>readyState</code></a>
- to <code>DONE</code> when the stream has been fully read.
- </li>
- </ol>
- </li>
- <li>
- Set the <a class="idlType" href="#widl-StreamReader-result"><code>result</code></a> attribute to be stream’s data content represented as a <code>Blob</code>;
- on getting, the result <a class="idlType" href="#widl-StreamReader-result"><code>result</code></a> returns the (complete) data of stream as a <code>Blob</code>.
- </li>
- <li>
- Terminate this overall set of steps.
- </li>
- </ol>
- <p></p>
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <dl class="exception" title="OperationNotAllowedException">
- <dt></dt>
- <dd></dd>
- </dl>
-
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completion</td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-StreamReader-readAsDataURL-void-Stream-Stream-unsigned-long-long-maxSize"><code>readAsDataURL</code></dt><dd>
- <p></p>
- <p>
- This method should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#readAsDataURL"><code>FileReader.readAsDataURL()</code></a>. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- The only addition is the addition of a <code>maxSize</code> parameter, which has the following adjustment.
- </p>
- <ul>
- <li>
- If <code>maxSize</code> is less than one, through an Invalid Argument exception. Terminate these overall steps.
- </li>
- <li>
- Queue a task to update the <a class="idlType" href="#widl-StreamReader-result"><code>result</code></a> attribute
- with the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> as a DataURL [<cite><a href="#bib-RFC2397" class="bibref">RFC2397</a></cite>] after the stream has been fully read,
- or the number of bytes specified by <code>maxSize</code> has been reached;
- on getting, the <a class="idlType" href="#widl-StreamReader-result"><code>result</code></a> attribute
- returns the (complete) data of stream as a DataURL [<cite><a href="#bib-RFC2397" class="bibref">RFC2397</a></cite>].
- </li>
- </ul>
-
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <dl class="exception" title="OperationNotAllowedException">
- <dt></dt>
- <dd></dd>
- </dl>
-
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">Stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completionk</td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-StreamReader-readAsText-void-Stream-stream-DOMString-encoding-optional-unsigned-long-long-maxSize"><code>readAsText</code></dt><dd>
- <p></p>
- <p>
- This method should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#readAsDataText"><code>FileReader.readAsText()</code></a>. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- The only addition is the addition of a <code>maxSize</code> parameter, which has the following adjustment:
- </p>
- <ol>
- <li>
- If <code>maxSize</code> is less than one, through an Invalid Argument exception. Terminate these overall steps.
- </li>
- <li>
- If no encoding is specified, use the <a href="http://dev.w3.org/2006/webapi/FileAPI/#encoding-determination">encoding determination</a> algorithm specified in the [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>].
- </li>
- <li>
- If no <code>maxSize</code> is specified, continue reading until the stream has been completed.
- </li>
- <li>
- When the stream has been fully read, or
- <strong>the number of bytes specified by <code>maxSize</code> has been reached</strong>,
- set <a class="idlType" href="#widl-StreamReader-readyState"><code>readyState</code></a> to <code>DONE</code>.
- </li>
- </ol>
- <p></p>
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <dl class="exception" title="OperationNotAllowedException">
- <dt></dt>
- <dd></dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">encoding</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The encoding format</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>optional unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completion</td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section><section id="constants"><h3><span class="secno">3.3 </span>Constants</h3><dl class="constants"><dt id="widl-StreamReader-DONE"><code>DONE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
- The current read request has been completed, or an error occurred during read,
- or the read was aborted using <a href="#widl-StreamReader-abort-void"><code>abort()</code></a>. The <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> is no longer reading a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </dd><dt id="widl-StreamReader-EMPTY"><code>EMPTY</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
- This state should mimic the
- <code>EMPTY</code> state of the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#blobreader-state">FileReader States</a>
- </dd><dt id="widl-StreamReader-LOADING"><code>LOADING</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
- This state should mimic the
- <code>LOADING</code> state of the
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#blobreader-state">FileReader States</a>
- </dd></dl></section>
- <pre class="idl"><span class="idlImplements"><a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> implements <a>EventTarget</a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a></code> type are defined to also implement the <a>EventTarget</a> interface.</p></div>
-
- <section class="section" id="streamreader-event-handler-types">
- <h3><span class="secno">3.4 </span>Event Handler Attributes</h3>
- <p>
- The following are the event handler attributes (and their corresponding event handler event types) that user agents <em title="must" class="rfc2119">must</em> support on StreamReader as DOM attributes:
- </p>
- <table class="error">
- <thead>
- <tr>
- <th><a href="#event-handler-attributes" title="event handler attributes">event handler attribute</a></th>
- <th><a href="#event-handler-event-type">event handler event type</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><dfn id="dfn-onloadstart"><code>onloadstart</code></dfn></td>
- <td><code><a href="#dfn-loadstart-event">loadstart</a></code></td>
- </tr>
- <tr>
- <td><dfn id="dfn-onprogress"><code>onprogress</code></dfn></td>
- <td><code><a href="#dfn-progress-event">progress</a></code></td>
- </tr>
- <tr>
- <td><dfn id="dfn-onload"><code>onload</code></dfn></td>
- <td><code><a href="#dfn-load-event">load</a></code></td>
- </tr>
- <tr>
- <td><dfn id="dfn-onabort"><code>onabort</code></dfn></td>
- <td><code title="abort-event"><a href="#dfn-abort-event">abort</a></code></td>
- </tr>
- <tr>
- <td><dfn id="dfn-onerror"><code>onerror</code></dfn></td>
- <td><code><a href="#dfn-error-event">error</a></code></td>
- </tr>
- <tr>
- <td><dfn id="dfn-onloadend"><code>onloadend</code></dfn></td>
- <td><code><a href="#dfn-loadend-event">loadend</a></code></td>
- </tr>
- </tbody>
- </table>
-
- <section class="section" id="streamreader-event-summary">
- <h4><span class="secno">3.4.1 </span>Event Summary</h4>
- <p>
- The following are the events that are fired at <code><a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a></code> objects;
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#fire-a-progress-event">firing events</a> is defined in DOM Level 3 Events [<cite><a href="#bib-DOM-LEVEL-3-EVENTS" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>],
- and the table below is normative for the events in this specification.
- </p>
- <table class="error" id="event-summary-table">
- <thead>
- <tr>
- <th>Event name</th>
- <th>Interface</th>
- <th>Fired when…</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><dfn id="dfn-loadstart-event"><code>loadstart</code></dfn></td>
- <td><code>ProgressEvent</code></td>
- <td>When the read starts.</td>
- </tr>
- <tr>
- <td><dfn id="dfn-progress-event"><code>progress</code></dfn></td>
- <td><code>ProgressEvent</code></td>
- <td>While reading (and decoding) a <code>stream</code>, and reporting progress.
- </td>
- </tr>
- <tr>
- <td><dfn id="dfn-abort-event" title="abort-event"><code>abort</code></dfn></td>
- <td><code>ProgressEvent</code></td>
- <td>When the read has been aborted. For instance, by invoking the <code><a href="#widl-StreamReader-abort-void">abort()</a></code> method.</td>
- </tr>
- <tr>
- <td><dfn id="dfn-error-event"><code>error</code></dfn></td>
- <td><code>ProgressEvent</code></td>
- <td>When the read has failed (see <a href="http://dev.w3.org/2006/webapi/FileAPI/#file-error-read">errors</a>).</td>
- </tr>
- <tr>
- <td><dfn id="dfn-load-event"><code>load</code></dfn></td>
- <td><code>ProgressEvent</code></td>
- <td>When the read has successfully completed.</td>
- </tr>
- <tr>
- <td><dfn id="dfn-loadend-event"><code>loadend</code></dfn></td>
- <td><code>ProgressEvent</code></td>
- <td>When the request has completed (either in success or failure).</td>
- </tr>
- </tbody>
- </table>
- </section>
-
- </section>
-
-</section>
-<!-- End section: The StreamReader Interface -->
-
-<section class="section" id="streamreadersync-interface">
-<!--OddPage--><h2><span class="secno">4. </span>The StreamReaderSync Interface</h2>
- <p>
- This interface provides methods to read the data of a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
- <p>
- When the <code>StreamReaderSync()</code> constructor is invoked, the user agent <em title="must" class="rfc2119">must</em> return a new <code>StreamReaderSync</code> object.
- </p>
- <p>
- In environments where the global object is represented by a <a href="http://dev.w3.org/html5/workers/#workerglobalscope"><code>WorkerGlobalScope</code></a> object,
- the <code>StreamReaderSync</code> constructor <em title="must" class="rfc2119">must</em> be available.
- </p>
- <pre class="idl"><span class="idlInterface" id="idl-def-StreamReaderSync">interface <span class="idlInterfaceID">StreamReaderSync</span> {
-<span class="idlMethod"> <span class="idlMethType"><a>Blob</a></span> <span class="idlMethName"><a href="#widl-StreamReaderSync-readAsBlob-Blob-Stream-stream-unsigned-long-long-maxSize">readAsBlob</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>ArrayBuffer</a></span> <span class="idlMethName"><a href="#widl-StreamReaderSync-readAsArrayBuffer-ArrayBuffer-Stream-stream-unsigned-long-long-maxSize">readAsArrayBuffer</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>DOMString</a></span> <span class="idlMethName"><a href="#widl-StreamReaderSync-readAsText-DOMString-Stream-stream-DOMString-encoding-optional-unsigned-long-long-maxSize">readAsText</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">encoding</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>optional unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>DOMString</a></span> <span class="idlMethName"><a href="#widl-StreamReaderSync-readAsDataURL-DOMString-Stream-stream-unsigned-long-long-maxSize">readAsDataURL</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlParamName">stream</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">maxSize</span></span>);</span>
-};</span></pre><section id="methods-2"><h3><span class="secno">4.1 </span>Methods</h3><dl class="methods"><dt id="widl-StreamReaderSync-readAsArrayBuffer-ArrayBuffer-Stream-stream-unsigned-long-long-maxSize"><code>readAsArrayBuffer</code></dt><dd>
- <p>
- This method should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#readAsArrayBufferSyncSection"><code>FileReader.readAsArrayBuffer()</code></a>. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- The only addition is the addition of a <code>maxSize</code> parameter that affects the amount of bytes to read from the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completion</td></tr></table><div><em>Return type: </em><code><a>ArrayBuffer</a></code></div></dd><dt id="widl-StreamReaderSync-readAsBlob-Blob-Stream-stream-unsigned-long-long-maxSize"><code>readAsBlob</code></dt><dd>
- <p></p>
- <p>
- When this method is called, the following steps <em title="must" class="rfc2119">must</em> be followed:
- </p>
- <ol>
- <li>
- If an error occurs during reading the <code>stream</code> parameter,
- throw a <code>StreamException</code> with the appropriate error code.
- Terminate these overall steps.
- </li>
- <li>
- If no error has occurred, read <code>stream</code> until the end is reached,
- or the number of bytes specified by <code>maxSize</code> have been read.
- Return the data contents of <code>stream</code> as a blob
- with the <code>type</code> property set as the type of the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </li>
- </ol>
- <p></p>
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completion</td></tr></table><div><em>Return type: </em><code><a>Blob</a></code></div></dd><dt id="widl-StreamReaderSync-readAsDataURL-DOMString-Stream-stream-unsigned-long-long-maxSize"><code>readAsDataURL</code></dt><dd>
- <p>
- This method should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#readAsDataURLSync-section"><code>FileReader.readAsDataURL()</code></a>. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- The only addition is the addition of a <code>maxSize</code> parameter that affects the amount of the amount of bytes to read from the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completion</td></tr></table><div><em>Return type: </em><code><a>DOMString</a></code></div></dd><dt id="widl-StreamReaderSync-readAsText-DOMString-Stream-stream-DOMString-encoding-optional-unsigned-long-long-maxSize"><code>readAsText</code></dt><dd>
- <p>
- This method should mimic <a href="http://dev.w3.org/2006/webapi/FileAPI/#readAsTextSync"><code>FileReader.readAsText()</code></a>. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- The only addition is the addition of a <code>maxSize</code> parameter that affects the amount of the amount of bytes to read from the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
-
- <dl class="exception" title="StreamException">
- <dt></dt>
- <dd></dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">stream</td><td class="prmType"><code><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The Stream to be read</td></tr><tr><td class="prmName">encoding</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The encoding format</td></tr><tr><td class="prmName">maxSize</td><td class="prmType"><code><a>optional unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The maximum number of bytes to be read before completion</td></tr></table><div><em>Return type: </em><code><a>DOMString</a></code></div></dd></dl></section>
-</section>
-
-<section class="section" id="reading-empty-stream">
-<!--OddPage--><h2><span class="secno">5. </span>Determining an empty Stream</h2>
- <p>
- StreamReader will read a Stream until maxSize has been reached or the
-Stream has no further data to return. If a Stream has been read until
-the end, then there is no further data to return. Subsequent read calls
-will return the following:
- </p><dl class="switch">
- <dt>If read is <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>readAsBlob</code></a></dt>
- <dd>Return an empty <code>Blob</code> with size zero</dd>
-
- <dt>If read is <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>readAsArrayBuffer</code></a></dt>
- <dd>Return an <code>ArrayBuffer</code> with length zero</dd>
-
- <dt>If read is <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>readAsText</code></a></dt>
- <dd>Return an empty string</dd>
-
- <dt>If read is <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>readAsDataURL</code></a></dt>
- <dd>Return an empty string</dd>
-
- </dl>
- <p></p>
-</section>
-
-<section class="section" id="errors-and-exceptions">
-<!--OddPage--><h2><span class="secno">6. </span>Errors and Exceptions</h2>
- <section class="section" id="streamerror-error">
- <h3><span class="secno">6.1 </span>StreamError</h3>
- <p>
- This interface should mimic the <a href="http://dev.w3.org/2006/webapi/FileAPI/#FileErrorInterface"><code>FileError</code> Interface</a>, and contain the same error codes.
- </p>
- </section>
-
- <section class="section" id="streamexception-error">
- <h3><span class="secno">6.2 </span>StreamException</h3>
- <p>
- This interface should mimic the <a href="http://dev.w3.org/2006/webapi/FileAPI/#FileException"><code>FileException</code> Interface</a>, , and contain the same error codes.
- </p>
- </section>
-</section>
-
-<section class="section" id="streambuilder-interface">
-<!--OddPage--><h2><span class="secno">7. </span>The StreamBuilder Interface</h2>
- <p>
- The <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> interface provides a way for developers to create a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> by appending data. During a read on the <code>stream</code> from a <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a>, the data is read 'First in, First out',
- in the order it was appended. <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> provides methods for appending different data, as well as a <a href="#dfn-thresholdreached-event"><code>thresholdreached</code></a> event to be notified when the amount of data available for read has fallen below a specified threshold.
- </p>
- <p>
- When the <code>StreamBuilder(in contentType)</code> constructor is invoked, the user agent <em title="must" class="rfc2119">must</em> return a new <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> object.
- If the <code>StreamBuilder(in contentType)</code> constructor is invoked with the optional <code>thresholdLimit</code> overload,
- then this limit will be used to fire the <a href="#dfn-thresholdreached-event"><code>thresholdreached</code></a> event.
- </p>
- <p>
- In environments where the global object is represented by a <a href="http://dev.w3.org/html5/workers/#workerglobalscope"><code>WorkerGlobalScope</code></a> object,
- the <code>StreamBuilder()</code> constructor <em title="must" class="rfc2119">must</em> be available.
- </p>
- <pre class="idl"><span class="idlInterface" id="idl-def-StreamBuilder">[<span class="extAttr">Constructor, Constructor(DOMString contentType, optional int thresholdLimit)</span>]
-interface <span class="idlInterfaceID">StreamBuilder</span> : <span class="idlSuperclass"><a>EventTarget</a></span> {
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamBuilder-append-void-String-data">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>String</a></span> <span class="idlParamName">data</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamBuilder-append-void-Blob-data">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>Blob</a></span> <span class="idlParamName">data</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamBuilder-append-void-ArrayBuffer-data">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>ArrayBuffer</a></span> <span class="idlParamName">data</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-StreamBuilder-close-void">close</a></span> ();</span>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span> <span class="idlAttrName"><a href="#widl-StreamBuilder-stream">stream</a></span>;</span>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-StreamBuilder-availableDataSize">availableDataSize</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-StreamBuilder-onthresholdreached">onthresholdreached</a></span>;</span>
-};</span></pre><section id="attributes-2"><h3><span class="secno">7.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-StreamBuilder-availableDataSize"><code>availableDataSize</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>The number of bytes of data available for read from the <a>stream</a></dd><dt id="widl-StreamBuilder-onthresholdreached"><code>onthresholdreached</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
- Handler for <a href="#dfn-thresholdreached-event"><code>thresholdreached</code></a> events.
- </dd><dt id="widl-StreamBuilder-stream"><code>stream</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></span>, readonly</dt><dd>Returns the underlying <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> represented by the <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a>.</dd></dl></section><section id="methods-3"><h3><span class="secno">7.2 </span>Methods</h3><dl class="methods"><dt id="widl-StreamBuilder-append-void-String-data"><code>append</code></dt><dd>
- <p></p>
- <p>
- Appends the supplied text to the data available for the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>, writing it as UTF-8.
- </p>
- <p></p>
-
- <dl class="exception" title="OperationNotAllowedException">
- <dt></dt>
- <dd>Thrown if append is called on a closed StreamBuilder</dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>String</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The data to append</td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-StreamBuilder-append-void-Blob-data"><code>append</code></dt><dd>
- <p></p>
- <p>
- Appends the supplied <code>Blob</code> to the data available for the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
- <p></p>
-
- <dl class="exception" title="OperationNotAllowedException">
- <dt></dt>
- <dd>Thrown if append is called on a closed StreamBuilder</dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>Blob</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The data to append</td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-StreamBuilder-append-void-ArrayBuffer-data"><code>append</code></dt><dd>
- <p></p>
- <p>
- Appends the supplied <code>ArrayBuffer</code> to the data available for the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
- <p></p>
-
- <dl class="exception" title="OperationNotAllowedException">
- <dt></dt>
- <dd>Thrown if append is called on a closed StreamBuilder</dd>
- </dl>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>ArrayBuffer</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The data to append</td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-StreamBuilder-close-void"><code>close</code></dt><dd>This method should close the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>. This is done by returning on the next and subsequent reads with no data.<div><em>No parameters.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
-
- <section class="section" id="reads-on-a-stream-from-streambuilder">
- <h3><span class="secno">7.3 </span>Reads on a Stream from StreamBuilder</h3>
- <p>
- When a read on a stream from <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> is made, the following steps <em title="must" class="rfc2119">must</em> be followed:
- </p>
- <ol>
- <li>
- If there is enough data available to satisfy the amount requested
-in the read, return the amount specified. The data should be returned in
- the order the data was appended.
- <ul>
- <li>
- Update the value of <a href="#widl-StreamBuilder-availableDataSize"><code>availableDataSize</code></a>.
- </li>
- </ul>
- </li>
- <li>
- If there is not enough data available to satisfy the amount requested in the read:
- <ul>
- <li>
- If the <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> has been closed, return all the data available,
- and set <a href="#widl-StreamBuilder-availableDataSize"><code>availableDataSize</code></a> to zero.</li>
- <li>
- Else, keep the request pending and do not return until there is enough data available to satisfy the requset.
-
- </li>
- </ul>
- </li>
- <li>
- If during the read request the value of <a href="#widl-StreamBuilder-availableDataSize"><code>availableDataSize</code></a>
- fell below the <code>thresholdLimit</code> value specified in the constructor,
- fire an event called <a href="#dfn-thresholdreached-event"><code>thresholdreached</code></a>.
- </li>
- </ol>
- </section>
-
- <section class="section" id="streambuilder-event-handler-types">
- <h3><span class="secno">7.4 </span>Event Handler Attributes</h3>
- <p>
- The following are the event handler attributes (and their corresponding event handler event types) that user agents <em title="must" class="rfc2119">must</em> support on <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> as DOM attributes:
- </p>
- <table class="error">
- <thead>
- <tr>
- <th><a href="#event-handler-attributes" title="event handler attributes">event handler attribute</a></th>
- <th><a href="#event-handler-event-type">event handler event type</a></th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><dfn id="dfn-onthresholdreached"><code>onthresholdreached</code></dfn></td>
- <td><code><a href="#dfn-thresholdreached-event">thresholdreached</a></code></td>
- </tr>
- </tbody>
- </table>
-
- <section class="section" id="streambuilder-event-summary">
- <h4><span class="secno">7.4.1 </span>Event Summary</h4>
- <p>
- The following are the events that are fired at <code><a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a></code> objects;
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#fire-a-progress-event">firing events</a> is defined in DOM Level 3 Events [<cite><a href="#bib-DOM-LEVEL-3-EVENTS" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>],
- and the table below is normative for the events in this specification.
- </p>
- <table class="error" id="event-summary-table">
- <thead>
- <tr>
- <th>Event name</th>
- <th>Interface</th>
- <th>Fired when…</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><dfn id="dfn-thresholdreached-event"><code>thresholdreached</code></dfn></td>
- <td><code>StreamBuilder</code></td>
- <td>The <a href="#widl-StreamBuilder-availableDataSize"><code>availableDataSize</code></a> has fallen below the <code>thresholdLimit</code> value specified in the constructor</td>
- </tr>
- </tbody>
- </table>
- </section>
-
- </section>
-
-
-</section>
-<!-- End section: The StreamBuilder Interface -->
-
-
-<section class="section" id="error-uris_for_streams">
-<!--OddPage--><h2><span class="secno">8. </span>URIs for Stream</h2>
- <p>
- To reference a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>, <a href="http://dev.w3.org/2006/webapi/FileAPI/#url">the same URI used</a> for <code>Blobs</code> and <code>Files</code> in
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#url">6.7. A URI for Blob and File reference</a> of
- the File API spec should be used. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- The definitions of <strong>Origin</strong>, <strong>Lifetime</strong>, <strong>Referencing</strong>, and <strong>Dereferencing</strong> of a <code>Blob</code> should be applied to a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
- <section class="section" id="creating-revoking-streamuri">
- <h3><span class="secno">8.1 </span>Creating and Revoking a Stream URI</h3>
- <p>
- A <dfn id="stream-uri">Stream URI</dfn> is a <code>Blob URI</code> that is referencing a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- These URIs are created and revoked using methods exposed on the URL object,
- as defined in <a href="http://dev.w3.org/2006/webapi/FileAPI/#creating-revoking">6.7.5. Creating and Revoking a Blob URI</a>
- of the File API spec. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- </p>
- <p>
- <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-createObjectURL">URL.createObjectURL</a>
- and <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-revokeObjectURL">URL.revokeObjectURL</a>
- should both be extended as follows:
- </p>
- <pre class="idl"><span class="idlInterface" id="idl-def-URL">interface <span class="idlInterfaceID">URL</span> {
-<span class="idlMethod"> static <span class="idlMethType"><a>DOMString</a></span> <span class="idlMethName"><a href="#widl-URL-createObjectURL-DOMString-any-object">createObjectURL</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">object</span></span>);</span>
-<span class="idlMethod"> static <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-URL-revokeObjectURL-void-DOMString-url">revokeObjectURL</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">url</span></span>);</span>
-};</span></pre><section id="methods-4"><h4><span class="secno">8.1.1 </span>Methods</h4><dl class="methods"><dt id="widl-URL-createObjectURL-DOMString-any-object"><code>createObjectURL</code>, static</dt><dd>
- <p></p>
- <p>The extension onto <code>createObjectURL</code> should have the following steps added.</p>
- <ol>
- <li>
- If this method is called with a <code>Blob</code> or <code>Stream</code> argument
- that is <strong>not</strong> valid, then the user agent <em title="must" class="rfc2119">must</em> return null.</li>
- <li>
- If this method is called with a valid <code>Blob</code> or <code>Stream</code> argument,
- user agents <em title="must" class="rfc2119">must</em> return a unique <code>Blob URI</code> that can be used to dereference the <code>blob</code> or <code>stream</code> argument.
- </li>
- </ol>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">object</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>DOMString</a></code></div></dd><dt id="widl-URL-revokeObjectURL-void-DOMString-url"><code>revokeObjectURL</code>, static</dt><dd>
- <p></p>
- <p>
- The extension onto <code>revokeObjectURL</code> should have the following steps added.
- </p>
- <ol>
- <li>
- If the URL refers to a <code>Blob</code> or <code>Stream</code> that is both
- valid and in the same origin of the global object’s <code>URL</code> property on which this static method was called,
- user agents <em title="must" class="rfc2119">must</em> return a 404 response code when the URL is dereferenced.</li>
- <li>
- If the URL refers to a <code>Blob</code> or <code>Stream</code> that is <strong>not</strong> valid
- or if the value provided for the URL argument is not a <code>Blob URI</code>
- or if the URL argument refers to a <code>Blob</code> or <code>Stream</code> that is <strong>not</strong> in the same origin
- as the global object’s <code>URL</code> property, this method call does nothing.
- User agents <em title="may" class="rfc2119">may</em> display a message on their error console.
- </li>
- </ol>
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">url</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
- </section>
-</section>
-
-<section class="section" id="security">
-<!--OddPage--><h2><span class="secno">9. </span>Security Considerations</h2>
- <p>
- A <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> should have the same security considerations as a <code>Blob</code>.
- This is outlined in <a href="http://dev.w3.org/2006/webapi/FileAPI/#security-discussion">6.8. Security Considerations</a>
- of the File API specification. [<cite><a href="#bib-FILE-API" class="bibref">FILE-API</a></cite>]
- Because a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> uses a <code>Blob URI</code>, cross origin requests on a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> will not be supported.
- </p>
-</section>
-
-<section class="section" id="XMLHttpRequest">
-<!--OddPage--><h2><span class="secno">10. </span>Extension of XMLHttpRequest</h2>
- <p>
- This specification proposes an extension to <code>XMLHttpRequest</code> [<cite><a href="#bib-XMLHTTPREQUEST2" class="bibref">XMLHTTPREQUEST2</a></cite>] to add support for <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>. This section is temporary and is meant to provide a recommendation for how <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> should be incorporated into <code>XMLHttpRequest</code>.
- This will extend <code>XMLHttpRequest</code> to allow for receiving and uploading of a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- One such scenario is providing access to data during <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-readystate"><code>readyState</code></a> 3 (loading).
- The sections below document in detail what extensions must be done to <code>XMLHttpRequest</code> to support <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a>.
- </p>
-
- <section id="addition-of-stream-responsetype" class="section" title="addition-of-stream">
- <h3><span class="secno">10.1 </span>Addition of stream responseType</h3>
- <p>
- A responseType of ‘<code>stream</code>’ should be introduced to <code>XMLHttpRequest</code>.
- </p>
- <p>
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-responsetype-attribute">Section 4.7.7 the <code>responseType</code> attribute</a>
- in XMLHttpRequest Level 2 [<cite><a href="#bib-XMLHTTPREQUEST2" class="bibref">XMLHTTPREQUEST2</a></cite>] should now read:
- </p>
- <p>
- On setting the <code>responseType</code> attribute these steps must be run:
- </p>
- <ol>
- <li>
- If the state is not <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-opened"><code>OPENED</code></a> or
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-headers_received"><code>HEADERS_RECEIVED</code></a>
- raise an <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-domexception-invalid_state_err"><code>INVALID_STATE_ERR</code></a>
- exception and terminate these steps.
- </li>
- <li>
- If the given value is not the empty string, "<code>arraybuffer</code>", "<code>blob</code>",
- "<code>document</code>", "<code>stream</code>", or "<code>text</code>" terminate these steps.</li>
- <li>Set the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>responseType</code></a> attribute's value to the given value.</li>
- </ol>
- <p></p>
-
- <p>
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-response-attribute">Section 4.7.8 the <code>response</code> attribute</a>
- in XMLHttpRequest Level 2 [<cite><a href="#bib-XMLHTTPREQUEST2" class="bibref">XMLHTTPREQUEST2</a></cite>] should now read:
- </p>
- <p>
- The <code>response</code> attribute must return the result of running these steps:
- </p>
- <dl class="switch">
- <dt>If <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>responseType</code></a> is the empty string or "text"</dt>
- <dd>
- <ol>
- <li>
- If the state is not
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-loading">LOADING</a>
- or <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-done">DONE</a>
- return the empty string and terminate these steps.
- </li>
- <li>
- If the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#error-flag">error flag</a>
- is true return the empty string and terminate these steps.
- </li>
- <li>
- Return the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#text-response-entity-body">text response entity body</a>.
- </li>
- </ol>
- </dd>
- <dt>If <code>responseType</code> is “<code>stream</code>”</dt>
- <dd>
- <ol>
- <li>
- If the state is not
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-loading">LOADING</a>
- or <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-done">DONE</a>
- return null and terminate these steps.</li>
- <li>
- If the error flag is true return null and terminate these steps.
- </li>
- <li>
- Return the <a href="#stream-response-entity">stream response entity body</a>.
- </li>
- </ol>
- </dd>
- <dt>Otherwise</dt>
- <dd>
- <ol>
- <li>
- If the state is not <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-done">DONE</a> return null and terminate these steps.
- </li>
- <li>
- If the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#error-flag">error flag</a> is true return null and terminate these steps.
- </li>
- <li>
- <dl class="switch">
- <dt>If <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>responseType</code></a> is "<code>arraybuffer</code>"</dt>
- <dd>Return the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#arraybuffer-response-entity-body">arraybuffer response entity body</a>.</dd>
-
- <dt>If <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>responseType</code></a> is "<code>blob</code>"</dt>
- <dd>Return the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#blob-response-entity-body">blob response entity body</a>.</dd>
-
- <dt>If <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-responsetype"><code>responseType</code></a> is "<code>document</code>"</dt>
- <dd>Return the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#document-response-entity-body">document response entity body</a>.</dd>
-
- </dl>
- </li>
- </ol>
- </dd>
- </dl>
-
- </section>
-
- <section class="section" id="readystate3-changes">
- <h3><span class="secno">10.2 </span>readyState 3 changes</h3>
- <p>
- A <code>stream</code> is binary data obtained sequentially over time.
- Given this, a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> should be accessible in <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#dom-xmlhttprequest-readystate"><code>readyState</code></a> 3 (LOADING).
- </p>
- <p>
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#response-entity-body0">Section 4.7.5 Response Entity Body</a>
- in XMLHttpRequest Level 2 [<cite><a href="#bib-XMLHTTPREQUEST2" class="bibref">XMLHTTPREQUEST2</a></cite>] should have the following additions:
- </p>
- <p>
- The <dfn id="stream-response-entity">stream response entity body</dfn> is a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> representing the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#response-entity-body">response entity body</a>.
- If the <a href="#stream-response-entity">stream response entity body</a> has no value assigned to it let it be the return value of the following algorithm:
- </p>
- <ol>
- <li>
- If the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#response-entity-body">response entity body</a> is null,
- return an empty <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> object and terminate these steps.
- </li>
- <li>
- Return a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> object representing the
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#response-entity-body">response entity body</a>.
- </li>
- </ol>
- </section>
-
- <section clas="section" id="send0">
- <h3><span class="secno">10.3 </span>send()</h3>
- <p>
- <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-send-method">Section 4.6.6 The <code>send()</code> method</a>
- in XMLHttpRequest Level 2 [<cite><a href="#bib-XMLHTTPREQUEST2" class="bibref">XMLHTTPREQUEST2</a></cite>] should have the following additions:
- </p>
- <dl class="switch">
- <dt>If data is a <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a></dt>
- <dd>
- <p>
- If the object's <code>type</code> attribute is not the empty string let <var>mime type</var> be its value.
- </p>
- <p>
- Let the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#request-entity-body">request entity body</a> be the raw data represented by <var>data</var>.
- </p>
-
- </dd>
- </dl>
- </section>
-
-</section>
-
-<section class="section" id="requirements">
-<!--OddPage--><h2><span class="secno">11. </span>Requirements and Use Cases</h2>
- <p>
- The <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> type allows for completion of several end-to-end experiences. This section covers what the requirements are for this API, and
- illustrates some use cases.
- </p>
- <ul>
- <li>
- Begin loading a video through <code>XMLHttpRequest</code> in <code>readyState</code> 3
- <p>
- Videos can typically be large files that may take a long time to
-download, and require authentication or certain headers to access.
- For certain video formats, an application can begin playing the
-video once the first chunks of data are available, and would not need to
- wait for the entire video to download.
-
- </p>
- </li>
- <li>
- Begin processing data with <a class="idlType" href="#idl-def-StreamReader"><code>StreamReader</code></a> as it is being read via <code>XMLHttpRequest</code>
- <p>
- If a file format is understood, then an application can make sense
-of the data as it being made available. For example, a given
- file may be very large and the application wants to begin
-processing the data immediately, rather than having to wait for full
-download of the file.
- </p>
- </li>
- <li>
- Upload of dynamic runtime data using <a class="idlType" href="#idl-def-StreamBuilder"><code>StreamBuilder</code></a> and <code>XMLHttpRequest</code>
- <p>
- There are situations where an application may have data to upload
-once the application is processing. This could involve processing
- of data an application wants to upload as it is being created. One
-such case is the upload of GPS coordinates within an application. The
- coordiantes may constantly change, and the application wants to
-upload the data as it being collected.
-
- </p>
- </li>
- <li>
- Media streaming scenarios using <a class="idlType" href="#idl-def-Stream"><code>Stream</code></a> and <code>XMLHttpRequest</code>
- <p>
- Media streaming scenarios require the ability to quickly receive
-data over the network and connect it to a media element. An application
-can successfully accomplish this by receiving a Stream in <code>readyState</code>
- 3 and assign it to a media element. This helps avoid the application
-from having to buffer the data prior to assigning it to a media element.
- </p>
- </li>
- </ul>
-</section>
-
-<section id="acknowledgements" class="appendix">
-<!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
-<p>
- Thanks to Eliot Graff for editorial assistance.
- Special thanks to the <abbr title="World Wide Web Consortium">W3C</abbr>.
-</p>
-</section>
-
-
-
-
-<section class="appendix" id="references"><!--OddPage--><h2><span class="secno">B. </span>References</h2><section id="normative-references"><h3><span class="secno">B.1 </span>Normative references</h3><dl class="bibliography"><dt id="bib-DOM-LEVEL-3-EVENTS">[DOM-LEVEL-3-EVENTS]</dt><dd>Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. <a href="http://www.w3.org/TR/2011/WD-DOM-Level-3-Events-20110531/"><cite>Document Object Model (DOM) Level 3 Events Specification.</cite></a> 31 May 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-DOM-Level-3-Events-20110531/">http://www.w3.org/TR/2011/WD-DOM-Level-3-Events-20110531/</a>
-</dd><dt id="bib-FILE-API">[FILE-API]</dt><dd>Arun Ranganathan; Jonas Sicking. <a href="http://www.w3.org/TR/2011/WD-FileAPI-20111020/"><cite>File API.</cite></a> 20 October 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-FileAPI-20111020/">http://www.w3.org/TR/2011/WD-FileAPI-20111020/</a>
-</dd><dt id="bib-HTML5">[HTML5]</dt><dd>Ian Hickson; David Hyatt. <a href="http://www.w3.org/TR/html5"><cite>HTML5.</cite></a> 29 March 2012. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/html5">http://www.w3.org/TR/html5</a>
-</dd><dt id="bib-HTTP11">[HTTP11]</dt><dd>R. Fielding; et al. <a href="http://www.ietf.org/rfc/rfc2616.txt"><cite>Hypertext Transfer Protocol - HTTP/1.1.</cite></a> June 1999. Internet RFC 2616. URL: <a href="http://www.ietf.org/rfc/rfc2616.txt">http://www.ietf.org/rfc/rfc2616.txt</a>
-</dd><dt id="bib-RFC2046">[RFC2046]</dt><dd>N. Freed; N. Borenstein. <a href="http://www.ietf.org/rfc/rfc2046.txt"><cite>Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.</cite></a> November 1996. Internet RFC 2046. URL: <a href="http://www.ietf.org/rfc/rfc2046.txt">http://www.ietf.org/rfc/rfc2046.txt</a>
-</dd><dt id="bib-RFC2397">[RFC2397]</dt><dd>L. Masinter. <a href="http://www.ietf.org/rfc/rfc2397.txt"><cite>The "data" URL scheme.</cite></a> August 1998. Internet RFC 2397. URL: <a href="http://www.ietf.org/rfc/rfc2397.txt">http://www.ietf.org/rfc/rfc2397.txt</a>
-</dd><dt id="bib-WEBWORKERS">[WEBWORKERS]</dt><dd>Ian Hickson. <a href="http://www.w3.org/TR/2011/WD-workers-20110901/"><cite>Web Workers.</cite></a> 1 September 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-workers-20110901/">http://www.w3.org/TR/2011/WD-workers-20110901/</a>
-</dd><dt id="bib-XMLHTTPREQUEST2">[XMLHTTPREQUEST2]</dt><dd>Anne van Kesteren. <a href="http://www.w3.org/TR/2008/WD-XMLHttpRequest2-20080930"><cite>XMLHttpRequest Level 2.</cite></a> 30 September 2008. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2008/WD-XMLHttpRequest2-20080930">http://www.w3.org/TR/2008/WD-XMLHttpRequest2-20080930</a>
-</dd></dl></section></section></body></html>
\ No newline at end of file