Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 4b56e0f353
Fetching contributors…

Cannot retrieve contributors at this time

3080 lines (2391 sloc) 161.836 kb
<!DOCTYPE html><html lang="en-US"><meta charset="utf-8">
<title>XMLHttpRequest Standard</title>
<link href="http://www.whatwg.org/style/specification" rel="stylesheet">
<link href="http://www.whatwg.org/images/icon" rel="icon">
<div class="head">
<h1 class="head" id="xmlhttprequest-ls">XMLHttpRequest</h1>
<h2 class="no-num no-toc" id="living-standard-—-last-updated-11-october-2012">Living Standard — Last Updated 11 October 2012</h2>
<dl>
<dt>This Version:</dt>
<dd><a href="http://xhr.spec.whatwg.org/">http://xhr.spec.whatwg.org/</a></dd>
<dt>Participate:</dt>
<dd>Send feedback to
<a href="mailto:public-webapps@w3.org?subject==%5Bxhr%5D%20">public-webapps@w3.org</a>
(<a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>) or
<a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=WebAppsWG&amp;component=XHR">file a bug</a>
(<a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=WebAppsWG&amp;component=XHR&amp;resolution=---">open bugs</a>)
<dd><a href="http://wiki.whatwg.org/wiki/IRC">IRC: #whatwg on Freenode</a>
<dt>Version History:
<dd><a href="https://github.com/whatwg/xhr/commits">https://github.com/whatwg/xhr/commits</a>
<dt>Editor:</dt>
<dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a>
&lt;<a href="mailto:annevk@annevk.nl">annevk@annevk.nl</a>&gt;</dd>
</dl>
<script async="" src="//dvcs.w3.org/hg/quirks-mode/raw-file/tip/file-bug.js"></script>
<p class="copyright"><a href="http://creativecommons.org/publicdomain/zero/1.0/" rel="license"><img alt="CC0" src="http://i.creativecommons.org/p/zero/1.0/80x15.png"></a>
To the extent possible under law, the editor has waived all copyright and
related or neighboring rights to this work. In addition, as of
11 October 2012, the editor has made this specification available
under the
<a href="http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0" rel="license">Open Web Foundation Agreement Version 1.0</a>,
which is available at
http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.
</div>
<h2 class="no-num no-toc" id="specabstract">Abstract</h2>
<p>The XMLHttpRequest specification defines an API that provides scripted
client functionality for transferring data between a client and a server.
<h2 class="no-num no-toc" id="toc">Table of Contents</h2>
<!--begin-toc-->
<ol class="toc">
<li><a href="#introduction"><span class="secno">1 </span>Introduction</a>
<ol class="toc">
<li><a href="#specification-history"><span class="secno">1.1 </span>Specification history</a></ol></li>
<li><a href="#conformance"><span class="secno">2 </span>Conformance</a>
<ol class="toc">
<li><a href="#extensibility"><span class="secno">2.1 </span>Extensibility</a></ol></li>
<li><a href="#terminology"><span class="secno">3 </span>Terminology</a></li>
<li><a href="#interface-xmlhttprequest"><span class="secno">4 </span>Interface <code title="">XMLHttpRequest</code></a>
<ol class="toc">
<li><a href="#base-url,-origin,-and-referrer"><span class="secno">4.1 </span>Base URL, origin, and referrer</a></li>
<li><a href="#task-sources"><span class="secno">4.2 </span>Task sources</a></li>
<li><a href="#constructors"><span class="secno">4.3 </span>Constructors</a></li>
<li><a href="#garbage-collection"><span class="secno">4.4 </span>Garbage collection</a></li>
<li><a href="#event-handlers"><span class="secno">4.5 </span>Event handlers</a></li>
<li><a href="#states"><span class="secno">4.6 </span>States</a></li>
<li><a href="#request"><span class="secno">4.7 </span>Request</a>
<ol class="toc">
<li><a href="#the-open()-method"><span class="secno">4.7.1 </span>The <code title="">open()</code> method</a></li>
<li><a href="#the-setrequestheader()-method"><span class="secno">4.7.2 </span>The <code title="">setRequestHeader()</code> method</a></li>
<li><a href="#the-timeout-attribute"><span class="secno">4.7.3 </span>The <code title="">timeout</code> attribute</a></li>
<li><a href="#the-withcredentials-attribute"><span class="secno">4.7.4 </span>The <code title="">withCredentials</code> attribute</a></li>
<li><a href="#the-upload-attribute"><span class="secno">4.7.5 </span>The <code title="">upload</code> attribute</a></li>
<li><a href="#the-send()-method"><span class="secno">4.7.6 </span>The <code title="">send()</code> method</a></li>
<li><a href="#infrastructure-for-the-send()-method"><span class="secno">4.7.7 </span>Infrastructure for the <code title="">send()</code> method</a></li>
<li><a href="#the-abort()-method"><span class="secno">4.7.8 </span>The <code title="">abort()</code> method</a></ol></li>
<li><a href="#response"><span class="secno">4.8 </span>Response</a>
<ol class="toc">
<li><a href="#the-status-attribute"><span class="secno">4.8.1 </span>The <code title="">status</code> attribute</a></li>
<li><a href="#the-statustext-attribute"><span class="secno">4.8.2 </span>The <code title="">statusText</code> attribute</a></li>
<li><a href="#the-getresponseheader()-method"><span class="secno">4.8.3 </span>The <code title="">getResponseHeader()</code> method</a></li>
<li><a href="#the-getallresponseheaders()-method"><span class="secno">4.8.4 </span>The <code title="">getAllResponseHeaders()</code> method</a></li>
<li><a href="#response-entity-body-0"><span class="secno">4.8.5 </span>Response entity body</a></li>
<li><a href="#the-overridemimetype()-method"><span class="secno">4.8.6 </span>The <code title="">overrideMimeType()</code> method</a></li>
<li><a href="#the-responsetype-attribute"><span class="secno">4.8.7 </span>The <code title="">responseType</code> attribute</a></li>
<li><a href="#the-response-attribute"><span class="secno">4.8.8 </span>The <code title="">response</code> attribute</a></li>
<li><a href="#the-responsetext-attribute"><span class="secno">4.8.9 </span>The <code title="">responseText</code> attribute</a></li>
<li><a href="#the-responsexml-attribute"><span class="secno">4.8.10 </span>The <code title="">responseXML</code> attribute</a></ol></li>
<li><a href="#events"><span class="secno">4.9 </span>Events summary</a></ol></li>
<li><a href="#interface-formdata"><span class="secno">5 </span>Interface <code title="">FormData</code></a>
<ol class="toc">
<li><a href="#formdata-constructors"><span class="secno">5.1 </span>Constructors</a></li>
<li><a href="#the-append()-method"><span class="secno">5.2 </span>The <code title="">append()</code> method</a></ol></li>
<li><a href="#interface-progressevent"><span class="secno">6 </span>Interface <code title="">ProgressEvent</code></a>
<ol class="toc">
<li><a href="#firing-events-using-the-progressevent-interface-for-http"><span class="secno">6.1 </span>Firing events using the <code title="">ProgressEvent</code> interface for HTTP</a></li>
<li><a href="#firing-events-using-the-progressevent-interface-for-other-contexts"><span class="secno">6.2 </span>Firing events using the <code title="">ProgressEvent</code> interface for other contexts</a></li>
<li><a href="#suggested-names-for-events-using-the-progressevent-interface"><span class="secno">6.3 </span>Suggested names for events using the <code title="">ProgressEvent</code> interface</a></li>
<li><a href="#security-considerations"><span class="secno">6.4 </span>Security Considerations</a></li>
<li><a href="#example"><span class="secno">6.5 </span>Example</a></ol></li>
<li><a href="#data:-urls-and-http"><span class="secno">7 </span><code>data:</code> URLs and HTTP</a></li>
<li><a class="no-num" href="#references">References</a></li>
<li><a class="no-num" href="#acknowledgments">Acknowledgments</a></ol>
<!--end-toc-->
<h2 id="introduction"><span class="secno">1 </span>Introduction</h2>
<p><em>This section is non-normative.</em></p>
<p>The <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object is the ECMAScript HTTP API.
<a class="informative" href="#refsECMASCRIPT">[ECMASCRIPT]</a>
<!-- XXX elaborate on options -->
<p>The name of the object is <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> for compatibility
with the Web, though each component of this name is potentially
misleading. First, the object supports any text based format, including
XML. Second, it can be used to make requests over both HTTP and HTTPS
(some implementations support protocols in addition to HTTP and HTTPS, but
that functionality is not covered by this specification). Finally, it
supports "requests" in a broad sense of the term as it pertains to HTTP;
namely all activity involved with HTTP requests or responses for the
defined HTTP methods.</p>
<!-- XXX need to improve point 2 -->
<div class="example">
<p>Some simple code to do something with data from an XML document
fetched over the network:</p>
<pre><code>function processData(data) {
// taking care of data
}
function handler() {
if(this.readyState == this.DONE) {
if(this.status == 200 &amp;&amp;
this.responseXML != null &amp;&amp;
this.responseXML.getElementById('test').textContent) {
// success!
processData(this.responseXML.getElementById('test').textContent);
return;
}
// something went wrong
processData(null);
}
}
var client = new XMLHttpRequest();
client.onreadystatechange = handler;
client.open("GET", "unicorn.xml");
client.send();</code></pre>
<p>If you just want to log a message to the server:</p>
<pre><code>function log(message) {
var client = new XMLHttpRequest();
client.open("POST", "/log");
client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
client.send(message);
}</code></pre>
<p>Or if you want to check the status of a document on the server:</p>
<pre><code>function fetchStatus(address) {
var client = new XMLHttpRequest();
client.onreadystatechange = function() {
// in case of network errors this might not give reliable results
if(this.readyState == this.DONE)
returnStatus(this.status);
}
client.open("HEAD", address);
client.send();
}</code></pre>
</div>
<h3 id="specification-history"><span class="secno">1.1 </span>Specification history</h3>
<p>The <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object was initially defined as part of
the WHATWG's HTML effort. (Long after Microsoft shipped an implementation.)
It moved to the W3C in 2006. Extensions (e.g. progress events and
cross-origin requests) to <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> were developed in a
separate draft (XMLHttpRequest Level 2) until end of 2011, at which point
the two drafts were merged and <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> became a single
entity again from a standards perspective. End of 2012 it moved back to the
WHATWG.
<p>Historical discussion can be found in the following mailing list
archives:
<ul>
<li><a href="http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/">whatwg@whatwg.org</a>
<li><a href="http://lists.w3.org/Archives/Public/public-webapi/">public-webapi@w3.org</a>
<li><a href="http://lists.w3.org/Archives/Public/public-appformats/">public-appformats@w3.org</a>
<li><a href="http://lists.w3.org/Archives/Public/public-webapps/">public-webapps@w3.org</a>
</ul>
<h2 id="conformance"><span class="secno">2 </span>Conformance</h2>
<p>All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.
<p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
NOT",--> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in the normative parts of this specification are to be
interpreted as described in RFC2119. For readability, these words do
not appear in all uppercase letters in this specification.
<a href="#refsRFC2119">[RFC2119]</a>
<h3 id="extensibility"><span class="secno">2.1 </span>Extensibility</h3>
<p>User agents, Working Groups, and other interested parties are
<em>strongly encouraged</em> to discuss new features with the WHATWG
community.
<h2 id="terminology"><span class="secno">3 </span>Terminology</h2>
<p>This specification heavily borrows terminology, from
Cross-Origin Resource Sharing, DOM, DOM Parsing and Serialization, Encoding,
File API, HTML, HTTP, Streams API, Typed Array, Web IDL, and XML.
<a href="#refsCORS">[CORS]</a>
<a href="#refsDOM">[DOM]</a>
<a href="#refsDOMPS">[DOMPS]</a>
<a href="#refsENCODING">[ENCODING]</a>
<a href="#refsFILEAPI">[FILEAPI]</a>
<a href="#refsHTML">[HTML]</a>
<a href="#refsHTTP">[HTTP]</a>
<a href="#refsSTREAMS">[STREAMS]</a>
<a href="#refsTYPEDARRAY">[TYPEDARRAY]</a>
<a href="#refsWEBIDL">[WEBIDL]</a>
<a href="#refsXML">[XML]</a> <a href="#refsXMLNS">[XMLNS]</a>
<p>The term <dfn id="user-credentials">user credentials</dfn> for the purposes of this
specification means cookies, HTTP authentication, and client-side SSL
certificates. Specifically it does not refer to proxy authentication or the
<code title="http-origin">Origin</code> header.
<a href="#refsCOOKIES">[COOKIES]</a> <!-- XXX ref? -->
<h2 id="interface-xmlhttprequest"><span class="secno">4 </span>Interface <code title="">XMLHttpRequest</code></h2>
<pre class="idl">[NoInterfaceObject]
interface <dfn id="xmlhttprequesteventtarget">XMLHttpRequestEventTarget</dfn> : <a class="external" href="http://dom.spec.whatwg.org/#eventtarget">EventTarget</a> {
// <a href="#event-handlers">event handlers</a>
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onloadstart" title="handler-xhr-onloadstart">onloadstart</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onprogress" title="handler-xhr-onprogress">onprogress</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onabort" title="handler-xhr-onabort">onabort</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onerror" title="handler-xhr-onerror">onerror</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onload" title="handler-xhr-onload">onload</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-ontimeout" title="handler-xhr-ontimeout">ontimeout</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onloadend" title="handler-xhr-onloadend">onloadend</a>;
};
interface <dfn id="xmlhttprequestupload">XMLHttpRequestUpload</dfn> : <a href="#xmlhttprequesteventtarget">XMLHttpRequestEventTarget</a> {
};
enum <dfn id="xmlhttprequestresponsetype">XMLHttpRequestResponseType</dfn> {
"",
"arraybuffer",
"blob",
"document",
"json",
"stream",
"text"
};
dictionary <dfn id="xmlhttprequestoptions">XMLHttpRequestOptions</dfn> {
boolean anon = false;
};
[<a href="#dom-xmlhttprequest" title="dom-XMLHttpRequest">Constructor</a>(optional <a href="#xmlhttprequestoptions">XMLHttpRequestOptions</a> <var title="">options</var>)]
interface <dfn id="xmlhttprequest">XMLHttpRequest</dfn> : <a href="#xmlhttprequesteventtarget">XMLHttpRequestEventTarget</a> {
// <a href="#event-handlers">event handler</a>
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onreadystatechange" title="handler-xhr-onreadystatechange">onreadystatechange</a>;
// <a href="#states">states</a>
const unsigned short <a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> = 0;
const unsigned short <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> = 1;
const unsigned short <a href="#dom-xmlhttprequest-headers_received" title="dom-XMLHttpRequest-HEADERS_RECEIVED">HEADERS_RECEIVED</a> = 2;
const unsigned short <a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> = 3;
const unsigned short <a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a> = 4;
readonly attribute unsigned short <a href="#dom-xmlhttprequest-readystate" title="dom-XMLHttpRequest-readyState">readyState</a>;
// <a href="#request">request</a>
void <a href="#dom-xmlhttprequest-open" title="dom-XMLHttpRequest-open">open</a>(ByteString <var>method</var>, DOMString <var title="">url</var>, optional boolean <var>async</var> = true, optional DOMString? <var>user</var> = null, optional DOMString? <var>password</var> = null);
void <a href="#dom-xmlhttprequest-setrequestheader" title="dom-XMLHttpRequest-setRequestHeader">setRequestHeader</a>(ByteString <var>header</var>, ByteString <var>value</var>);
attribute unsigned long <a href="#dom-xmlhttprequest-timeout" title="dom-XMLHttpRequest-timeout">timeout</a>;
attribute boolean <a href="#dom-xmlhttprequest-withcredentials" title="dom-XMLHttpRequest-withCredentials">withCredentials</a>;
readonly attribute <a href="#xmlhttprequestupload">XMLHttpRequestUpload</a> <a href="#dom-xmlhttprequest-upload" title="dom-XMLHttpRequest-upload">upload</a>;
void <a href="#dom-xmlhttprequest-send" title="dom-XMLHttpRequest-send">send</a>(optional (<a class="external" href="http://www.khronos.org/registry/typedarray/specs/latest/#6">ArrayBufferView</a> or <a class="external" href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a> or <a class="external" href="http://dom.spec.whatwg.org/#document">Document</a> or DOMString or <a href="#formdata">FormData</a> or <a class="external" href="http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm#idl-def-Stream">Stream</a>)? <var>data</var> = null);
void <a href="#dom-xmlhttprequest-abort" title="dom-XMLHttpRequest-abort">abort</a>();
// <a href="#response">response</a>
readonly attribute unsigned short <a href="#dom-xmlhttprequest-status" title="dom-XMLHttpRequest-status">status</a>;
readonly attribute ByteString <a href="#dom-xmlhttprequest-statustext" title="dom-XMLHttpRequest-statusText">statusText</a>;
ByteString? <a href="#dom-xmlhttprequest-getresponseheader" title="dom-XMLHttpRequest-getResponseHeader">getResponseHeader</a>(ByteString <var>header</var>);
ByteString <a href="#dom-xmlhttprequest-getallresponseheaders" title="dom-XMLHttpRequest-getAllResponseHeaders">getAllResponseHeaders</a>();
void <a href="#dom-xmlhttprequest-overridemimetype" title="dom-XMLHttpRequest-overrideMimeType">overrideMimeType</a>(DOMString <var>mime</var>);
attribute <a href="#xmlhttprequestresponsetype">XMLHttpRequestResponseType</a> <a href="#dom-xmlhttprequest-responsetype" title="dom-XMLHttpRequest-responseType">responseType</a>;
readonly attribute any <a href="#dom-xmlhttprequest-response" title="dom-XMLHttpRequest-response">response</a>;
readonly attribute DOMString <a href="#dom-xmlhttprequest-responsetext" title="dom-XMLHttpRequest-responseText">responseText</a>;
readonly attribute <a class="external" href="http://dom.spec.whatwg.org/#document">Document</a>? <a href="#dom-xmlhttprequest-responsexml" title="dom-XMLHttpRequest-responseXML">responseXML</a>;
};</pre>
<h3 id="base-url,-origin,-and-referrer"><span class="secno">4.1 </span>Base URL, origin, and referrer</h3>
<p>Each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has an associated
<dfn id="xmlhttprequest-base-url"><code>XMLHttpRequest</code> base URL</dfn>,
<dfn id="xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</dfn>, and
<dfn id="xmlhttprequest-referrer-source"><code>XMLHttpRequest</code> referrer source</dfn>.
<p class="note">The XMLHttpRequest standard defines
<a href="#xmlhttprequest-base-url"><code>XMLHttpRequest</code> base URL</a>,
<a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a>, and
<a href="#xmlhttprequest-referrer-source"><code>XMLHttpRequest</code> referrer source</a> when the global
object is represented by the <code class="external"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a></code>
object. Other contexts will have to define them as appropriate for
<code><a href="#xmlhttprequest">XMLHttpRequest</a></code> to function as other contexts are considered
out of scope for this document.</p>
<p>In environments where the global object is represented by the
<code class="external"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a></code> object the
<code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has an associated
<dfn id="xmlhttprequest-document"><code>XMLHttpRequest</code> document</dfn> which is the
<a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a>
associated with the <code class="external"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a></code> object for
which the <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> interface object was created.</p>
<p>In these environments the
<a href="#xmlhttprequest-referrer-source"><code>XMLHttpRequest</code> referrer source</a> is that
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a>.
<p class="note">The
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> is also used to
determine the <a href="#xmlhttprequest-base-url"><code>XMLHttpRequest</code> base URL</a> and
<a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> at a later stage.
<h3 id="task-sources"><span class="secno">4.2 </span>Task sources</h3>
<p>Each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has its own
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#task-source">task source</a>. Namely, the
<dfn id="xmlhttprequest-task-source"><code>XMLHttpRequest</code> task source</dfn>.
<h3 id="constructors"><span class="secno">4.3 </span>Constructors</h3>
<p>The <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has an associated
<dfn id="anonymous-flag">anonymous flag</dfn>. If the <a href="#anonymous-flag">anonymous flag</a> is set,
<a href="#user-credentials">user credentials</a> and the
<a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> are not exposed when
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch" title="fetch">fetching</a> resources.
<dl class="domintro">
<dt><code><var title="">client</var> = new <a href="#dom-xmlhttprequest" title="dom-XMLHttpRequest">XMLHttpRequest</a>()</code>
<dd>Returns a new <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object.
<dt><code><var title="">client</var> = new <a href="#dom-xmlhttprequest" title="dom-XMLHttpRequest">XMLHttpRequest</a>({anon:true})</code>
<dd>Returns a new <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object that has its
<a href="#anonymous-flag">anonymous flag</a> set.
</dl>
<p>The
<dfn id="dom-xmlhttprequest" title="dom-XMLHttpRequest"><code>XMLHttpRequest(<var title="">options</var>)</code></dfn>
constructor must run these steps:
<ol>
<li><p>Let <var title="">xhr</var> be a new <code><a href="#xmlhttprequest">XMLHttpRequest</a></code>
object.
<li><p>If <var title="">options</var>'s <code title="">anon</code> member is
true, set <var title="">xhr</var>'s <a href="#anonymous-flag">anonymous flag</a>.
<li><p>Return <var title="">xhr</var>.
</ol>
<h3 id="garbage-collection"><span class="secno">4.4 </span>Garbage collection</h3>
<!-- Based on EventSource and WebSocket. Not sure what I am doing. -->
<p>An <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object must not be garbage collected if
its state is <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> and the
<a href="#send-flag"><code>send()</code> flag</a> is set, its state is
<a href="#dom-xmlhttprequest-headers_received" title="dom-XMLHttpRequest-HEADERS_RECEIVED">HEADERS_RECEIVED</a>, or
its state is <a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a>, and
one of the following is true:
<ul>
<li><p>It has one or more
<a class="external" href="http://dom.spec.whatwg.org/#concept-event-listener" title="concept-event-listener">event listeners</a>
registered whose <b>type</b> is
<code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>,
<code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>,
<code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>,
<code title="event-xhr-error"><a href="#event-xhr-error">error</a></code>,
<code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>,
<code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code>, or
<code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>.
<li><p>The <a href="#upload-complete-flag">upload complete flag</a> is unset and the associated
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object has one or more
<a class="external" href="http://dom.spec.whatwg.org/#concept-event-listener" title="concept-event-listener">event listeners</a>
registered whose <b>type</b> is
<code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>,
<code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>,
<code title="event-xhr-error"><a href="#event-xhr-error">error</a></code>,
<code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>,
<code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code>, or
<code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>.
</ul>
<p>If an <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object is garbage collected while its
connection is still open, the user agent must cancel any instance of the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch">fetch</a> algorithm opened by this object,
discarding any <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task" title="concept-task">tasks</a>
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queued</a> for them, and
discarding any further data received from the network for them.
<h3 id="event-handlers"><span class="secno">4.5 </span>Event handlers</h3>
<p>The following are the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers">event handlers</a> (and their corresponding
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type" title="event handler event type">event handler event types</a>)
that must be supported on objects implementing an interface that inherits
from <code><a href="#xmlhttprequesteventtarget">XMLHttpRequestEventTarget</a></code> as attributes:</p>
<table>
<thead>
<tr>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers" title="event handlers">event handler</a>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type">event handler event type</a>
<tbody>
<tr>
<td><dfn id="handler-xhr-onloadstart" title="handler-xhr-onloadstart"><code>onloadstart</code></dfn>
<td><code title="event-xhr-loadstart"><a href="#event-xhr-loadstart">loadstart</a></code>
<tr>
<td><dfn id="handler-xhr-onprogress" title="handler-xhr-onprogress"><code>onprogress</code></dfn>
<td><code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>
<tr>
<td><dfn id="handler-xhr-onabort" title="handler-xhr-onabort"><code>onabort</code></dfn>
<td><code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>
<tr>
<td><dfn id="handler-xhr-onerror" title="handler-xhr-onerror"><code>onerror</code></dfn>
<td><code title="event-xhr-error"><a href="#event-xhr-error">error</a></code>
<tr>
<td><dfn id="handler-xhr-onload" title="handler-xhr-onload"><code>onload</code></dfn>
<td><code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>
<tr>
<td><dfn id="handler-xhr-ontimeout" title="handler-xhr-ontimeout"><code>ontimeout</code></dfn>
<td><code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code>
<tr>
<td><dfn id="handler-xhr-onloadend" title="handler-xhr-onloadend"><code>onloadend</code></dfn>
<td><code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>
</table>
<p>The following is the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers" title="event handlers">event handler</a>
(and its corresponding
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type">event handler event type</a>) that must be
supported as attribute solely by the
<code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object:</p>
<table>
<thead>
<tr>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers" title="event handlers">event handler</a>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type">event handler event type</a>
<tbody>
<tr>
<td><dfn id="handler-xhr-onreadystatechange" title="handler-xhr-onreadystatechange"><code>onreadystatechange</code></dfn>
<td><code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code></td>
</table>
<h3 id="states"><span class="secno">4.6 </span>States</h3>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-readystate" title="dom-XMLHttpRequest-readyState">readyState</a></code>
<dd><p>Returns the current state.
</dl>
<p>The <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object can be in several states. The
<dfn id="dom-xmlhttprequest-readystate" title="dom-XMLHttpRequest-readyState"><code>readyState</code></dfn>
attribute must return the current state, which must be one of the
following values:</p>
<dl>
<dt><dfn id="dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT"><code>UNSENT</code></dfn>
(numeric value 0)</dt>
<dd><p>The object has been constructed.</dd>
<dt><dfn id="dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED"><code>OPENED</code></dfn>
(numeric value 1)</dt>
<dd><p>The <code title="dom-XMLHttpRequest-open"><a href="#dom-xmlhttprequest-open">open()</a></code> method has been successfully invoked.
During this state request headers can be set using
<code title="dom-XMLHttpRequest-setRequestHeader"><a href="#dom-xmlhttprequest-setrequestheader">setRequestHeader()</a></code>
and the request can be made using the
<code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method.</dd>
<dt><dfn id="dom-xmlhttprequest-headers_received" title="dom-XMLHttpRequest-HEADERS_RECEIVED"><code>HEADERS_RECEIVED</code></dfn>
(numeric value 2)</dt>
<dd><p>All redirects (if any) have been followed and all HTTP headers of
the final response have been received. Several response members of the
object are now available.</dd>
<dt><dfn id="dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING"><code>LOADING</code></dfn>
(numeric value 3)</dt>
<dd><p>The <a href="#response-entity-body">response entity body</a> is being received.</dd>
<dt><dfn id="dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE"><code>DONE</code></dfn>
(numeric value 4)</dt>
<dd><p>The data transfer has been completed or something went wrong
during the transfer (e.g. infinite redirects).</dd>
</dl>
<p>The <dfn id="send-flag"><code>send()</code> flag</dfn> indicates
that the <code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method has
been invoked. It is initially unset and is used during the
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> state.
<p>The <dfn id="error-flag">error flag</dfn> indicates some type of
network error or request abortion. It is initially unset and is used
during the <a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a> state.
<h3 id="request"><span class="secno">4.7 </span>Request</h3>
<p>Each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has the following
request-associated concepts:</p>
<dl>
<dt><dfn id="synchronous-flag">synchronous flag</dfn></dt>
<dd>Set when <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch" title="fetch">fetching</a> is
done synchronously. Initially unset.</dd>
<dt><dfn id="request-method">request method</dfn></dt>
<dd>The HTTP method used in the request.</dd>
<dt><dfn id="request-url">request URL</dfn></dt>
<dd>The resolved <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#url">URL</a> used in the
request.</dd>
<dt><dfn id="request-username">request username</dfn></dt>
<dd>The username used in the request or null if there is no
username.</dd>
<dt><dfn id="request-password">request password</dfn></dt>
<dd>The password used in the request or null if there is no
password.</dd>
<dt><dfn id="author-request-headers">author request headers</dfn></dt>
<dd>A list consisting of HTTP header name/value pairs to be used in the
request.
<dt><dfn id="request-entity-body">request entity body</dfn></dt>
<dd>The <a class="external" href="http://tools.ietf.org/html/rfc2616/#section-7.2">entity body</a> used in the
request or null if there is no
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-7.2">entity body</a>.</dd>
<dt><dfn id="upload-complete-flag">upload complete flag</dfn></dt>
<dd>Set when no more events are to be dispatched on the
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object. Initially unset.
<dt><dfn id="upload-events-flag">upload events flag</dfn></dt>
<dd>Set when event listeners are registered on the
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object to determine whether a preflight
request is needed. Initially unset.</dd>
</dl>
<p>Each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object also has a unique, associated
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<h4 id="the-open()-method"><span class="secno">4.7.1 </span>The <code title="">open()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-open" title="dom-XMLHttpRequest-open">open</a>(<var title="">method</var>,
<var title="">url</var> [, <var title="">async</var> = true [, <var title="">user</var> = null [,
<var title="">password</var> = null]]])</code>
<dd>
<p>Sets the <a href="#request-method">request method</a>, <a href="#request-url">request URL</a>,
<a href="#synchronous-flag">synchronous flag</a>, <a href="#request-username">request username</a>, and
<a href="#request-password">request password</a>.</p>
<p>Throws a "<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception if
one of the following is true:</p>
<ul>
<li><var title="">method</var> is not a valid HTTP method.</li>
<li><var title="">url</var> cannot be resolved.</li>
<li><var title="">url</var> contains the <code>"user:password"</code>
format in the <code class="external"><a href="http://tools.ietf.org/html/rfc2616/#section-3.2.1">userinfo</a></code> production.
</ul>
<p>Throws a "<code class="external"><a href="http://dom.spec.whatwg.org/#securityerror">SecurityError</a></code>" exception
if <var title="">method</var> is a case-insensitive match for
<code>CONNECT</code>, <code>TRACE</code> or <code>TRACK</code>.</p>
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>"
exception if <var title="">async</var> is false, there is an associated
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> and either the
<a href="#anonymous-flag">anonymous flag</a> is set, the
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> attribute is not
zero, the
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute is true, or the
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code>
attribute is not the empty string.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-open" title="dom-XMLHttpRequest-open"><code>open(<var title="">method</var>, <var title="">url</var>, <var title="">async</var>, <var title="">user</var>, <var title="">password</var>)</code></dfn>
method must run these steps (unless otherwise indicated):</p>
<ol>
<li>
<p>If there is an associated
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> run
these substeps:</p>
<ol>
<li><p>If the
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> is not
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#fully-active">fully active</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate the overall set of steps.
<li><p>Let <a href="#xmlhttprequest-base-url"><code>XMLHttpRequest</code> base URL</a> be the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#document-base-url">document base URL</a> of the
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a>.</li>
<li><p>Let <a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> be the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#origin">origin</a> of the
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a>
and let it be a globally unique identifier if the
<a href="#anonymous-flag">anonymous flag</a> is set.</li>
</ol>
</li>
<li><p>If <var>method</var> does not match the
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-5.1.1">Method</a> token production,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception and terminate
these steps.
<li>
<p>If <var>method</var> is a case-insensitive match for
<code>CONNECT</code>, <code>DELETE</code>, <code>GET</code>,
<code>HEAD</code>, <code>OPTIONS</code>, <code>POST</code>,
<code>PUT</code>, <code>TRACE</code>, or <code>TRACK</code>
subtract 0x20 from each byte in the range 0x61 (ASCII a) to
0x7A (ASCII z).</p>
<p class="note">If it does not match any of the above, it is passed
through <em>literally</em>, including in the final request.</p>
</li>
<!-- WebKit (and supposedly Gecko) also uppercase: COPY, INDEX, LOCK,
M-POST, MKCOL, MOVE, PROPFIND, PROPPATCH, and UNLOCK. -->
<li>
<p>If <var>method</var> is a case-sensitive match for
<code>CONNECT</code>, <code>TRACE</code>, or <code>TRACK</code>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#securityerror">SecurityError</a></code>" exception and
terminate these steps.
<p class="note">Allowing these methods would pose a security risk.
<a href="#refsHTTPVERBSEC">[HTTPVERBSEC]</a>
</li>
<li><p>Let <var title="">url</var> be a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#url">URL</a> with character encoding UTF-8.
<li><p><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#resolve-a-url" title="Resolve a URL">Resolve</a>
<var title="">url</var> relative to the
<a href="#xmlhttprequest-base-url"><code>XMLHttpRequest</code> base URL</a>. If the algorithm
returns an error,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception and terminate
these steps.
<!-- Presto and Gecko override the encoding. WebKit does not. Trident
does not support non-ASCII URLs. This matters for the <query> component,
see HTML. -->
<li><p>Drop
<code class="external" title="url-fragment"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#url-fragment">&lt;fragment&gt;</a></code> from
<var title="">url</var>.</li>
<li><p>If the <code>"user:password"</code> format in the
<code class="external"><a href="http://tools.ietf.org/html/rfc2616/#section-3.2.1">userinfo</a></code> production is not supported
for the relevant
<code class="external" title="url-scheme"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#url-scheme">&lt;scheme&gt;</a></code> and
<var title="">url</var> contains this format,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" and terminate these
steps.
<!-- XXX need to throw here for "user:password" or just "user" for
cross-origin unless we solve this in another way -->
<li><p>If <var title="">url</var> contains the <code>"user:password"</code>
format let <var>temp user</var> be the user part and
<var>temp password</var> be the password part.</li>
<li><p>If <var title="">url</var> just contains the <code>"user"</code>
format let <var>temp user</var> be the user part.</li>
<li><p>If <var>async</var> is false, there is an associated
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> and either the
<a href="#anonymous-flag">anonymous flag</a> is set, the
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> attribute value is
not zero, the
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute value is true, or the
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code>
attribute value is not the empty string,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception and
terminate these steps.
<li><p>If the <var title="">user</var> argument is not null, set
<var>temp user</var> to <var>user</var>.
<li><p>If the <var title="">password</var> argument is not null, set
<var>temp password</var> to <var>password</var>.
<li><p><a href="#terminate-abort()" title="terminate abort()">Terminate the <code>abort()</code> algorithm</a>.</li>
<li><p><a href="#terminate-send()" title="terminate send()">Terminate the <code>send()</code> algorithm</a>.</li>
<li><p>The user agent should cancel any network
activity for which the object is responsible.</li>
<!-- we can hardly require it... -->
<li><p>If there are any
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task" title="concept-task">tasks</a> from the
object's <a href="#xmlhttprequest-task-source"><code>XMLHttpRequest</code> task source</a> in one of
the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#task-queue" title="task queue">task queues</a>,
then remove them.
<li>
<p>Set variables associated with the object as follows:</p>
<ul>
<li><p>Set <a href="#request-method">request method</a> to <var>method</var>.
<li><p>Set <a href="#request-url">request URL</a> to <var title="">url</var>.
<li><p>If <var>async</var> is false, set the
<a href="#synchronous-flag">synchronous flag</a>.
<li><p>Set <a href="#request-username">request username</a> to <var>temp user</var>.
<li><p>Set <a href="#request-password">request password</a> to <var>temp password</var>.
<li><p>Set <a href="#author-request-headers">author request headers</a> to the empty list.
<li><p>Unset the <a href="#send-flag"><code>send()</code> flag</a>.
<li><p>Set <a href="#response-entity-body">response entity body</a> to null.
</ul>
</li>
<li><p>Change the state to
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>.</li>
<li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>.</li>
</ol>
<h4 id="the-setrequestheader()-method"><span class="secno">4.7.2 </span>The <code title="">setRequestHeader()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-setrequestheader" title="dom-XMLHttpRequest-setRequestHeader">setRequestHeader</a>(<var title="">header</var>, <var title="">value</var>)</code>
<dd>
<p>Appends an header to the list of
<a href="#author-request-headers">author request headers</a>, or if <var>header</var> is already
in the list of <a href="#author-request-headers">author request headers</a>, combines its value
with <var>value</var>.</p>
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>"
exception if the state is not
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> or if the
<a href="#send-flag"><code>send()</code> flag</a> is set.</p>
<p>Throws a "<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception if
<var title="">header</var> is not a valid HTTP header field name or if
<var title="">value</var> is not a valid HTTP header field value.</p>
</dd>
</dl>
<p class="note">As indicated in the algorithm below certain headers cannot
be set and are left up to the user agent. In addition there are certain
other headers the user agent will take control of if they are not set by
the author as indicated at the end of the
<code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method section.</p>
<p class="note">For non <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin">same origin</a> requests using the HTTP
<code>GET</code> method a preflight request is made when headers other
than <code>Accept</code> and <code>Accept-Language</code> are set.</p>
<p>The
<dfn id="dom-xmlhttprequest-setrequestheader" title="dom-XMLHttpRequest-setRequestHeader"><code>setRequestHeader(<var title="">header</var>, <var title="">value</var>)</code></dfn>
method must run these steps:</p>
<ol>
<li><p>If the state is not
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If the <a href="#send-flag"><code>send()</code> flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If <var>header</var> does not match the
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-4.2">field-name</a> production,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception and terminate
these steps.
<li>
<p>If <var>value</var> does not match the
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-4.2">field-value</a> production,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception and terminate
these steps.
<p class="note">The empty string is legal and represents the empty
header value.</p>
</li>
<li>
<p>Terminate these steps if <var>header</var> is a case-insensitive
match for one of the following headers:</p>
<ul class="brief">
<li><code>Accept-Charset</code></li>
<li><code>Accept-Encoding</code></li>
<li><code>Access-Control-Request-Headers</code></li>
<li><code>Access-Control-Request-Method</code></li>
<li><code>Connection</code></li>
<li><code>Content-Length</code></li>
<li><code>Cookie</code></li>
<li><code>Cookie2</code></li>
<li><code>Date</code></li>
<li><code>DNT</code></li>
<li><code>Expect</code></li>
<li><code>Host</code></li>
<li><code>Keep-Alive</code></li>
<li><code title="">Origin</code></li>
<li><code>Referer</code></li>
<li><code>TE</code></li>
<li><code>Trailer</code></li>
<li><code>Transfer-Encoding</code></li>
<li><code>Upgrade</code></li>
<li><code>User-Agent</code></li>
<li><code>Via</code></li>
</ul>
<p>… or if the start of <var>header</var> is a case-insensitive
match for <code>Proxy-</code> or <code>Sec-</code> (including when
<var>header</var> is just <code>Proxy-</code> or <code>Sec-</code>).</p>
<p class="note">The above headers are controlled by the user agent to
let it control those aspects of transport. This guarantees data
integrity to some extent. Header names starting with <code>Sec-</code>
are not allowed to be set to allow new headers to be minted that are
guaranteed not to come from <code><a href="#xmlhttprequest">XMLHttpRequest</a></code>.</p>
</li>
<li><p>If <var>header</var> is not in the
<a href="#author-request-headers">author request headers</a> list, append <var>header</var> with
its associated <var>value</var> to the list and terminate these
steps.</li>
<li>
<p>If <var>header</var> is in the <a href="#author-request-headers">author request headers</a>
list, combine <var title="">value</var> with the value of the header
matching <var>header</var> in the <a href="#author-request-headers">author request headers</a>
list (for combine see section 4.2, RFC 2616).
<a href="#refsHTTP">[HTTP]</a>
<p class="note">The XMLHttpRequest standard intentionally constraints the
use of HTTP here in line with contemporary implementations.
</ol>
<p class="note">See also the
<code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method regarding user
agent header handling for caching, authentication, proxies, and
cookies.</p>
<div class="example">
<p>Some simple code demonstrating what happens when setting the same
header twice:</p>
<pre><code>// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send();
// …results in the following header being sent:
X-Test: one, two</code></pre>
</div>
<h4 id="the-timeout-attribute"><span class="secno">4.7.3 </span>The <code title="">timeout</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-timeout" title="dom-XMLHttpRequest-timeout">timeout</a></code>
<dd>
<p>Can be set to a time in milliseconds. When set to a non-zero value
will cause <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch" title="fetch">fetching</a> to
terminate after the given time has passed. When the time has passed, if
the <a href="#synchronous-flag">synchronous flag</a> is unset, a
<code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code> event will then be
<a class="external" href="http://dom.spec.whatwg.org/#concept-event-dispatch" title="concept-event-dispatch">dispatched</a>,
or a "<code class="external"><a href="http://dom.spec.whatwg.org/#timeouterror">TimeoutError</a></code>" exception will be
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">thrown</a> otherwise
(for the <code title="dom-XMLHttpRequest"><a href="#dom-xmlhttprequest">send()</a></code> method).
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception if
the <a href="#synchronous-flag">synchronous flag</a> is set when there is an
associated <a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a>.
</dd>
</dl>
<p>The
<dfn id="dom-xmlhttprequest-timeout" title="dom-XMLHttpRequest-timeout"><code>timeout</code></dfn>
attribute must return its value. Initially its value must be zero.</p>
<p>Setting the <code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code>
attribute must run these steps:
<ol>
<li><p>If there is an associated
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> and the
<a href="#synchronous-flag">synchronous flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception and
terminate these steps.
<li><p>Set its value to the new value.
</ol>
<p class="note">This implies that the
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> attribute can be
set while <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch" title="fetch">fetching</a> is in
progress. If that occurs it will still be measured relative to the start
of <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch" title="fetch">fetching</a>.
<h4 id="the-withcredentials-attribute"><span class="secno">4.7.4 </span>The <code title="">withCredentials</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-withcredentials" title="dom-XMLHttpRequest-withCredentials">withCredentials</a></code>
<dd>
<p>True when <a href="#user-credentials">user credentials</a> are to be included in a
cross-origin request. False when they are to be excluded in a
cross-origin request and when cookies are to be ignored in its response.
Initially false.
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception if the
state is not <a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>, or if
the <a href="#send-flag"><code>send()</code> flag</a> is set.</p>
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception if
either the <a href="#synchronous-flag">synchronous flag</a> is set when there is an
associated <a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> or if the
<a href="#anonymous-flag">anonymous flag</a> is set.</p>
</dd>
</dl>
<p>The
<dfn id="dom-xmlhttprequest-withcredentials" title="dom-XMLHttpRequest-withCredentials"><code>withCredentials</code></dfn>
attribute must return its value. Initially its value must be false.
<p>Setting the
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute must run these steps:</p>
<ol>
<li><p>If the state is not
<a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If the <a href="#send-flag"><code>send()</code> flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If the <a href="#anonymous-flag">anonymous flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception and
terminate these steps.
<li><p>If there is an associated
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> and the
<a href="#synchronous-flag">synchronous flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception and
terminate these steps.
<li><p>Set the
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute's value to the given value.</li>
</ol>
<p class="note">The
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute has no effect when
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch" title="fetch">fetching</a>
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin" title="same origin">same-origin</a>
resources.</p>
<h4 id="the-upload-attribute"><span class="secno">4.7.5 </span>The <code title="">upload</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-upload" title="dom-XMLHttpRequest-upload">upload</a></code>
<dd><p>Returns the associated <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code>
object. It can be used to gather transmission information when data is
transferred to a server.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-upload" title="dom-XMLHttpRequest-upload"><code>upload</code></dfn>
attribute must return the associated
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.</p>
<p class="note">As indicated earlier, each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code>
object has an associated <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<h4 id="the-send()-method"><span class="secno">4.7.6 </span>The <code title="">send()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-send" title="dom-XMLHttpRequest-send">send</a>([<var title="">data</var> = null])</code>
<dd>
<p>Initiates the request. The optional argument provides the
<a href="#request-entity-body">request entity body</a>. The argument is ignored if
<a href="#request-method">request method</a> is <code>GET</code> or
<code>HEAD</code>.</p>
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>"
exception if the state is not
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> or if the
<a href="#send-flag"><code>send()</code> flag</a> is set.</p>
</dd>
</dl>
<p>The
<dfn id="dom-xmlhttprequest-send" title="dom-XMLHttpRequest-send"><code>send(<var>data</var>)</code></dfn>
method must run these steps (unless otherwise noted). This algorithm can
be <dfn id="terminate-send()" title="terminate send()">terminated</dfn> by invoking the
<code title="dom-XMLHttpRequest-open"><a href="#dom-xmlhttprequest-open">open()</a></code> or
<code title="dom-XMLHttpRequest-abort"><a href="#dom-xmlhttprequest-abort">abort()</a></code> method. When it is
<a href="#terminate-send()" title="terminate send()">terminated</a> the user agent
must terminate the algorithm after finishing the step it is on.</p>
<p class="note">The <code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code>
algorithm can only be terminated if the <a href="#synchronous-flag">synchronous flag</a> is
unset and only after the method call has returned.</p>
<ol>
<li><p>If the state is not
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If the <a href="#send-flag"><code>send()</code> flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If the <a href="#request-method">request method</a> is <code>GET</code> or
<code>HEAD</code>, set <var title="">data</var> to null.
<li>
<p>If <var title="">data</var> is null, do not include a
<a href="#request-entity-body">request entity body</a> and go to the next step.
<p>Otherwise, let <var>encoding</var> be null, <var>mime type</var> be
null, and then follow these rules, depending on <var title="">data</var>:
<dl class="switch">
<dt><code class="external"><a href="http://www.khronos.org/registry/typedarray/specs/latest/#6">ArrayBufferView</a></code>
<dd><p>Let the <a href="#request-entity-body">request entity body</a> be the raw data
represented by <var title="">data</var>.</dd>
<dt><code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code>
<dt><code class="external"><a href="http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm#idl-def-Stream">Stream</a></code>
<dd>
<p>If the object's <code title="">type</code> attribute value is not
the empty string, let <var>mime type</var> be its value.
<p class="note">See also <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code>'s
<code class="external" title="dom-Blob-type"><a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-type">type</a></code>
attribute and <code class="external"><a href="http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm#idl-def-Stream">Stream</a></code>'s
<code class="external"><a href="http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm#widl-Stream-type">type</a></code> attribute.
<p>Let the <a href="#request-entity-body">request entity body</a> be the raw data
represented by <var>data</var>.
</dd>
<dt><a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a>
<dd>
<p>Let <var title="">encoding</var> be the
<a class="external" href="http://dom.spec.whatwg.org/#concept-document-encoding" title="concept-document-encoding">encoding</a>
of <var title="">data</var>. If <var title="">encoding</var> is
<a class="external" href="http://encoding.spec.whatwg.org/#utf-16">utf-16</a> or
<a class="external" href="http://encoding.spec.whatwg.org/#utf-16be">utf-16be</a>, set
<var title="">encoding</var> to
<a class="external" href="http://encoding.spec.whatwg.org/#utf-8">utf-8</a>.
<p>If <var title="">data</var> is an
<a class="external" href="http://dom.spec.whatwg.org/#html-document">HTML document</a>, let
<var>mime type</var> be "<code>text/html</code>", or let
<var>mime type</var> be "<code>application/xml</code>" otherwise. Then
append "<code>;charset=<var>encoding</var></code>" to
<var>mime type</var>.
<p><a class="external" href="http://html5.org/specs/dom-parsing.html#concept-serialize" title="concept-serialize">Serialize</a>
<var title="">data</var>, and let the <a href="#request-entity-body">request entity body</a> be the result,
<a class="external" href="http://dev.w3.org/2006/webapi/WebIDL/#dfn-obtain-unicode" title="convert a DOMString to a sequence of Unicode characters">converted to Unicode</a>
and <a class="external" href="http://encoding.spec.whatwg.org/#encode" title="encode">encoded</a> using
encoding <var>encoding</var>. Re-throw any exception this
throws.</p>
<p class="XXX">Should we only encode as utf-8? What happens in the face
of an <a class="external" href="http://encoding.spec.whatwg.org/#encoder-error">encoder error</a>?
<p class="note">In particular, if the document cannot be serialized an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception is
thrown.</p>
<p class="note">Subsequent changes to the
<a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a> have
no effect on what is transferred.
</dd>
<dt>a string
<dd>
<p>Let <var>encoding</var> be UTF-8.</p>
<p>Let <var>mime type</var> be "<code>text/plain;charset=UTF-8</code>".</p>
<p>Let the <a href="#request-entity-body">request entity body</a> be <var title="">data</var>
<a class="external" href="http://dev.w3.org/2006/webapi/WebIDL/#dfn-obtain-unicode" title="convert a DOMString to a sequence of Unicode characters">converted to Unicode</a>
and encoded as utf-8.</p>
</dd>
<dt><code><a href="#formdata">FormData</a></code>
<dd>
<p>Let the <a href="#request-entity-body">request entity body</a> be the result of running
the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#multipart/form-data-encoding-algorithm"><code>multipart/form-data</code> encoding algorithm</a>
with <var>data</var> as <var>form data set</var> and with UTF-8 as the
explicit character encoding.</p>
<p>Let <var>mime type</var> be the concatenation of
"<code title="">multipart/form-data;</code>",
a U+0020 SPACE character,
"<code title="">boundary=</code>", and the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#multipart/form-data-boundary-string"><code>multipart/form-data</code> boundary string</a>
generated by the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#multipart/form-data-encoding-algorithm"><code>multipart/form-data</code> encoding algorithm</a>.
</dl>
<p>If a <code>Content-Type</code> header is in
<a href="#author-request-headers">author request headers</a> and its value is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#valid-mime-type">valid MIME type</a> that has a
<code>charset</code> parameter whose value is not a case-insensitive
match for <var title="">encoding</var>, and <var title="">encoding</var>
is not null, set all the <code>charset</code> parameters of that
<code>Content-Type</code> header to <var title="">encoding</var>.
<p>If no <code>Content-Type</code> header is in
<a href="#author-request-headers">author request headers</a> and <var title="">mime type</var> is
not null, append a <code>Content-Type</code> header with value
<var title="">mime type</var> to <a href="#author-request-headers">author request headers</a>.
<!-- reminder: if we ever change this to always include charset it has
to be included as the first parameter for compatibility reasons -->
</li>
<li><p>If the <a href="#synchronous-flag">synchronous flag</a> is set, release the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#storage-mutex">storage mutex</a>.</li>
<li><p>If the <a href="#synchronous-flag">synchronous flag</a> is unset and one or more
event listeners are registered on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code>
object, set the <a href="#upload-events-flag">upload events flag</a>.
<li><p>Unset the <a href="#error-flag">error flag</a>.</li>
<li><p>Set the <a href="#upload-complete-flag">upload complete flag</a> if there is no
<a href="#request-entity-body">request entity body</a> or if the
<a href="#request-entity-body">request entity body</a> is empty.
<li>
<p>If the <a href="#synchronous-flag">synchronous flag</a> is unset, run these substeps:</p>
<ol>
<li><p>Set the <a href="#send-flag"><code>send()</code> flag</a>.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-loadstart"><a href="#event-xhr-loadstart">loadstart</a></code>.</li>
<li><p>If the <a href="#upload-complete-flag">upload complete flag</a> is unset,
<a href="#concept-event-fire-progress" title="concept-event-fire-progress">fire a progress event</a> named <code title="event-xhr-loadstart"><a href="#event-xhr-loadstart">loadstart</a></code>
on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.</li>
<li><p>Return the <code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code>
method call, but continue running the steps in this algorithm.</li>
</ol>
</li>
<li>
<dl class="switch">
<dt>If the <a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> and the
<a href="#request-url">request URL</a> are <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin">same origin</a></dt>
<dt>If the <a href="#request-url">request URL</a>'s
<code class="external" title="url-scheme"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#url-scheme">&lt;scheme&gt;</a></code> is
"<code title="">data</code>"
<dd>
<p>These are the <dfn id="same-origin-request-steps">same-origin request steps</dfn>.</p>
<p><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/fetching-resources.html#fetch">Fetch</a> the
<a href="#request-url">request URL</a> from <i title="">origin</i>
<a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a>, using
<a href="#xmlhttprequest-referrer-source"><code>XMLHttpRequest</code> referrer source</a> as
<i title="">override referrer source</i>, with the
<i title="">synchronous flag</i> set if the
<a href="#synchronous-flag">synchronous flag</a> is set, using HTTP method
<a href="#request-method">request method</a>, user <a href="#request-username">request username</a> (if
non-null) and password <a href="#request-password">request password</a> (if non-null),
taking into account the <a href="#request-entity-body">request entity body</a>, list of
<a href="#author-request-headers">author request headers</a> and the rules listed at the end of
this section.</p>
<dl class="switch">
<dt>If the <a href="#synchronous-flag">synchronous flag</a> is set</dt>
<dd>
<p>While making the request also follow the
<a href="#same-origin-request-event-rules">same-origin request event rules</a>.</p>
<!--
This cannot involve any task queue whatsoever because that would
mean other tasks on the task queue might get processed as well
which is counter to the whole idea of doing things synchronous.
-->
<p class="note">The
<code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method call will
now be returned by virtue of this algorithm ending.</p>
</dd>
<dt>If the <a href="#synchronous-flag">synchronous flag</a> is unset</dt>
<dd>
<p><a href="#make-upload-progress-notifications">Make upload progress notifications</a>.</p>
<p><a href="#make-progress-notifications">Make progress notifications</a>.</p>
<p>While processing the request, as data becomes available and when
the user interferes with the request,
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queue tasks</a>
to update the <a href="#response-entity-body">response entity body</a> and follow the
<a href="#same-origin-request-event-rules">same-origin request event rules</a>.</p>
</dd>
</dl>
</dd>
<dt>Otherwise</dt>
<dd>
<p>These are the <dfn id="cross-origin-request-steps">cross-origin request steps</dfn>.</p>
<p>Make a <a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request">cross-origin request</a>,
passing these as parameters:</p>
<dl>
<dt>request URL</dt>
<dd>The <a href="#request-url">request URL</a>.</dd>
<dt>request method</dt>
<dd>The <a href="#request-method">request method</a>.</dd>
<dt>author request headers</dt>
<dd>The list of <a href="#author-request-headers">author request headers</a>.</dd>
<dt>request entity body</dt>
<dd>The <a href="#request-entity-body">request entity body</a>.</dd>
<dt>source origin</dt>
<dd>The <a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a>.</dd>
<dt>referrer source
<dd>If the <a href="#anonymous-flag">anonymous flag</a> is set the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#url">URL</a>
"<code title="">about:blank</code>", or the
<a href="#xmlhttprequest-referrer-source"><code>XMLHttpRequest</code> referrer source</a> otherwise.
<dt>omit credentials flag</dt>
<dd>Set if
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute's value is false.
<dt>force preflight flag</dt>
<dd>Set if the <a href="#upload-events-flag">upload events flag</a> is set.
</dl>
<dl class="switch">
<dt>If the <a href="#synchronous-flag">synchronous flag</a> is set</dt>
<dd>
<p>While making the request also follow the
<a href="#cross-origin-request-event-rules">cross-origin request event rules</a>.</p>
<!--
This cannot involve any task queue whatsoever because that would
mean other tasks on the task queue might get processed as well
which is counter to the whole idea of doing things synchronous.
-->
<p class="note">The
<code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method call will
now be returned by virtue of this algorithm ending.</p>
</dd>
<dt>If the <a href="#synchronous-flag">synchronous flag</a> is unset</dt>
<dd>
<p>While processing the request, as data becomes available and when
the end user interferes with the request,
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queue tasks</a>
to update the <a href="#response-entity-body">response entity body</a> and follow the
<a href="#cross-origin-request-event-rules">cross-origin request event rules</a>.</p>
</dd>
</dl>
</dd>
</dl>
</li>
</ol>
<hr>
<p>If the user agent allows the end user to configure a proxy it
should modify the request appropriately; i.e., connect
to the proxy host instead of the origin server, modify the
<code>Request-Line</code> and send <code>Proxy-Authorization</code>
headers as specified.</p>
<hr>
<p>If the user agent supports HTTP Authentication and
<code title="http-authorization">Authorization</code> is not in the list
of <a href="#author-request-headers">author request headers</a>, it should
consider requests originating from the <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object
to be part of the protection space that includes the accessed URIs and
send <code title="http-authorization">Authorization</code> headers and
handle <code>401 Unauthorized</code> requests appropriately.</p>
<p>If authentication fails,
<a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> and the
<a href="#request-url">request URL</a> are <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin">same origin</a>,
<code title="http-authorization">Authorization</code> is not in the list
of <a href="#author-request-headers">author request headers</a>, <a href="#request-username">request username</a> is
null, and <a href="#request-password">request password</a> is null, user agents
should prompt the end user for their username and
password.</p>
<p>Otherwise, if authentication fails, user agents
must not prompt the end user for their username and
password. <a href="#refsHTTPAUTH">[HTTPAUTH]</a>
<p class="note">Unfortunately end users are prompted because of legacy
content constraints. However, when possible this behavior is prohibited,
as it is bad UI. E.g. that is why the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin">same origin</a> restriction is made above.
<hr>
<p>If the user agent supports HTTP State Management it
should persist, discard and send cookies (as received
in the <code>Set-Cookie</code> response header, and sent in the
<code>Cookie</code> header) as applicable.
<a href="#refsCOOKIES">[COOKIES]</a>
<hr>
<p>If the user agent implements a HTTP cache it should
respect <code>Cache-Control</code> headers in
<a href="#author-request-headers">author request headers</a>
(e.g. <code>Cache-Control: no-cache</code> bypasses the cache). It
must not send <code>Cache-Control</code> or
<code>Pragma</code> request headers automatically unless the end user
explicitly requests such behavior (e.g. by reloading the page).</p>
<p>For <code>304 Not Modified</code> responses that are a result of a
user agent generated conditional request the user agent
must act as if the server gave a <code>200 OK</code>
response with the appropriate content. The user agent
must allow <a href="#author-request-headers">author request headers</a> to override automatic cache
validation (e.g. <code>If-None-Match</code> or
<code>If-Modified-Since</code>), in which case
<code>304 Not Modified</code> responses must be passed through.
<a href="#refsHTTP">[HTTP]</a>
<hr>
<p>If the user agent implements server-driven content-negotiation
it must follow these constraints for the
<code>Accept</code> and <code>Accept-Language</code> request headers:</p>
<ul>
<li><p>Both headers must not be modified if they are in
<a href="#author-request-headers">author request headers</a>.
<li><p>If not in <a href="#author-request-headers">author request headers</a>,
<code>Accept-Language</code> with an appropriate value should be appended
to it.
<li><p>If not in <a href="#author-request-headers">author request headers</a>, <code>Accept</code>
with value <code>*/*</code> must be appended to it.
</ul>
<p>Responses must have the content-encodings
automatically decoded. <a href="#refsHTTP">[HTTP]</a>
<hr>
<p>Besides the <a href="#author-request-headers">author request headers</a>, user agents
should not include additional request headers other than those mentioned
above or other than those authors are not allowed to set using
<code title="dom-XMLHttpRequest-setRequestHeader"><a href="#dom-xmlhttprequest-setrequestheader">setRequestHeader()</a></code>.
This ensures that authors have a predictable API.</p>
<h4 id="infrastructure-for-the-send()-method"><span class="secno">4.7.7 </span>Infrastructure for the <code title="">send()</code> method</h4>
<p>The <dfn id="same-origin-request-event-rules">same-origin request event rules</dfn> are as follows:</p>
<dl class="switch">
<dt>If the response has an HTTP status code of 301, 302, 303, 307, or 308
<dd>
<p>If the redirect violates infinite loop precautions this is a
<a href="#network-error">network error</a>.</p>
<p>Otherwise, run these steps:</p>
<ol>
<li><p>Set the <a href="#request-url">request URL</a> to the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#url">URL</a> conveyed by the
<code>Location</code> header.</li>
<li><p>If the <a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> and the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#origin">origin</a> of <a href="#request-url">request URL</a>
are <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin">same origin</a> transparently follow
the redirect while observing the
<a href="#same-origin-request-event-rules">same-origin request event rules</a>.
<li><p>Otherwise, follow the <a href="#cross-origin-request-steps">cross-origin request steps</a>
and terminate the steps for this algorithm.</li>
</ol>
<p class="note">HTTP places requirements on the user agent regarding the
preservation of the <a href="#request-method">request method</a> and
<a href="#request-entity-body">request entity body</a> during redirects, and also requires end
users to be notified of certain kinds of automatic redirections.</p>
<!-- XXX HTTP needs fixing here -->
</dd>
<dt>If the end user cancels the request</dt>
<dd><p>This is an <a href="#abort-error">abort error</a>.</dd>
<dt>If there is a network error</dt>
<dd>
<p>In case of DNS errors, TLS negotiation failure, or other type of
network errors, this is a <a href="#network-error">network error</a>. Do not request any
kind of end user interaction.</p>
<p class="note">This does not include HTTP responses that indicate
some type of error, such as HTTP status code 410.</p>
</dd>
<dt>If <code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> is not 0
and since the request started the amount of milliseconds specified by
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> has passed</dt>
<dd><p>This is a <a href="#timeout-error">timeout error</a>.</dd>
<dt>Once all HTTP headers have been received, the
<a href="#synchronous-flag">synchronous flag</a> is unset, and the HTTP status code of the
response is not one of 301, 302, 303, 307, and 308
<dd><p><a href="#switch-headers-received">Switch to the HEADERS_RECEIVED state</a>.</dd>
<dt>Once the first byte (or more) of the
<a href="#response-entity-body">response entity body</a> has been received and the
<a href="#synchronous-flag">synchronous flag</a> is unset</dt>
<dt>If there is no <a href="#response-entity-body">response entity body</a> and the
<a href="#synchronous-flag">synchronous flag</a> is unset</dt>
<dd><p><a href="#switch-loading">Switch to the LOADING state</a>.</dd>
<dt>Once the whole <a href="#response-entity-body">response entity body</a> has been
received</dt>
<dt>If there is no <a href="#response-entity-body">response entity body</a> and the state is
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a></dt>
<dt>If there is no <a href="#response-entity-body">response entity body</a> and the
<a href="#synchronous-flag">synchronous flag</a> is set</dt>
<dd><p><a href="#switch-done">Switch to the DONE state</a>.</dd>
</dl>
<hr>
<p>The <dfn id="cross-origin-request-event-rules">cross-origin request event rules</dfn> are as follows:</p>
<dl class="switch">
<dt>If the <a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a>
is <i>preflight complete</i> and the <a href="#synchronous-flag">synchronous flag</a> is
unset</dt>
<dd><p><a href="#make-upload-progress-notifications">Make upload progress notifications</a>.</dd>
<dt>If the <a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a>
is <i title="">network error</i></dt>
<dd><p>This is a <a href="#network-error">network error</a>.</dd>
<dt>If the <a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a>
is <i title="">abort error</i></dt>
<dd><p>This is an <a href="#abort-error">abort error</a>.</dd>
<dt>If <code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> is not 0
and since the request started the amount of milliseconds specified by
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> has passed</dt>
<dd><p>This is a <a href="#timeout-error">timeout error</a>.</dd>
<dt>Once all HTTP headers have been received, the
<a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a> is
<i>success</i>, and the <a href="#synchronous-flag">synchronous flag</a> is unset</dt>
<dd>
<p><a href="#switch-headers-received">Switch to the HEADERS_RECEIVED state</a>.</p>
<p><a href="#make-progress-notifications">Make progress notifications</a>.</p>
</dd>
<dt>Once the first byte (or more) of the
<a href="#response-entity-body">response entity body</a> has been received, the
<a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a> is
<i>success</i>, and the <a href="#synchronous-flag">synchronous flag</a> is unset</dt>
<dt>If there is no <a href="#response-entity-body">response entity body</a>, the
<a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a> is
<i>success</i>, and the <a href="#synchronous-flag">synchronous flag</a> is unset</dt>
<dd><p><a href="#switch-loading">Switch to the LOADING state</a>.</dd>
<dt>Once the whole <a href="#response-entity-body">response entity body</a> has been received
and the <a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a> is
<i>success</i></dt>
<dt>If there is no <a href="#response-entity-body">response entity body</a>, the
<a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a> is
<i>success</i>, and the state is
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a></dt>
<dt>If there is no <a href="#response-entity-body">response entity body</a>, the
<a class="external" href="http://fetch.spec.whatwg.org/#cross-origin-request-status">cross-origin request status</a> is
<i>success</i>, and the <a href="#synchronous-flag">synchronous flag</a> is set</dt>
<dd><p><a href="#switch-done">Switch to the DONE state</a>.</dd>
</dl>
<hr>
<p>When something is said to be a <dfn id="network-error">network error</dfn> run the
<a href="#request-error">request error</a> steps for exception
"<code class="external"><a href="http://dom.spec.whatwg.org/#networkerror">NetworkError</a></code>" and
event <code title="event-xhr-error"><a href="#event-xhr-error">error</a></code>.</p>
<p>When something is said to be an <dfn id="abort-error">abort error</dfn> run the
<a href="#request-error">request error</a> steps for exception
"<code class="external"><a href="http://dom.spec.whatwg.org/#aborterror">AbortError</a></code>" and event
<code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>.</p>
<p>When something is said to be an <dfn id="timeout-error">timeout error</dfn> run the
<a href="#request-error">request error</a> steps for exception
"<code class="external"><a href="http://dom.spec.whatwg.org/#timeouterror">TimeoutError</a></code>" and event
<code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code>.</p>
<p>When something is said to be a <dfn id="request-error">request error</dfn> for
exception <var>exception</var> and event <var title="">event</var> run these
steps:</p>
<ol>
<li><p>The user agent should cancel any network
activity for which the object is responsible.</li>
<li><p>If there are any
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task" title="concept-task">tasks</a> from the
object's <a href="#xmlhttprequest-task-source"><code>XMLHttpRequest</code> task source</a> in one of
the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#task-queue" title="task queue">task queues</a>,
then remove them.
<li><p>Set the the <a href="#error-flag">error flag</a>.
<li><p>Change the state to <a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>.</li>
<li><p>If the <a href="#synchronous-flag">synchronous flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
<var>exception</var> exception and terminate the overall set of
steps.</li>
<li>
<p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>.</p>
<p class="note">At this point it is clear that the
<a href="#synchronous-flag">synchronous flag</a> is unset.</p>
</li>
<li>
<p>If the <a href="#upload-complete-flag">upload complete flag</a> is unset, follow these
substeps:</p>
<ol>
<li><p>Set the <a href="#upload-complete-flag">upload complete flag</a>.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named
<code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code> on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named
<var title="">event</var> on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named
<code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code> on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
</ol>
</li>
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <var title="">event</var>.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>.
</ol>
<hr>
<p>When it is said to
<dfn id="switch-headers-received">switch to the HEADERS_RECEIVED state</dfn>
run these steps:</p>
<ol>
<li><p>Change the state to <a href="#dom-xmlhttprequest-headers_received" title="dom-XMLHttpRequest-HEADERS_RECEIVED">HEADERS_RECEIVED</a>.</li>
<li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>.</li>
</ol>
<p>When it is said to
<dfn id="switch-loading">switch to the LOADING state</dfn> run these
steps:</p>
<ol>
<li><p>Change the state to <a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a>.</li>
<li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>.</li>
</ol>
<p>When it is said to
<dfn id="switch-done">switch to the DONE state</dfn> run these steps:</p>
<ol>
<li><p>If the <a href="#synchronous-flag">synchronous flag</a> is set, update the
<a href="#response-entity-body">response entity body</a>.</li>
<li><p>Unset the <a href="#synchronous-flag">synchronous flag</a>.
<li><p>Change the state to <a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>.</li>
<li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>.</li>
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>.</li>
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>.</li>
</ol>
<hr>
<p>When it is said to <dfn id="make-progress-notifications">make progress notifications</dfn>, while the
download is progressing, <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> to
<a href="#concept-event-fire-progress" title="concept-event-fire-progress">fire a progress event</a> named <code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>
about every 50ms or for every byte received, whichever is <em>least</em>
frequent.</p>
<hr>
<p>When it is said to <dfn id="make-upload-progress-notifications">make upload progress notifications</dfn> run
these steps:</p>
<ul>
<li><p>While the request entity body is being transmitted and the
<a href="#upload-complete-flag">upload complete flag</a> is unset,
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> to
<a href="#concept-event-fire-progress" title="concept-event-fire-progress">fire a progress event</a> named <code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code> on
the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object about every 50ms or for
every byte transmitted, whichever is <em>least</em> frequent.</li>
<li>
<p>If the <a href="#request-entity-body">request entity body</a> has been fully transmitted
(irrespective of whether the server has started transmitting a response
or the status code of such a response) and the
<a href="#upload-complete-flag">upload complete flag</a> is still unset,
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> to run these substeps:
<ol>
<li><p>Set the <a href="#upload-complete-flag">upload complete flag</a>.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>
on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>
on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>
on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
</ol>
</ul>
<h4 id="the-abort()-method"><span class="secno">4.7.8 </span>The <code title="">abort()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-abort" title="dom-XMLHttpRequest-abort">abort</a>()</code>
<dd>Cancels any network activity.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-abort" title="dom-XMLHttpRequest-abort"><code>abort()</code></dfn>
method must run these steps (unless otherwise noted). This algorithm can
be <dfn id="terminate-abort()" title="terminate abort()">terminated</dfn> by invoking the
<code title="dom-XMLHttpRequest-open"><a href="#dom-xmlhttprequest-open">open()</a></code> method. When it is
<a href="#terminate-abort()" title="terminate abort()">terminated</a> the user agent
must terminate the algorithm after finishing the step it is on.
<p class="note">The <code title="dom-XMLHttpRequest-abort"><a href="#dom-xmlhttprequest-abort">abort()</a></code>
algorithm can only be terminated by invoking
<code title="dom-XMLHttpRequest-open"><a href="#dom-xmlhttprequest-open">open()</a></code> from an event
handler.</p>
<ol>
<li><p><a href="#terminate-send()" title="terminate send()">Terminate the <code>send()</code> algorithm</a>.</li>
<li><p>The user agent should cancel any network
activity for which the object is responsible.</li>
<li><p>If there are any
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task" title="concept-task">tasks</a> from the
object's <a href="#xmlhttprequest-task-source"><code>XMLHttpRequest</code> task source</a> in one of
the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#task-queue" title="task queue">task queues</a>,
then remove them.
<li><p>Set the <a href="#error-flag">error flag</a>.
<li><p>Unset the <a href="#synchronous-flag">synchronous flag</a>.
<li>
<p>If the state is <a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a>,
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> with the
<a href="#send-flag"><code>send()</code> flag</a> being unset, or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a> go to the next step.</p>
<p>Otherwise run these substeps:</p>
<ol>
<li><p>Change the state to <a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>.</li>
<li><p>Unset the <a href="#send-flag"><code>send()</code> flag</a>.
<li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>.</li>
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>.</li>
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>.</li>
<li>
<p>If the <a href="#upload-complete-flag">upload complete flag</a> is false run these
substeps:</p>
<ol>
<li><p>Set the <a href="#upload-complete-flag">upload complete flag</a> to true.</li>
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>
on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>
on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.</li>
<li><p><a href="#concept-event-fire-progress" title="concept-event-fire-progress">Fire a progress event</a> named <code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>
on the <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.</li>
</ol>
</li>
</ol>
</li>
<li>
<p>Change the state to <a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a>.</p>
<p class="note">No <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code> event is dispatched.</p>
</li>
</ol>
<h3 id="response"><span class="secno">4.8 </span>Response</h3>
<h4 id="the-status-attribute"><span class="secno">4.8.1 </span>The <code title="">status</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-status" title="dom-XMLHttpRequest-status">status</a></code>
<dd><p>Returns the HTTP status code.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-status" title="dom-XMLHttpRequest-status"><code>status</code></dfn>
attribute must return the result of running these
steps:</p>
<ol>
<li><p>If the state is
<a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>, return 0 and
terminate these steps.
<li><p>If the <a href="#error-flag">error flag</a> is set, return 0 and terminate
these steps.</li>
<li><p>Return the HTTP status code.</li>
</ol>
<h4 id="the-statustext-attribute"><span class="secno">4.8.2 </span>The <code title="">statusText</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-statustext" title="dom-XMLHttpRequest-statusText">statusText</a></code>
<dd><p>Returns the HTTP status text.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-statustext" title="dom-XMLHttpRequest-statusText"><code>statusText</code></dfn>
attribute must return the result of running these steps:
<ol>
<li><p>If the state is
<a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>, return the empty
string and terminate these steps.
<li><p>If the <a href="#error-flag">error flag</a> is set, return the empty string and
terminate these steps.
<li><p>Return the HTTP status text.
</ol>
<h4 id="the-getresponseheader()-method"><span class="secno">4.8.3 </span>The <code title="">getResponseHeader()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-getresponseheader" title="dom-XMLHttpRequest-getResponseHeader">getResponseHeader</a>(<var title="">header</var>)</code>
<dd><p>Returns the header field value from the response of which the
field name matches <var title="">header</var>, unless the field name is
<code>Set-Cookie</code> or <code>Set-Cookie2</code>.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-getresponseheader" title="dom-XMLHttpRequest-getResponseHeader"><code>getResponseHeader(<var title="">header</var>)</code></dfn>
method must run these steps:
<ol>
<li><p>If the state is
<a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>, return null and
terminate these steps.
<li><p>If the <a href="#error-flag">error flag</a> is set, return null and terminate
these steps.
<li><p>If <var>header</var> is a case-insensitive match for
<code>Set-Cookie</code> or <code>Set-Cookie2</code>, return null and
terminate these steps.</li>
<li><p>If <var>header</var> is a case-insensitive match for multiple HTTP
response headers, return the values of these headers as a single
concatenated string separated from each other by a
U+002C COMMA U+0020 SPACE character pair and terminate these steps.
<li><p>If <var>header</var> is a case-insensitive match for a single HTTP
response header, return the value of that header and terminate these steps.
<li><p>Return null.</li>
</ol>
<p class="note">The Cross-Origin Resource Sharing specification filters
the headers that are exposed by
<code title="dom-XMLHttpRequest-getResponseHeader"><a href="#dom-xmlhttprequest-getresponseheader">getResponseHeader()</a></code>
for non <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin" title="same origin">same-origin</a>
requests. <a href="#refsCORS">[CORS]</a>
<div class="example">
<p>For the following script:</p>
<pre><code>var client = new XMLHttpRequest();
client.open("GET", "unicorns-are-teh-awesome.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == 2) {
print(client.getResponseHeader("Content-Type"));
}
}</code></pre>
<p>The <code>print()</code> function will get to process something
like:</p>
<pre><code>text/plain; charset=UTF-8</code></pre>
</div>
<h4 id="the-getallresponseheaders()-method"><span class="secno">4.8.4 </span>The <code title="">getAllResponseHeaders()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-getallresponseheaders" title="dom-XMLHttpRequest-getAllResponseHeaders">getAllResponseHeaders</a>()</code>
<dd><p>Returns all headers from the response, with the exception of those
whose field name is <code>Set-Cookie</code> or
<code>Set-Cookie2</code>.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-getallresponseheaders" title="dom-XMLHttpRequest-getAllResponseHeaders"><code>getAllResponseHeaders()</code></dfn>
method must run these steps:</p>
<ol>
<li><p>If the state is
<a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>, return the empty
string and terminate these steps.
<li><p>If the <a href="#error-flag">error flag</a> is set, return the empty string and
terminate these steps.
<li><p>Return all the HTTP headers, excluding headers that are a
case-insensitive match for <code>Set-Cookie</code> or
<code>Set-Cookie2</code>, as a single string, with each header line
separated by a U+000D CR U+000A LF pair, excluding the status line, and
with each header name and header value separated by a
U+003A COLON U+0020 SPACE pair.</li>
</ol>
<p class="note">The Cross-Origin Resource Sharing specification filters
the headers that are exposed by
<code title="dom-XMLHttpRequest-getAllResponseHeaders"><a href="#dom-xmlhttprequest-getallresponseheaders">getAllResponseHeaders()</a></code>
for non <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin" title="same origin">same-origin</a>
requests. <a href="#refsCORS">[CORS]</a>
<div class="example">
<p>For the following script:</p>
<pre><code>var client = new XMLHttpRequest();
client.open("GET", "narwhals-too.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == 2) {
print(this.getAllResponseHeaders());
}
}</code></pre>
<p>The <code>print()</code> function will get to process something
like:</p>
<pre><code>Date: Sun, 24 Oct 2004 04:58:38 GMT
Server: Apache/1.3.31 (Unix)
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8</code></pre>
</div>
<h4 id="response-entity-body-0"><span class="secno">4.8.5 </span>Response entity body</h4>
<p>The <dfn id="response-mime-type">response MIME type</dfn> is the
MIME type the <code>Content-Type</code> header contains excluding any
parameters and
<a class="external" href="http://dom.spec.whatwg.org/#converted-to-ascii-lowercase">converted to ASCII lowercase</a>, or null if
the response header can not be parsed or was omitted. The
<dfn id="override-mime-type">override MIME type</dfn> is initially null
and can get a value if
<code title="dom-XMLHttpRequest-overrideMimeType"><a href="#dom-xmlhttprequest-overridemimetype">overrideMimeType()</a></code>
is invoked. <dfn id="final-mime-type">Final MIME type</dfn> is the
<a href="#override-mime-type">override MIME type</a> unless that is null in which case it is
the <a href="#response-mime-type">response MIME type</a>.
<p>The <dfn id="response-charset">response charset</dfn> is the value of
the <code>charset</code> parameter of the <code>Content-Type</code> header
or null if there was no <code>charset</code> parameter or the header could
not be parsed or was omitted. The
<dfn id="override-charset">override charset</dfn> is initially null and
can get a value if <code title="dom-XMLHttpRequest-overrideMimeType"><a href="#dom-xmlhttprequest-overridemimetype">overrideMimeType()</a></code> is invoked.
<dfn id="final-charset">Final charset</dfn> is the
<a href="#override-charset">override charset</a> unless
that is null in which case it is the <a href="#response-charset">response charset</a>.</p>
<hr>
<p>The <dfn id="response-entity-body">response entity body</dfn> is the
fragment of the <a class="external" href="http://tools.ietf.org/html/rfc2616/#section-7.2">entity body</a> of the
response received so far
(<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a>) or the complete
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-7.2">entity body</a> of the response
(<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>). If the response
does not have an <a class="external" href="http://tools.ietf.org/html/rfc2616/#section-7.2">entity body</a>, the
<a href="#response-entity-body">response entity body</a> is null.</p>
<p class="note">The <a href="#response-entity-body">response entity body</a> is updated as part
of the <code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> algorithm.</p>
<hr>
<p>The
<dfn id="arraybuffer-response-entity-body">arraybuffer response entity body</dfn>
is an <code class="external"><a href="http://www.khronos.org/registry/typedarray/specs/latest/#5">ArrayBuffer</a></code> representing
the <a href="#response-entity-body">response entity body</a>. If the
<a href="#arraybuffer-response-entity-body">arraybuffer response entity body</a> has no value assigned to it
let it be the return value of the following algorithm:</p>
<ol>
<li><p>If the <a href="#response-entity-body">response entity body</a> is null, return an empty
<code class="external"><a href="http://www.khronos.org/registry/typedarray/specs/latest/#5">ArrayBuffer</a></code> object and terminate
these steps.</li>
<li><p>Return an <code class="external"><a href="http://www.khronos.org/registry/typedarray/specs/latest/#5">ArrayBuffer</a></code>
object representing the <a href="#response-entity-body">response entity body</a>.</li>
</ol>
<p>The
<dfn id="blob-response-entity-body">blob response entity body</dfn> is a
<code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code> representing the <a href="#response-entity-body">response entity body</a>. If
the <a href="#blob-response-entity-body">blob response entity body</a> has no value assigned to it let
it be the return value of the following algorithm:</p>
<ol>
<li><p>If the <a href="#response-entity-body">response entity body</a> is null, return an empty
<code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code> object and terminate these steps.</li>
<li><p>Return a <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code> object
representing the <a href="#response-entity-body">response entity body</a>.
</ol>
<p>The
<dfn id="document-response-entity-body">document response entity body</dfn>
is either a
<a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a>
representing the <a href="#response-entity-body">response entity body</a> or null. If the
<a href="#document-response-entity-body">document response entity body</a> has no value assigned to it let
it be the return value of the following algorithm:</p>
<ol>
<li><p>If the <a href="#response-entity-body">response entity body</a> is null, return null and
terminate these steps.</li>
<li><p>If <a href="#final-mime-type">final MIME type</a> is not null,
<code>text/html</code>, <code>text/xml</code>,
<code>application/xml</code>, or does not end in
<code title="">+xml</code>, return null and terminate these steps.
<li>
<p>If <code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is
the empty string and <a href="#final-mime-type">final MIME type</a> is
<code>text/html</code>, return null and terminate these steps.
<p class="note">This is restricted to
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> being
"<code title="">document</code>" in order to prevent breaking legacy
content.
<li>
<p>If <a href="#final-mime-type">final MIME type</a> is <code>text/html</code>, run these
substeps:
<ol>
<li><p>Let <var>charset</var> be the <a href="#final-charset">final charset</a>.
<li><p>If <var>charset</var> is null,
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/parsing.html#prescan-a-byte-stream-to-determine-its-encoding" title="prescan a byte stream to determine its encoding">prescan</a>
the first 1024 bytes of the <a href="#response-entity-body">response entity body</a> and if
that does not terminate unsuccessfully then let <var>charset</var> be
the return value.
<li><p>If <var>charset</var> is null, set <var>charset</var> to
<a class="external" href="http://encoding.spec.whatwg.org/#utf-8">utf-8</a>.
<li><p><a class="external" href="http://encoding.spec.whatwg.org/#decode">Decode</a> byte stream
<a href="#response-entity-body">response entity body</a> using fallback encoding
<var>charset</var> and then let <var title="">document</var> be a
<a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a> that
represents the result of that, parsed following the rules set
forth in the HTML specification for an HTML parser with scripting
disabled. <a href="#refsHTML">[HTML]</a>
<li><p>Set <var title="">document</var>'s
<a class="external" href="http://dom.spec.whatwg.org/#concept-document-encoding" title="concept-document-encoding">encoding</a>
to <var>charset</var>.
</ol>
<li>
<p>Otherwise, let <var title="">document</var> be a
<a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a>
that represents the result of parsing the
<a href="#response-entity-body">response entity body</a> following the rules set forth in the
XML specifications. If that fails (unsupported character encoding,
namespace well-formedness error, etc.), return null and terminate these
steps.
<a href="#refsXML">[XML]</a> <a href="#refsXMLNS">[XMLNS]</a>
<p class="note">Scripts in the resulting document tree will not be
executed, resources referenced will not be loaded and no associated XSLT
will be applied.</p> <!-- XXX more formally?! -->
<!-- XXX what about document's encoding? -->
<li><p>Set <var title="">document</var>'s
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#origin">origin</a> to the
<a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a>.
<li><p>Set <var title="">document</var>'s
<a class="external" href="http://dom.spec.whatwg.org/#concept-document-content-type" title="concept-document-content-type">content type</a>
to <a href="#final-mime-type">final MIME type</a>.
<li><p>Set <var title="">document</var>'s
<a class="external" href="http://dom.spec.whatwg.org/#concept-document-url" title="concept-document-url">URL</a> to
<a href="#request-url">request URL</a>.
<li><p>Return <var title="">document</var>.
</ol>
<p>The <dfn id="json-response-entity-body">JSON response entity body</dfn> is an ECMAScript value
representing the <a href="#response-entity-body">response entity body</a>. The
<a href="#json-response-entity-body">JSON response entity body</a> is the return value of the following
algorithm:</p>
<ol>
<li><p>If the <a href="#response-entity-body">response entity body</a> is null, return null.
<li><p>Let <var title="">JSON text</var> be the result of running
<a class="external" href="http://encoding.spec.whatwg.org/#utf-8-decode">utf-8 decode</a> on byte stream
<a href="#response-entity-body">response entity body</a>.
<li><p>Return the result of invoking the <code title="">parse</code> function
of the <code title="">JSON</code> object defined in ECMAScript, with
<var title="">JSON text</var> as its only argument, or null if that function
throws an exception. <a href="#refsECMASCRIPT">[ECMASCRIPT]</a>
</ol>
<p>The <dfn id="stream-response-entity-body">stream response entity body</dfn> is
<code class="external"><a href="http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm#idl-def-Stream">Stream</a></code> object representing the
<a href="#response-entity-body">response entity body</a>. The
<a href="#stream-response-entity-body">stream response entity body</a> is the return value of the
following algorithm:
<ol>
<li><p>If the <a href="#response-entity-body">response entity body</a> is null, return an empty
<code class="external"><a href="http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm#idl-def-Stream">Stream</a></code> object.
<li><p>Return a <code class="external"><a href="http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm#idl-def-Stream">Stream</a></code> object \
representing the <a href="#response-entity-body">response entity body</a>.
</ol>
<p>The <dfn id="text-response-entity-body">text response entity body</dfn>
is a string representing the <a href="#response-entity-body">response entity body</a>. The
<a href="#text-response-entity-body">text response entity body</a> is the return value of the
following algorithm:</p>
<ol>
<li><p>If the <a href="#response-entity-body">response entity body</a> is null, return the empty
string and terminate these steps.
<li><p>Let <var>charset</var> be the <a href="#final-charset">final charset</a>.
<li>
<p>If <code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is
the empty string, <var>charset</var> is null, and
<a href="#final-mime-type">final MIME type</a> is either null, <code>text/xml</code>,
<code>application/xml</code> or ends in <code title="">+xml</code>, use the
rules set forth in the XML specifications to determine the encoding. Let
<var>charset</var> be the determined encoding.
<a href="#refsXML">[XML]</a> <a href="#refsXMLNS">[XMLNS]</a>
<p class="note">This is restricted to
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> being
the empty string to keep the non-legacy
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> value
"<code title="">text</code>" simple.
<li><p>If <var>charset</var> is null, set <var>charset</var> to
<a class="external" href="http://encoding.spec.whatwg.org/#utf-8">utf-8</a>.
<li><p>Return the result of running
<a class="external" href="http://encoding.spec.whatwg.org/#decode">decode</a> on byte stream
<a href="#response-entity-body">response entity body</a> using fallback encoding
<var>charset</var>.
</ol>
<p class="note">Authors are strongly encouraged to always encode their
resources using UTF-8.</p>
<h4 id="the-overridemimetype()-method"><span class="secno">4.8.6 </span>The <code title="">overrideMimeType()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-overridemimetype" title="dom-XMLHttpRequest-overrideMimeType">overrideMimeType</a>(<var title="">mime</var>)</code>
<dd>
<p>Sets the <code>Content-Type</code> header for the response to
<var title="">mime</var>.</p>
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>"
exception if the state is
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>.
<p>Throws a "<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception if
<var title="">mime</var> is not a valid media type.</p>
</dd>
</dl>
<p>The
<dfn id="dom-xmlhttprequest-overridemimetype" title="dom-XMLHttpRequest-overrideMimeType"><code>overrideMimeType(<var title="">mime</var>)</code></dfn>
method must run these steps:
<ol>
<li><p>If the state is
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If parsing <var title="">mime</var> analogously to the value of
the <code>Content-Type</code> headers fails,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception and terminate
these steps.
<li><p>If a MIME type is successfully parsed, set
<a href="#override-mime-type">override MIME type</a> to that MIME type,
excluding any parameters, and
<a class="external" href="http://dom.spec.whatwg.org/#converted-to-ascii-lowercase">converted to ASCII lowercase</a>.
<li><p>If a <code>charset</code> parameter is successfully parsed, set
<a href="#override-charset">override charset</a> to its value.</li>
</ol>
<h4 id="the-responsetype-attribute"><span class="secno">4.8.7 </span>The <code title="">responseType</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-responsetype" title="dom-XMLHttpRequest-responseType">responseType</a></code> [ = <var title="">value</var> ]
<dd>
<p>Returns the response type.</p>
<p>Can be set to change the response type. Values are:
the empty string (default),
"<code title="">arraybuffer</code>",
"<code title="">blob</code>",
"<code title="">document</code>",
"<code title="">json</code>",
"<code title="">stream</code>", and
"<code title="">text</code>".
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception if the
state is <a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>.
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception if the
<a href="#synchronous-flag">synchronous flag</a> is set and there is an associated
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a>.</p>
</dl>
<p>The
<dfn id="dom-xmlhttprequest-responsetype" title="dom-XMLHttpRequest-responseType"><code>responseType</code></dfn>
attribute must return its value. Initially its value must be the empty
string.
<p>Setting the
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code>
attribute must run these steps:
<ol>
<li><p>If the state is
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If there is an associated
<a href="#xmlhttprequest-document"><code>XMLHttpRequest</code> document</a> and the
<a href="#synchronous-flag">synchronous flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception and
terminate these steps.
<li><p>Set the
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code>
attribute's value to the given value.</li>
</ol>
<h4 id="the-response-attribute"><span class="secno">4.8.8 </span>The <code title="">response</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-response" title="dom-XMLHttpRequest-response">response</a></code>
<dd><p>Returns the <a href="#response-entity-body">response entity body</a>.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-response" title="dom-XMLHttpRequest-response"><code>response</code></dfn>
attribute must return the result of running these
steps:</p>
<dl class="switch">
<dt>If <code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code>
is the empty string or "<code title="">text</code>"</dt>
<dd>
<ol>
<li><p>If the state is not
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>, return the empty
string and terminate these steps.</li>
<li><p>If the <a href="#error-flag">error flag</a> is set, return the empty string
and terminate these steps.</li>
<li><p>Return the <a href="#text-response-entity-body">text response entity body</a>.</li>
</ol>
<dt>If <code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code>
is "<code title="">stream</code>"
<dd>
<ol>
<li><p>If the state is not
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>, return null and
terminate these steps.
<li><p>If the <a href="#error-flag">error flag</a> is set, return null and terminate
these steps.
<li><p>Return the <a href="#stream-response-entity-body">stream response entity body</a>.
</ol>
<dt>Otherwise</dt>
<dd>
<ol>
<li><p>If the state is not
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>, return null and
terminate these steps.</li>
<li><p>If the <a href="#error-flag">error flag</a> is set, return null and terminate
these steps.</li>
<li>
<dl class="switch">
<dt>If
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is
"<code title="">arraybuffer</code>"</dt>
<dd><p>Return the
<a href="#arraybuffer-response-entity-body">arraybuffer response entity body</a>.</dd>
<dt>If
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is
"<code title="">blob</code>"</dt>
<dd><p>Return the
<a href="#blob-response-entity-body">blob response entity body</a>.</dd>
<dt>If
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is
"<code title="">document</code>"</dt>
<dd><p>Return the
<a href="#document-response-entity-body">document response entity body</a>.</dd>
<dt>If
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is
"<code title="">json</code>"</dt>
<dd><p>Return the
<a href="#json-response-entity-body">JSON response entity body</a>.</dd>
</dl>
</ol>
</dl>
<h4 id="the-responsetext-attribute"><span class="secno">4.8.9 </span>The <code title="">responseText</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-responsetext" title="dom-XMLHttpRequest-responseText">responseText</a></code>
<dd>
<p>Returns the <a href="#text-response-entity-body">text response entity body</a>.
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>"
exception if
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is not
the empty string or "<code title="">text</code>".
</dl>
<p>The
<dfn id="dom-xmlhttprequest-responsetext" title="dom-XMLHttpRequest-responseText"><code>responseText</code></dfn>
attribute must return the result of running these
steps:</p>
<ol>
<li><p>If
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is not
the empty string or "<code title="">text</code>",
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.
<li><p>If the state is not
<a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> or
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>, return the empty
string and terminate these steps.</li>
<li><p>If the <a href="#error-flag">error flag</a> is set, return the empty string and
terminate these steps.</li>
<li><p>Return the <a href="#text-response-entity-body">text response entity body</a>.</li>
</ol>
<h4 id="the-responsexml-attribute"><span class="secno">4.8.10 </span>The <code title="">responseXML</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-responsexml" title="dom-XMLHttpRequest-responseXML">responseXML</a></code>
<dd>
<p>Returns the <a href="#document-response-entity-body">document response entity body</a>.</p>
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>"
exception if
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is not
the empty string or "<code title="">document</code>".
</dl>
<p>The
<dfn id="dom-xmlhttprequest-responsexml" title="dom-XMLHttpRequest-responseXML"><code>responseXML</code></dfn>
attribute must return the result of running these steps:</p>
<ol>
<li><p>If
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> is not
the empty string or "<code title="">document</code>",
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception and
terminate these steps.</li>
<li><p>If the state is not
<a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a>, return null and
terminate these steps.
<li><p>If the <a href="#error-flag">error flag</a> is set, return null and terminate
these steps.
<li><p>Return the <a href="#document-response-entity-body">document response entity body</a>.</li>
</ol>
<p class="note">The
<code title="dom-XMLHttpRequest-responseXML"><a href="#dom-xmlhttprequest-responsexml">responseXML</a></code> attribute
has XML in its name for historical reasons. It also returns HTML resources
as documents.</p>
<h3 id="events"><span class="secno">4.9 </span>Events summary</h3>
<p><em>This section is non-normative.</em></p>
<p>The following events are dispatched on <code><a href="#xmlhttprequest">XMLHttpRequest</a></code>
and/or <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> objects:</p>
<table>
<thead>
<tr>
<th>Event name</th>
<th>Interface</th>
<th>Dispatched when…</th>
</tr>
</thead>
<tbody>
<tr>
<td><dfn id="event-xhr-readystatechange" title="event-xhr-readystatechange"><code>readystatechange</code></dfn></td>
<td><code class="external"><a href="http://dom.spec.whatwg.org/#event">Event</a></code></td>
<td>The <code title="dom-XMLHttpRequest-readyState"><a href="#dom-xmlhttprequest-readystate">readyState</a></code>
attribute changes at some seemingly arbitrary times for historical
reasons.</td>
</tr>
<tr>
<td><dfn id="event-xhr-loadstart" title="event-xhr-loadstart"><code>loadstart</code></dfn></td>
<td><code><a href="#progressevent">ProgressEvent</a></code></td>
<td>When the request starts.</td>
</tr>
<tr>
<td><dfn id="event-xhr-progress" title="event-xhr-progress"><code>progress</code></dfn></td>
<td><code><a href="#progressevent">ProgressEvent</a></code></td>
<td>While sending and loading data.</td>
</tr>
<tr>
<td><dfn id="event-xhr-abort" title="event-xhr-abort"><code>abort</code></dfn></td>
<td><code><a href="#progressevent">ProgressEvent</a></code></td>
<td>When the request has been aborted. For instance, by invoking the
<code title="dom-XMLHttpRequest-abort"><a href="#dom-xmlhttprequest-abort">abort()</a></code> method.</td>
</tr>
<tr>
<td><dfn id="event-xhr-error" title="event-xhr-error"><code>error</code></dfn></td>
<td><code><a href="#progressevent">ProgressEvent</a></code></td>
<td>When the request has failed.</td>
</tr>
<tr>
<td><dfn id="event-xhr-load" title="event-xhr-load"><code>load</code></dfn></td>
<td><code><a href="#progressevent">ProgressEvent</a></code></td>
<td>When the request has successfully completed.</td>
</tr>
<tr>
<td><dfn id="event-xhr-timeout" title="event-xhr-timeout"><code>timeout</code></dfn></td>
<td><code><a href="#progressevent">ProgressEvent</a></code></td>
<td>When the author specified timeout has passed before the request
could complete.</td>
</tr>
<tr>
<td><dfn id="event-xhr-loadend" title="event-xhr-loadend"><code>loadend</code></dfn></td>
<td><code><a href="#progressevent">ProgressEvent</a></code></td>
<td>When the request has completed (either in success or failure).</td>
</tr>
</tbody>
</table>
<h2 id="interface-formdata"><span class="secno">5 </span>Interface <code title="">FormData</code></h2>
<p>The <code><a href="#formdata">FormData</a></code> object represents an ordered collection of
entries. Each entry has a name, a value, a type, and optionally a
filename (if type is "file").</p>
<pre class="idl">[<a href="#dom-formdata" title="dom-FormData">Constructor</a>,
<a href="#dom-formdata-form" title="dom-FormData-form">Constructor</a>(<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#htmlformelement">HTMLFormElement</a> <var>form</var>)]
interface <dfn id="formdata">FormData</dfn> {
void <a href="#dom-formdata-append" title="dom-FormData-append">append</a>(DOMString <var>name</var>, <a class="external" href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a> <var title="">value</var>, optional DOMString <var title="">filename</var>);
void <a href="#dom-formdata-append" title="dom-FormData-append">append</a>(DOMString <var>name</var>, DOMString <var>value</var>);
};</pre>
<h3 id="formdata-constructors"><span class="secno">5.1 </span>Constructors</h3>
<dl class="domintro">
<dt><code><var title="">fd</var> = new <a href="#dom-formdata" title="dom-FormData">FormData</a>()</code>
<dd><p>Returns a new <code><a href="#formdata">FormData</a></code> object.
</dl>
<p>The <dfn id="dom-formdata" title="dom-FormData"><code>FormData()</code></dfn> constructor
must return a new <code><a href="#formdata">FormData</a></code> object.
<p>The
<dfn id="dom-formdata-form" title="dom-FormData-form"><code>FormData(<var>form</var>)</code></dfn>
constructor must return a new <code><a href="#formdata">FormData</a></code> object with as entries
the result of
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#constructing-form-data-set">constructing the form data set</a> for
<var>form</var>.
<h3 id="the-append()-method"><span class="secno">5.2 </span>The <code title="">append()</code> method</h3>
<dl class="domintro">
<dt><code><var title="">fd</var> . <a href="#dom-formdata-append" title="dom-FormData-append">append</a>(<var title="">name</var>, <var title="">value</var> [, <var title="">filename</var>])</code>
<dd><p>Appends a new name/value-pair to the <code><a href="#formdata">FormData</a></code>
object, optionally with a filename.
</dl>
<p>The
<dfn id="dom-formdata-append" title="dom-FormData-append"><code>append(<var>name</var>, <var>value</var>, <var>filename</var>)</code></dfn>
method must create a new entry with the following parameters set and
append it to the end of the collection the <code><a href="#formdata">FormData</a></code> object
represents:</p>
<ul>
<li>Set its name to <var>name</var>.
<li>Set its value to <var>value</var>.
<li>Set its type to "text" if <var>value</var> is a string and "file" if
it is a <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code>.
<li>If its type is "file" set its filename to "<code title="">blob</code>".
<li>If its type is "file" and <var>value</var> is a
<code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#file">File</a></code> whose
<code class="external" title="dom-File-name"><a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-name">name</a></code> attribute
is not the empty string, set entry's filename to the attribute's value.
<li>If the <var title="">filename</var> parameter is not omitted set entry's
filename to <var title="">filename</var>.
</ul>
<h2 id="interface-progressevent"><span class="secno">6 </span>Interface <code title="">ProgressEvent</code></h2>
<pre class="idl">[Constructor(DOMString <var title="">type</var>, optional <a href="#progresseventinit">ProgressEventInit</a> <var title="">eventInitDict</var>)]
interface <dfn id="progressevent">ProgressEvent</dfn> : <a class="external" href="http://dom.spec.whatwg.org/#event">Event</a> {
readonly attribute boolean <a href="#dom-progressevent-lengthcomputable" title="dom-ProgressEvent-lengthComputable">lengthComputable</a>;
readonly attribute unsigned long long <a href="#dom-progressevent-loaded" title="dom-ProgressEvent-loaded">loaded</a>;
readonly attribute unsigned long long <a href="#dom-progressevent-total" title="dom-ProgressEvent-total">total</a>;
};
dictionary <dfn id="progresseventinit">ProgressEventInit</dfn> : <a class="external" href="http://dom.spec.whatwg.org/#eventinit">EventInit</a> {
boolean <span title="dom-ProgressEventInit-lengthComputable">lengthComputable</span>;
unsigned long long <span title="dom-ProgressEventInit-loaded">loaded</span>;
unsigned long long <span title="dom-ProgressEventInit-total">total</span>;
}</pre>
<p><a class="external" href="http://dom.spec.whatwg.org/#concept-event" title="concept-event">Events</a> using
the <code><a href="#progressevent">ProgressEvent</a></code> interface indicate some kind of
progression.</p>
<p>The
<dfn id="dom-progressevent-lengthcomputable" title="dom-ProgressEvent-lengthComputable"><code>lengthComputable</code></dfn>
attribute must return the value it was initialized to. When an
<a class="external" href="http://dom.spec.whatwg.org/#concept-event" title="concept-event">event</a> is created
the attribute must be initialized to false.</p>
<p>The
<dfn id="dom-progressevent-loaded" title="dom-ProgressEvent-loaded"><code>loaded</code></dfn> and
<dfn id="dom-progressevent-total" title="dom-ProgressEvent-total"><code>total</code></dfn>
attributes must return the value they were initialized to. When an
<a class="external" href="http://dom.spec.whatwg.org/#concept-event" title="concept-event">event</a> is created
the attributes must be initialized to 0.</p>
<h3 id="firing-events-using-the-progressevent-interface-for-http"><span class="secno">6.1 </span>Firing events using the <code title="">ProgressEvent</code> interface for HTTP</h3>
<p>To
<dfn id="concept-event-fire-progress" title="concept-event-fire-progress">fire a progress event named <var>e</var></dfn>
means to
<a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">fire an event named <var>e</var></a>
with an <a class="external" href="http://dom.spec.whatwg.org/#concept-event" title="concept-event">event</a>
using the <code><a href="#progressevent">ProgressEvent</a></code> interface that also meets these
conditions:
<ul>
<li>Initialize the <code title="dom-ProgressEvent-loaded"><a href="#dom-progressevent-loaded">loaded</a></code>
attribute to the number of HTTP
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-7.2">entity body</a> bytes transferred.
<li>If the length of the HTTP
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-7.2">entity body</a> is known through the
<code class="external" title="http-content-length"><a href="http://tools.ietf.org/html/rfc2616/#section-14.13">Content-Length</a></code>
header, initialize the