xhr.bs

<pre class=metadata>
Group: WHATWG
H1: XMLHttpRequest
Shortname: xhr
Text Macro: TWITTER xhrstandard
Text Macro: LATESTRD 2024-02
Abstract: The XMLHttpRequest Standard defines an API that provides scripted client functionality for transferring data between a client and a server.
Translation: ja https://triple-underscore.github.io/XHR-ja.html
Translate IDs: enumdef-xmlhttprequestresponsetype xmlhttprequestresponsetype,dictdef-progresseventinit progresseventinit,typedefdef-formdataentryvalue formdataentryvalue
</pre>

<!-- Temporary: https://github.com/w3c/webdriver-bidi/issues/358 -->
<pre class=link-defaults>
spec:webdriver-bidi; type:dfn; text:event
spec:fetch; type:dfn; for:/; text:credentials
</pre>

<pre class=anchors>
urlPrefix: https://w3c.github.io/DOM-Parsing/; spec: dom-parsing
    type: dfn; text: fragment serializing algorithm; url: dfn-fragment-serializing-algorithm
</pre>



<h2 id=introduction>Introduction</h2>

<p><em>This section is non-normative.</em>

<p>The {{XMLHttpRequest}} object is an API for <a for=/>fetching</a> resources.

<p>The name {{XMLHttpRequest}} is historical and has no bearing on its functionality.

<div id=example-xhr class=example>
 <p>Some simple code to do something with data from an XML document
 fetched over the network:

 <pre><code class=lang-javascript>
function processData(data) {
  // taking care of data
}

function handler() {
  if(this.status == 200 &amp;&amp;
    this.responseXML != null &amp;&amp;
    this.responseXML.getElementById('test').textContent) {
    // success!
    processData(this.responseXML.getElementById('test').textContent);
  } else {
    // something went wrong
    …
  }
}

var client = new XMLHttpRequest();
client.onload = handler;
client.open("GET", "unicorn.xml");
client.send();</code></pre>

 <p>If you just want to log a message to the server:

 <pre><code class=lang-javascript>
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:

 <pre><code class=lang-javascript>
function fetchStatus(address) {
  var client = new XMLHttpRequest();
  client.onload = function() {
    // in case of network errors this might not give reliable results
    returnStatus(this.status);
  }
  client.open("HEAD", address);
  client.send();
}</code></pre>
</div>


<h3 id=specification-history>Specification history</h3>

<p>The {{XMLHttpRequest}} object was initially defined as part of
the WHATWG's HTML effort. (Based on Microsoft's implementation many years prior.)
It moved to the W3C in 2006. Extensions (e.g., progress events and
cross-origin requests) to {{XMLHttpRequest}} were developed in a
separate draft (XMLHttpRequest Level 2) until end of 2011, at which point
the two drafts were merged and {{XMLHttpRequest}} became a single
entity again from a standards perspective. End of 2012 it moved back to the
WHATWG.

<p>Discussion that led to the current draft can be found in the following mailing list
archives:

<ul class=brief>
 <li><a href=https://lists.w3.org/Archives/Public/public-whatwg-archive/>whatwg@whatwg.org</a>
 <li><a href=https://lists.w3.org/Archives/Public/public-webapps/>public-webapps@w3.org</a>
 <li><a href=https://lists.w3.org/Archives/Public/public-webapi/>public-webapi@w3.org</a>
 <li><a href=https://lists.w3.org/Archives/Public/public-appformats/>public-appformats@w3.org</a>
</ul>



<h2 id=terminology>Terminology</h2>

<p>This specification depends on the Infra Standard. [[!INFRA]]

<p>This specification uses terminology from DOM, DOM Parsing and Serialization, Encoding,
Fetch, File API, HTML, URL, Web IDL, and XML.

[[!DOM]]
[[!DOM-PARSING]]
[[!ENCODING]]
[[!FETCH]]
[[!FILEAPI]]
[[!HTML]]
[[!URL]]
[[!WEBIDL]]
[[!XML]] [[!XML-NAMES]]



<h2 id=interface-xmlhttprequest>Interface {{XMLHttpRequest}}</h2>

<pre class=idl>
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestEventTarget : EventTarget {
  // event handlers
  attribute EventHandler onloadstart;
  attribute EventHandler onprogress;
  attribute EventHandler onabort;
  attribute EventHandler onerror;
  attribute EventHandler onload;
  attribute EventHandler ontimeout;
  attribute EventHandler onloadend;
};

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
};

enum XMLHttpRequestResponseType {
  "",
  "arraybuffer",
  "blob",
  "document",
  "json",
  "text"
};

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequest : XMLHttpRequestEventTarget {
  constructor();

  // event handler
  attribute EventHandler onreadystatechange;

  // states
  const unsigned short UNSENT = 0;
  const unsigned short OPENED = 1;
  const unsigned short HEADERS_RECEIVED = 2;
  const unsigned short LOADING = 3;
  const unsigned short DONE = 4;
  readonly attribute unsigned short readyState;

  // request
  undefined open(ByteString method, USVString url);
  undefined open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
  undefined setRequestHeader(ByteString name, ByteString value);
           attribute unsigned long timeout;
           attribute boolean withCredentials;
  [SameObject] readonly attribute XMLHttpRequestUpload upload;
  undefined send(optional (Document or XMLHttpRequestBodyInit)? body = null);
  undefined abort();

  // response
  readonly attribute USVString responseURL;
  readonly attribute unsigned short status;
  readonly attribute ByteString statusText;
  ByteString? getResponseHeader(ByteString name);
  ByteString getAllResponseHeaders();
  undefined overrideMimeType(DOMString mime);
           attribute XMLHttpRequestResponseType responseType;
  readonly attribute any response;
  readonly attribute USVString responseText;
  [Exposed=Window] readonly attribute Document? responseXML;
};
</pre>

<p>An {{XMLHttpRequest}} object has an associated:

<dl>
 <dt><dfn>upload object</dfn>
 <dd>An {{XMLHttpRequestUpload}} object.

 <dt><dfn id=concept-xmlhttprequest-state>state</dfn>
 <dd>One of <i>unsent</i>, <i>opened</i>, <i>headers received</i>, <i>loading</i>, and <i>done</i>;
 initially <i>unsent</i>.

 <dt><dfn id=send-flag><code>send()</code> flag</dfn>
 <dd>A flag, initially unset.

 <dt><dfn>timeout</dfn>
 <dd>An unsigned integer, initially 0.

 <dt><dfn>cross-origin credentials</dfn>
 <dd>A boolean, initially false.

 <dt><dfn>request method</dfn>
 <dd>A <a for=/>method</a>.

 <dt><dfn>request URL</dfn>
 <dd>A <a for=/>URL</a>.

 <dt><dfn id=author-request-headers>author request headers</dfn>
 <dd>A <a for=/>header list</a>, initially empty.

 <dt><dfn>request body</dfn>
 <dd>Initially null.

 <dt><dfn>synchronous flag</dfn>
 <dd>A flag, initially unset.

 <dt><dfn id=upload-complete-flag>upload complete flag</dfn>
 <dd>A flag, initially unset.

 <dt><dfn>upload listener flag</dfn>
 <dd>A flag, initially unset.

 <dt><dfn>timed out flag</dfn>
 <dd>A flag, initially unset.

 <dt><dfn id=response for=XMLHttpRequest>response</dfn>
 <dd>A <a for=/>response</a>, initially a <a>network error</a>.

 <dt><dfn>received bytes</dfn>
 <dd>A <a for=/>byte sequence</a>, initially the empty byte sequence.

 <dt><dfn>response type</dfn>
 <dd>One of the empty string, "<code>arraybuffer</code>", "<code>blob</code>",
 "<code>document</code>", "<code>json</code>", and "<code>text</code>"; initially the empty string.

 <dt><dfn>response object</dfn>
 <dd>An object, failure, or null, initially null.

 <dt><dfn for=XMLHttpRequest>fetch controller</dfn>
 <dd>A <a for=/>fetch controller</a>, initially a new <a for=/>fetch controller</a>.
 <span class=note>The <a><code>send()</code></a> method sets it to a useful
 <a for=/>fetch controller</a>, but for simplicity it always holds a
 <a for=/>fetch controller</a>.</span>

 <dt><dfn id=override-mime-type>override MIME type</dfn>
 <dd>A <a for=/>MIME type</a> or null, initially null. <span class=note>Can get a value when
 {{overrideMimeType()}} is invoked.</span>
</dl>


<h3 id=constructors>Constructors</h3>

<dl class=domintro>
 <dt><code><var>client</var> = new <a constructor for=XMLHttpRequest>XMLHttpRequest()</a></code>
 <dd>Returns a new {{XMLHttpRequest}} object.
</dl>

<p>The
<dfn id=dom-xmlhttprequest constructor for=XMLHttpRequest lt="XMLHttpRequest()"><code>new XMLHttpRequest()</code></dfn>
constructor steps are:

<ol>
 <li><p>Set <a>this</a>'s <a>upload object</a> to a <a for=/>new</a>
 <code>XMLHttpRequestUpload</code> object.
</ol>


<h3 id=garbage-collection>Garbage collection</h3>
<!-- Based on EventSource and WebSocket. Not sure what I am doing. -->

<p>An {{XMLHttpRequest}} object must not be garbage collected if its
<a>state</a> is either
<i>opened</i> with the <a><code>send()</code> flag</a> set,
<i>headers received</i>, or <i>loading</i>, and it has one or more
<a>event listeners</a>
registered whose <b>type</b> is one of
{{XMLHttpRequest/readystatechange}},
{{XMLHttpRequestEventTarget/progress}},
{{XMLHttpRequestEventTarget/abort}},
{{XMLHttpRequestEventTarget/error}},
{{XMLHttpRequestEventTarget/load}},
{{XMLHttpRequestEventTarget/timeout!!event}}, and
{{XMLHttpRequestEventTarget/loadend}}.
<!-- No need to mention upload event listeners as they happen during /opened/. -->

<p>If an {{XMLHttpRequest}} object is garbage collected while its connection is still open, the user
agent must <a for="fetch controller">terminate</a> the {{XMLHttpRequest}} object's
<a for=XMLHttpRequest>fetch controller</a>.


<h3 id=event-handlers>Event handlers</h3>

<p>The following are the
<a>event handlers</a> (and their corresponding
<a>event handler event types</a>)
that must be supported on objects implementing an interface that inherits
from {{XMLHttpRequestEventTarget}} as attributes:

<table>
 <thead>
  <tr>
   <th><a lt="event handlers">event handler</a>
   <th><a>event handler event type</a>
 <tbody>
  <tr>
   <td><dfn id=handler-xhr-onloadstart attribute for=XMLHttpRequestEventTarget><code>onloadstart</code></dfn>
   <td>{{XMLHttpRequestEventTarget/loadstart}}
  <tr>
   <td><dfn id=handler-xhr-onprogress attribute for=XMLHttpRequestEventTarget><code>onprogress</code></dfn>
   <td>{{XMLHttpRequestEventTarget/progress}}
  <tr>
   <td><dfn id=handler-xhr-onabort attribute for=XMLHttpRequestEventTarget><code>onabort</code></dfn>
   <td>{{XMLHttpRequestEventTarget/abort}}
  <tr>
   <td><dfn id=handler-xhr-onerror attribute for=XMLHttpRequestEventTarget><code>onerror</code></dfn>
   <td>{{XMLHttpRequestEventTarget/error}}
  <tr>
   <td><dfn id=handler-xhr-onload attribute for=XMLHttpRequestEventTarget><code>onload</code></dfn>
   <td>{{XMLHttpRequestEventTarget/load}}
  <tr>
   <td><dfn id=handler-xhr-ontimeout attribute for=XMLHttpRequestEventTarget><code>ontimeout</code></dfn>
   <td>{{XMLHttpRequestEventTarget/timeout!!event}}
  <tr>
   <td><dfn id=handler-xhr-onloadend attribute for=XMLHttpRequestEventTarget><code>onloadend</code></dfn>
   <td>{{XMLHttpRequestEventTarget/loadend}}
</table>

<p>The following is the
<a lt="event handlers">event handler</a>
(and its corresponding
<a>event handler event type</a>) that must be
supported as attribute solely by the
{{XMLHttpRequest}} object:

<table>
 <thead>
  <tr>
   <th><a lt="event handlers">event handler</a>
   <th><a>event handler event type</a>
 <tbody>
  <tr>
   <td><dfn id=handler-xhr-onreadystatechange attribute for=XMLHttpRequest><code>onreadystatechange</code></dfn>
   <td><a event><code>readystatechange</code></a>
</table>


<h3 id=states>States</h3>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>readyState</a></code>
 <dd><p>Returns <var>client</var>'s
 <a>state</a>.
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>readyState</code></dfn> getter steps are to return
the value from the table below in the cell of the second column, from the row where the value in the
cell in the first column is <a>this</a>'s <a>state</a>:

<table>
 <tbody><tr>
  <td><i>unsent</i>
  <td><dfn const for=XMLHttpRequest><code>UNSENT</code></dfn> (numeric value 0)
  <td>The object has been constructed.
 <tr>
  <td><i>opened</i>
  <td><dfn const for=XMLHttpRequest><code>OPENED</code></dfn> (numeric value 1)
  <td>The <a method for=XMLHttpRequest lt="open(method, url)"><code>open()</code></a> method has
  been successfully invoked. During this state request headers can be set using
  <a><code>setRequestHeader()</code></a> and the fetch can be initiated using the
  <a><code>send()</code></a> method.
 <tr>
  <td><i>headers received</i>
  <td><dfn const for=XMLHttpRequest><code>HEADERS_RECEIVED</code></dfn> (numeric value 2)
  <td>All redirects (if any) have been followed and all headers of a response have been received.
 <tr>
  <td><i>loading</i>
  <td><dfn const for=XMLHttpRequest><code>LOADING</code></dfn> (numeric value 3)
  <td>The response body is being received.
 <tr>
  <td><i>done</i>
  <td><dfn const for=XMLHttpRequest><code>DONE</code></dfn> (numeric value 4)
  <td>The data transfer has been completed or something went wrong during the transfer (e.g.,
  infinite redirects).
</table>


<h3 id=request>Request</h3>

<p class=note id=event-listeners-and-preflight>Registering one or more event listeners on an
{{XMLHttpRequestUpload}} object will result in a <a>CORS-preflight request</a>. (That is because
registering an event listener causes the <a>upload listener flag</a> to be set, which in turn causes
the <a>use-CORS-preflight flag</a> to be set.)


<h4 id=the-open()-method>The <code>open()</code> method</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a method for=XMLHttpRequest lt="open(method, url)">open(<var>method</var>, <var>url</var> [, <var>async</var> = true [, <var>username</var> = null [, <var>password</var> = null]]])</a></code>

 <dd>
  <p>Sets the <a>request method</a>, <a>request URL</a>, and
  <a>synchronous flag</a>.

  <p>Throws a "{{SyntaxError!!exception}}" {{DOMException}} if either <var>method</var> is not a
  valid method or <var>url</var> cannot be parsed.

  <p>Throws a "{{SecurityError!!exception}}" {{DOMException}} if <var>method</var> is a
  case-insensitive match for `<code>CONNECT</code>`, `<code>TRACE</code>`, or `<code>TRACK</code>`.

  <p>Throws an "{{InvalidAccessError!!exception}}" {{DOMException}} if <var>async</var> is false,
  the <a>current global object</a> is a {{Window}} object, and the
  {{XMLHttpRequest/timeout!!attribute}} attribute is not zero or the {{XMLHttpRequest/responseType}}
  attribute is not the empty string.
</dl>

<p class=critical id=sync-warning>Synchronous {{XMLHttpRequest}} outside of workers is in the
process of being removed from the web platform as it has detrimental effects to the end user's
experience. (This is a long process that takes many years.) Developers must not pass false for the
<var>async</var> argument when the <a>current global object</a> is a {{Window}} object. User agents
are strongly encouraged to warn about such usage in developer tools and may experiment with
<a lt=throw>throwing</a> an "{{InvalidAccessError!!exception}}" {{DOMException}} when it occurs.

<p>The
<dfn id=dom-xmlhttprequest-open method for=XMLHttpRequest><code>open(<var>method</var>, <var>url</var>)</code></dfn>
and
<dfn method for=XMLHttpRequest><code>open(<var>method</var>, <var>url</var>, <var>async</var>, <var>username</var>, <var>password</var>)</code></dfn>
method steps are:

<ol>
 <li><p>If <a>this</a>'s <a>relevant global object</a> is a {{Window}} object and its
 <a>associated <code>Document</code></a> is not <a>fully active</a>, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If <var>method</var> is not a <a for=/>method</a>, then <a>throw</a> a
 "{{SyntaxError!!exception}}" {{DOMException}}.

 <li><p>If <var>method</var> is a <a>forbidden method</a>, then <a>throw</a> a
 "{{SecurityError!!exception}}" {{DOMException}}.

 <li><p><a for=method>Normalize</a> <var>method</var>.

 <li><p>Let <var>parsedURL</var> be the result of
 <a lt="encoding-parse a URL">encoding-parsing a URL</a> <var>url</var>, relative to <a>this</a>'s
 <a>relevant settings object</a>.

 <li><p>If <var>parsedURL</var> is failure, then <a>throw</a> a "{{SyntaxError!!exception}}"
 {{DOMException}}.

 <li>
  <p>If the <var>async</var> argument is omitted, set <var>async</var> to true, and set
  <var>username</var> and <var>password</var> to null.

  <p class=note>Unfortunately legacy content prevents treating the <var>async</var>
  argument being <code>undefined</code> identical from it being omitted.

 <li>
  <p>If <var>parsedURL</var>'s <a for=url>host</a> is non-null, then:

  <ol>
   <li><p>If the <var>username</var> argument is not null,
   <a>set the username</a> given <var>parsedURL</var> and
   <var>username</var>.

   <li><p>If the <var>password</var> argument is not null,
   <a>set the password</a> given <var>parsedURL</var> and
   <var>password</var>.
  </ol>

 <li><p>If <var>async</var> is false, the <a>current global object</a> is a {{Window}} object, and
 either <a>this</a>'s <a>timeout</a> is not 0 or <a>this</a>'s <a>response type</a> is not
 the empty string, then <a>throw</a> an "{{InvalidAccessError!!exception}}" {{DOMException}}.

 <li>
  <p><a for="fetch controller">Terminate</a> <a>this</a>'s
  <a for=XMLHttpRequest>fetch controller</a>.

  <p class=note>A <a for=/>fetch</a> can be ongoing at this point.

 <li>
  <p>Set variables associated with the object as follows:

  <ul>
   <li><p>Unset <a>this</a>'s <a><code>send()</code> flag</a>.
   <li><p>Unset <a>this</a>'s <a>upload listener flag</a>.
   <li><p>Set <a>this</a>'s <a>request method</a> to <var>method</var>.
   <li><p>Set <a>this</a>'s <a>request URL</a> to <var>parsedURL</var>.
   <li><p>Set <a>this</a>'s <a>synchronous flag</a> if <var>async</var> is false; otherwise unset
   <a>this</a>'s <a>synchronous flag</a>.
   <li><p><a for=list>Empty</a> <a>this</a>'s <a>author request headers</a>.
   <li><p>Set <a>this</a>'s <a for=XMLHttpRequest>response</a> to a <a>network error</a>.
   <li><p>Set <a>this</a>'s <a>received bytes</a> to the empty byte sequence.
   <li><p>Set <a>this</a>'s <a>response object</a> to null.
  </ul>

  <p class=note><a>Override MIME type</a> is not overridden here as the
  <code>overrideMimeType()</code> method can be invoked before the <code>open()</code> method.

 <li>
  <p>If <a>this</a>'s <a>state</a> is not <i>opened</i>, then:

  <ol>
   <li><p>Set <a>this</a>'s <a>state</a> to <i>opened</i>.

   <li><p><a>Fire an event</a> named <a event><code>readystatechange</code></a> at <a>this</a>.
  </ol>
</ol>

<p class=note>The reason there are two <code>open()</code> methods defined is due to a limitation of
the editing software used to write the XMLHttpRequest Standard.



<h4 id=the-setrequestheader()-method>The <code>setRequestHeader()</code> method</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a method for=XMLHttpRequest>setRequestHeader(<var>name</var>, <var>value</var>)</a></code>

 <dd>
  <p>Appends a value to an existing request header or adds a new request header.

  <p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if either <a>state</a> is not
  <i>opened</i> or the <a><code>send()</code> flag</a> is set.

  <p>Throws a "{{SyntaxError!!exception}}" {{DOMException}} if <var>name</var> is not a header name
  or if <var>value</var> is not a header value.
</dl>

<p>The
<dfn id=dom-xmlhttprequest-setrequestheader method for=XMLHttpRequest><code>setRequestHeader(<var>name</var>, <var>value</var>)</code></dfn>
method must run these steps:

<ol>
 <li><p>If <a>this</a>'s <a>state</a> is not <i>opened</i>, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If <a>this</a>'s <a><code>send()</code> flag</a> is set, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p><a for="header value">Normalize</a> <var>value</var>.

 <li>
  <p>If <var>name</var> is not a <a>header name</a> or <var>value</var> is not a
  <a>header value</a>, then <a>throw</a> a "{{SyntaxError!!exception}}" {{DOMException}}.

  <p class=note>An empty byte sequence represents an empty <a>header value</a>.

 <li><p>If (<var>name</var>, <var>value</var>) is a <a>forbidden request-header</a>, then return.

 <li><p><a for="header list">Combine</a> (<var>name</var>, <var>value</var>) in <a>this</a>'s
 <a>author request headers</a>.
</ol>

<div id=example-setting-header-twice class=example>
 <p>Some simple code demonstrating what happens when setting the same
 header twice:

 <pre><code class=lang-javascript>
// 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>The <code>timeout</code> getter and setter</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>timeout</a></code>
 <dd>
  <p>Can be set to a time in milliseconds. When set to a non-zero value will cause
  <a for=/>fetching</a> to terminate after the given time has passed. When the time has passed, the
  request has not yet completed, and <a>this</a>'s <a>synchronous flag</a> is unset, a
  <a event><code>timeout</code></a> event will then be <a>dispatched</a>, or a
  "{{TimeoutError!!exception}}" {{DOMException}} will be <a lt=throw>thrown</a> otherwise (for the
  <a><code>send()</code></a> method).

  <p>When set: throws an "{{InvalidAccessError!!exception}}" {{DOMException}} if the
  <a>synchronous flag</a> is set and the <a>current global object</a> is a {{Window}} object.
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>timeout</code></dfn> getter steps are to return
<a>this</a>'s <a>timeout</a>.

<p>The {{XMLHttpRequest/timeout!!attribute}} setter steps are:

<ol>
 <li><p>If the <a>current global object</a> is a {{Window}} object and <a>this</a>'s
 <a>synchronous flag</a> is set, then <a>throw</a> an "{{InvalidAccessError!!exception}}"
 {{DOMException}}.

 <li><p>Set <a>this</a>'s <a>timeout</a> to the given value.
</ol>

<p class=note>This implies that the
{{XMLHttpRequest/timeout!!attribute}} attribute can be
set while <a for=/>fetching</a> is in
progress. If that occurs it will still be measured relative to the start
of <a for=/>fetching</a>.


<h4 id=the-withcredentials-attribute>The <code>withCredentials</code> getter and setter</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>withCredentials</a></code>
 <dd>
  <p>True when <a>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 "{{InvalidStateError!!exception}}" {{DOMException}} if <a>state</a> is not
  <i>unsent</i> or <i>opened</i>, or if the <a><code>send()</code> flag</a> is set.
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>withCredentials</code></dfn> getter steps are to
return <a>this</a>'s <a>cross-origin credentials</a>.

<p>The {{XMLHttpRequest/withCredentials}} setter steps are:

<ol>
 <li><p>If <a>this</a>'s <a>state</a> is not <i>unsent</i> or <i>opened</i>, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If <a>this</a>'s <a><code>send()</code> flag</a> is set, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>Set <a>this</a>'s <a>cross-origin credentials</a> to the given value.
</ol>


<h4 id=the-upload-attribute>The <code>upload</code> getter</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>upload</a></code>
 <dd><p>Returns the associated {{XMLHttpRequestUpload}}
 object. It can be used to gather transmission information when data is
 transferred to a server.
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>upload</code></dfn> getter steps are to return
<a>this</a>'s <a>upload object</a>.


<h4 id=the-send()-method>The <code>send()</code> method</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a method for=XMLHttpRequest lt="send(body)">send([<var>body</var> = null])</a></code>
 <dd>
  <p>Initiates the request. The <var>body</var> argument provides the <a>request body</a>, if any,
  and is ignored if the <a>request method</a> is <code>GET</code> or <code>HEAD</code>.

  <p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if either <a>state</a> is not
  <i>opened</i> or the <a><code>send()</code> flag</a> is set.
</dl>

<p>The <dfn method for=XMLHttpRequest><code>send(<var>body</var>)</code></dfn> method steps are:

<ol>
 <li><p>If <a>this</a>'s <a>state</a> is not <i>opened</i>, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If <a>this</a>'s <a><code>send()</code> flag</a> is set, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If <a>this</a>'s <a>request method</a> is `<code>GET</code>` or `<code>HEAD</code>`, then
 set <var>body</var> to null.

 <li>
  <p>If <var>body</var> is not null, then:

  <ol>
   <li><p>Let <var>extractedContentType</var> be null.

   <li><p>If <var>body</var> is a {{Document}}, then set <a>this</a>'s <a>request body</a> to
   <var>body</var>, <a lt="fragment serializing algorithm">serialized</a>,
   <a for=string>converted</a>, and <a lt="UTF-8 encode">UTF-8 encoded</a>.

   <li>
    <p>Otherwise:

    <ol>
     <li><p>Let <var>bodyWithType</var> be the result of
     <a for=BodyInit lt="safely extract">safely extracting</a> <var>body</var>.

     <li><p>Set <a>this</a>'s <a>request body</a> to <var>bodyWithType</var>'s
     <a for="body with type">body</a>.

     <li><p>Set <var>extractedContentType</var> to <var>bodyWithType</var>'s
     <a for="body with type">type</a>.
    </ol>
   </li>

   <li><p>Let <var>originalAuthorContentType</var> be the result of <a for="header list">getting</a>
   `<code>Content-Type</code>` from <a>this</a>'s <a>author request headers</a>.

   <li>
    <p>If <var>originalAuthorContentType</var> is non-null, then:

    <ol>
     <li>
      <p>If <var>body</var> is a {{Document}} or a {{USVString}}, then:

      <ol>
       <li><p>Let <var>contentTypeRecord</var> be the result of
       <a lt="parse a MIME type from bytes">parsing</a> <var>originalAuthorContentType</var>.

       <li>
        <p>If <var>contentTypeRecord</var> is not failure, <var>contentTypeRecord</var>'s
        <a for="MIME type">parameters</a>["<code>charset</code>"] <a for=map>exists</a>, and
        <a for="MIME type">parameters</a>["<code>charset</code>"] is not an
        <a>ASCII case-insensitive</a> match for "<code>UTF-8</code>", then:

        <ol>
         <li><p><a for=map>Set</a> <var>contentTypeRecord</var>'s
         <a for="MIME type">parameters</a>["<code>charset</code>"] to "<code>UTF-8</code>".

         <li><p>Let <var>newContentTypeSerialized</var> be the result of
         <a lt="serialize a MIME type to bytes">serializing</a> <var>contentTypeRecord</var>.

         <li><p><a for="header list">Set</a> (`<code>Content-Type</code>`,
         <var>newContentTypeSerialized</var>) in <a>this</a>'s <a>author request headers</a>.
        </ol>
      </ol>
    </ol>

   <li>
    <p>Otherwise:

    <ol>
     <li><p>If <var>body</var> is an <a>HTML document</a>, then <a for="header list">set</a>
     (`<code>Content-Type</code>`, `<code>text/html;charset=UTF-8</code>`) in <a>this</a>'s
     <a>author request headers</a>.

     <li><p>Otherwise, if <var>body</var> is an <a>XML document</a>, <a for="header list">set</a>
     (`<code>Content-Type</code>`, `<code>application/xml;charset=UTF-8</code>`) in <a>this</a>'s
     <a>author request headers</a>.

     <li><p>Otherwise, if <var>extractedContentType</var> is not null, <a for="header list">set</a>
     (`<code>Content-Type</code>`, <var>extractedContentType</var>) in <a>this</a>'s
     <a>author request headers</a>.
    </ol>
  </ol>

 <li><p>If one or more event listeners are registered on <a>this</a>'s <a>upload object</a>, then
 set <a>this</a>'s <a>upload listener flag</a>.

 <li>
  <p>Let <var>req</var> be a new
  <a for=/>request</a>, initialized as
  follows:

  <dl>
   <dt><a for=request>method</a>
   <dd><a>This</a>'s <a>request method</a>.
   <dt><a for=request>URL</a>
   <dd><a>This</a>'s <a>request URL</a>.
   <dt><a for=request>header list</a>
   <dd><a>This</a>'s <a>author request headers</a>.
   <dt><a for=request>unsafe-request flag</a>
   <dd>Set.
   <dt><a for=request>body</a>
   <dd><a>This</a>'s <a>request body</a>.
   <dt><a for=request>client</a>
   <dd><a>This</a>'s <a>relevant settings object</a>.
   <dt><a for=request>mode</a>
   <dd>"<code>cors</code>".
   <dt><a for=request>use-CORS-preflight flag</a>
   <dd>Set if <a>this</a>'s <a>upload listener flag</a> is set.
   <dt><a for=request>credentials mode</a>
   <dd>If <a>this</a>'s <a>cross-origin credentials</a> is true, then "<code>include</code>";
   otherwise "<code>same-origin</code>".
   <dt><a for=request>use-URL-credentials flag</a>
   <dd>Set if <a>this</a>'s <a>request URL</a> <a>includes credentials</a>.
   <dt><a for=request>initiator type</a>
   <dd>"<code>xmlhttprequest</code>".
  </dl>

 <li><p>Unset <a>this</a>'s <a>upload complete flag</a>.

 <li><p>Unset <a>this</a>'s <a>timed out flag</a>.

 <li><p>If <var>req</var>'s <a for=request>body</a> is null, then set <a>this</a>'s
 <a>upload complete flag</a>.

 <li><p>Set <a>this</a>'s <a><code>send()</code> flag</a>.

 <li>
  <p>If <a>this</a>'s <a>synchronous flag</a> is unset, then:

  <ol>
   <li><p><a>Fire a progress event</a> named <a event><code>loadstart</code></a> at <a>this</a>
   with 0 and 0.

   <li><p>Let <var>requestBodyTransmitted</var> be 0.

   <li><p>Let <var>requestBodyLength</var> be <var>req</var>'s <a for=request>body</a>'s
   <a for=body>length</a>, if <var>req</var>'s <a for=request>body</a> is non-null; otherwise 0.

   <li><p>Assert: <var>requestBodyLength</var> is an integer.

   <li><p>If <a>this</a>'s <a>upload complete flag</a> is unset and <a>this</a>'s
   <a>upload listener flag</a> is set, then <a>fire a progress event</a> named
   <a event><code>loadstart</code></a> at <a>this</a>'s <a>upload object</a> with
   <var>requestBodyTransmitted</var> and <var>requestBodyLength</var>.

   <li><p>If <a>this</a>'s <a>state</a> is not <i>opened</i> or <a>this</a>'s
   <a><code>send()</code> flag</a> is unset, then return.

   <li>
    <p>Let <var>processRequestBodyChunkLength</var>, given a <var>bytesLength</var>, be these steps:

    <ol>
     <li><p>Increase <var>requestBodyTransmitted</var> by <var>bytesLength</var>.

     <li><p>If not roughly 50ms have passed since these steps were last invoked, then return.

     <li><p>If <a>this</a>'s <a>upload listener flag</a> is set, then <a>fire a progress event</a>
     named <a event><code>progress</code></a> at <a>this</a>'s <a>upload object</a> with
     <var>requestBodyTransmitted</var> and <var>requestBodyLength</var>.
     <!-- upload complete flag can never be set here I hope -->
    </ol>

    <p class=note>These steps are only invoked when new bytes are transmitted.

   <li>
    <p>Let <var>processRequestEndOfBody</var> be these steps:

    <ol>
     <li><p>Set <a>this</a>'s <a>upload complete flag</a>.

     <li><p>If <a>this</a>'s <a>upload listener flag</a> is unset, then return.

     <li><p><a>Fire a progress event</a> named <a event><code>progress</code></a> at <a>this</a>'s
     <a>upload object</a> with <var>requestBodyTransmitted</var> and <var>requestBodyLength</var>.

     <li><p><a>Fire a progress event</a> named <a event><code>load</code></a> at <a>this</a>'s
     <a>upload object</a> with <var>requestBodyTransmitted</var> and <var>requestBodyLength</var>.

     <li><p><a>Fire a progress event</a> named <a event><code>loadend</code></a> at <a>this</a>'s
     <a>upload object</a> with <var>requestBodyTransmitted</var> and <var>requestBodyLength</var>.
    </ol>
    <!-- upload complete flag can never be set here I hope -->

   <li>
    <p>Let <var>processResponse</var>, given a <var>response</var>, be these steps:

    <ol>
     <li><p>Set <a>this</a>'s <a for=XMLHttpRequest>response</a> to <var>response</var>.

     <li><p><a>Handle errors</a> for <a>this</a>.

     <li><p>If <a>this</a>'s <a for=XMLHttpRequest>response</a> is a <a>network error</a>, then
     return.

     <li><p>Set <a>this</a>'s <a>state</a> to <i>headers received</i>.

     <li><p><a>Fire an event</a> named <a event><code>readystatechange</code></a> at <a>this</a>.

     <li><p>If <a>this</a>'s <a>state</a> is not <i>headers received</i>, then return.

     <li><p>If <a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>body</a> is null,
     then run <a>handle response end-of-body</a> for <a>this</a> and return.

     <li><p>Let <var>length</var> be the result of <a for="header list">extracting a length</a> from
     <a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>header list</a>.

     <li><p>If <var>length</var> is not an integer, then set it to 0.

     <li>
      <p>Let <var>processBodyChunk</var> given <var>bytes</var> be these steps:

      <ol>
       <li><p>Append <var>bytes</var> to <a>this</a>'s <a>received bytes</a>.

       <li><p>If not roughly 50ms have passed since these steps were last invoked, then return.

       <li><p>If <a>this</a>'s <a>state</a> is <i>headers received</i>, then set <a>this</a>'s
       <a>state</a> to <i>loading</i>.

       <li>
        <p><a>Fire an event</a> named <a event><code>readystatechange</code></a> at <a>this</a>.

        <p class=note>Web compatibility is the reason <a event><code>readystatechange</code></a>
        fires more often than <a>this</a>'s <a>state</a> changes.

       <li><p><a>Fire a progress event</a> named <a event><code>progress</code></a> at <a>this</a>
       with <a>this</a>'s <a>received bytes</a>'s <a for="byte sequence">length</a> and
       <var>length</var>.
      </ol>

     <li><p>Let <var>processEndOfBody</var> be this step: run <a>handle response end-of-body</a> for
     <a>this</a>.

     <li>
      <p>Let <var>processBodyError</var> be these steps:

      <ol>
       <li><p>Set <a>this</a>'s <a for=XMLHttpRequest>response</a> to a <a for=/>network error</a>.

       <li><p>Run <a>handle errors</a> for <a>this</a>.
      </ol>

     <li><p><a for=body>Incrementally read</a> <a>this</a>'s <a for=XMLHttpRequest>response</a>'s
     <a for=response>body</a>, given <var>processBodyChunk</var>, <var>processEndOfBody</var>,
     <var>processBodyError</var>, and <a>this</a>'s <a>relevant global object</a>.
    </ol>

   <li><p>Set <a>this</a>'s <a for=XMLHttpRequest>fetch controller</a> to the result of
   <a for=/ lt=fetch>fetching</a> <var>req</var> with
   <a for=fetch><i>processRequestBodyChunkLength</i></a> set to
   <var>processRequestBodyChunkLength</var>, <a for=fetch><i>processRequestEndOfBody</i></a> set to
   <var>processRequestEndOfBody</var>, and <a for=fetch><i>processResponse</i></a> set to
   <var>processResponse</var>.

   <li><p>Let <var>now</var> be the present time.
   <!-- Eventually this should use some kind of time standard. -->

   <li>
    <p>Run these steps <a>in parallel</a>:

    <ol>
     <li><p>Wait until either <var>req</var>'s <a for=request>done flag</a> is set or <a>this</a>'s
     <a>timeout</a> is not 0 and <a>this</a>'s <a>timeout</a> milliseconds have passed since
     <var>now</var>.

     <li><p>If <var>req</var>'s <a for=request>done flag</a> is unset, then set <a>this</a>'s
     <a>timed out flag</a> and <a for="fetch controller">terminate</a> <a>this</a>'s
     <a for=XMLHttpRequest>fetch controller</a>.
    </ol>
  </ol>

 <li>
  <p>Otherwise, if <a>this</a>'s <a>synchronous flag</a> is set:

  <ol>
   <li><p>Let <var>processedResponse</var> be false.

   <li>
    <p>Let <var>processResponseConsumeBody</var>, given a <var>response</var> and
    <var>nullOrFailureOrBytes</var>, be these steps:

    <ol>
     <li><p>If <var>nullOrFailureOrBytes</var> is not failure, then set <a>this</a>'s
     <a for=XMLHttpRequest>response</a> to <var>response</var>.

     <li><p>If <var>nullOrFailureOrBytes</var> is a <a for=/>byte sequence</a>, then append
     <var>nullOrFailureOrBytes</var> to <a>this</a>'s <a>received bytes</a>.

     <li><p>Set <var>processedResponse</var> to true.
    </ol>

   <li><p>Set <a>this</a>'s <a for=XMLHttpRequest>fetch controller</a> to the result of
   <a for=/ lt=fetch>fetching</a> <var>req</var> with
   <a for=fetch><i>processResponseConsumeBody</i></a> set to <var>processResponseConsumeBody</var>
   and <a for=fetch><i>useParallelQueue</i></a> set to true.

   <li><p>Let <var>now</var> be the present time.
   <!-- Eventually this should use some kind of time standard. -->

   <li><p><a>Pause</a> until either <var>processedResponse</var> is true or <a>this</a>'s
   <a>timeout</a> is not 0 and <a>this</a>'s <a>timeout</a> milliseconds have passed since
   <var>now</var>.

   <li><p>If <var>processedResponse</var> is false, then set <a>this</a>'s <a>timed out flag</a> and
   <a for="fetch controller">terminate</a> <a>this</a>'s <a for=XMLHttpRequest>fetch controller</a>.

   <li><p><a for="fetch controller">Report timing</a> for <a>this</a>'s
   <a for=XMLHttpRequest>fetch controller</a> given the <a>current global object</a>.

   <li><p>Run <a>handle response end-of-body</a> for <a>this</a>.
  </ol>
</ol>

<p id=handle-response-end-of-file>To <dfn>handle response end-of-body</dfn> for an
{{XMLHttpRequest}} object <var>xhr</var>, run these steps:

<ol>
 <li><p><a>Handle errors</a> for <var>xhr</var>.

 <li><p>If <var>xhr</var>'s <a for=XMLHttpRequest>response</a> is a <a>network error</a>, then
 return.

 <li><p>Let <var>transmitted</var> be <var>xhr</var>'s <a>received bytes</a>'s
 <a for="byte sequence">length</a>.

 <li><p>Let <var>length</var> be the result of <a for="header list">extracting a length</a> from
 <a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>header list</a>.

 <li><p>If <var>length</var> is not an integer, then set it to 0.

 <li><p>If <var>xhr</var>'s <a>synchronous flag</a> is unset, then <a>fire a progress event</a>
 named <a event><code>progress</code></a> at <var>xhr</var> with <var>transmitted</var> and
 <var>length</var>.

 <li><p>Set <var>xhr</var>'s <a>state</a> to <i>done</i>.

 <li><p>Unset <var>xhr</var>'s <a><code>send()</code> flag</a>.

 <li><p><a>Fire an event</a> named <a event><code>readystatechange</code></a> at <var>xhr</var>.

 <li><p><a>Fire a progress event</a> named <a event><code>load</code></a> at <var>xhr</var> with
 <var>transmitted</var> and <var>length</var>.

 <li><p><a>Fire a progress event</a> named <a event><code>loadend</code></a> at <var>xhr</var> with
 <var>transmitted</var> and <var>length</var>.
</ol>

<p>To <dfn>handle errors</dfn> for an {{XMLHttpRequest}} object <var>xhr</var>, run these steps:

<ol>
 <li><p>If <var>xhr</var>'s <a><code>send()</code> flag</a> is unset, then return.

 <li><p>If <var>xhr</var>'s <a>timed out flag</a> is set, then run the <a>request error steps</a>
 for <var>xhr</var>, <a event><code>timeout</code></a>, and "{{TimeoutError!!exception}}"
 {{DOMException}}.

 <li><p>Otherwise, if <var>xhr</var>'s <a for=XMLHttpRequest>response</a>'s
 <a for=response>aborted flag</a> is set, run the <a>request error steps</a> for <var>xhr</var>,
 <a event for=XMLHttpRequest><code>abort</code></a>, and "{{AbortError!!exception}}"
 {{DOMException}}.

 <li><p>Otherwise, if <var>xhr</var>'s <a for=XMLHttpRequest>response</a> is a
 <a for=/>network error</a>, then run the <a>request error steps</a> for <var>xhr</var>,
 {{XMLHttpRequestEventTarget/error}}, and "{{NetworkError!!exception}}" {{DOMException}}.
</ol>

<p>The <dfn>request error steps</dfn> for an {{XMLHttpRequest}} object <var>xhr</var>,
<var>event</var>, and optionally <var>exception</var> are:

<ol>
 <li><p>Set <var>xhr</var>'s <a>state</a> to <i>done</i>.

 <li><p>Unset <var>xhr</var>'s <a><code>send()</code> flag</a>.

 <li><p>Set <var>xhr</var>'s <a for=XMLHttpRequest>response</a> to a <a>network error</a>.

 <li><p>If <var>xhr</var>'s <a>synchronous flag</a> is set, then <a>throw</a> <var>exception</var>.

 <li>
  <p><a>Fire an event</a> named <a event><code>readystatechange</code></a> at <var>xhr</var>.

  <p class=note>At this point it is clear that <var>xhr</var>'s <a>synchronous flag</a> is unset.

 <li>
  <p>If <var>xhr</var>'s <a>upload complete flag</a> is unset, then:

  <ol>
   <li><p>Set <var>xhr</var>'s <a>upload complete flag</a>.

   <li>
    <p>If <var>xhr</var>'s <a>upload listener flag</a> is set, then:

    <ol>
     <li><p><a>Fire a progress event</a> named <var>event</var> at <var>xhr</var>'s
     <a>upload object</a> with 0 and 0.

     <li><p><a>Fire a progress event</a> named <a event><code>loadend</code></a> at <var>xhr</var>'s
     <a>upload object</a> with 0 and 0.
    </ol>
  </ol>

 <li><p><a>Fire a progress event</a> named <var>event</var> at <var>xhr</var> with 0 and 0.

 <li><p><a>Fire a progress event</a> named <a event><code>loadend</code></a> at <var>xhr</var>
 with 0 and 0.
</ol>


<h4 id=the-abort()-method>The <code>abort()</code> method</h4>

  <dl class=domintro>
   <dt><code><var>client</var> . <a method for=XMLHttpRequest>abort()</a></code>
   <dd>Cancels any network activity.
  </dl>

<p>The <dfn method for=XMLHttpRequest><code>abort()</code></dfn> method steps are:

<ol>
 <li><p><a for="fetch controller">Abort</a> <a>this</a>'s
 <a for=XMLHttpRequest>fetch controller</a>.

 <li><p>If <a>this</a>'s <a>state</a> is <i>opened</i> with <a>this</a>'s
 <a><code>send()</code> flag</a> set, <i>headers received</i>, or <i>loading</i>, then run the
 <a>request error steps</a> for <a>this</a> and <a event for=XMLHttpRequest><code>abort</code></a>.

 <li>
  <p>If <a>this</a>'s <a>state</a> is <i>done</i>, then set <a>this</a>'s <a>state</a> to
  <i>unsent</i> and <a>this</a>'s <a for=XMLHttpRequest>response</a> to a <a>network error</a>.

  <p class=note>No <a event><code>readystatechange</code></a> event is dispatched.
</ol>


<h3 id=xmlhttprequest-response>Response</h3>

<h4 id=the-responseurl-attribute>The <code>responseURL</code> getter</h4>

<p>The <dfn attribute for=XMLHttpRequest><code>responseURL</code></dfn> getter steps are to return
the empty string if <a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>URL</a> is
null; otherwise its <a lt="URL serializer">serialization</a> with the <i>exclude fragment flag</i>
set.


<h4 id=the-status-attribute>The <code>status</code> getter</h4>

<p>The <dfn attribute for=XMLHttpRequest><code>status</code></dfn> getter steps are to return
<a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>status</a>.


<h4 id=the-statustext-attribute>The <code>statusText</code> getter</h4>

<p>The <dfn attribute for=XMLHttpRequest><code>statusText</code></dfn> getter steps are to return
<a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a>status message</a>.


<h4 id=the-getresponseheader()-method>The <code>getResponseHeader()</code> method</h4>

<p>The <dfn method for=XMLHttpRequest><code>getResponseHeader(<var>name</var>)</code></dfn> method
steps are to return the result of <a for="header list">getting</a> <var>name</var> from
<a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>header list</a>.

<p class=note>The Fetch Standard filters <a>this</a>'s <a for=XMLHttpRequest>response</a>'s
<a for=response>header list</a>. [[!FETCH]]

<div id=example-getresponseheader class=example>
 <p>For the following script:

 <pre><code class=lang-javascript>
var client = new XMLHttpRequest();
client.open("GET", "unicorns-are-awesome.txt", true);
client.send();
client.onreadystatechange = function() {
  if(this.readyState == this.HEADERS_RECEIVED) {
    print(client.getResponseHeader("Content-Type"));
  }
}</code></pre>

 <p>The <code>print()</code> function will get to process something like:

 <pre><code>
text/plain; charset=UTF-8</code></pre>
</div>


<h4 id=the-getallresponseheaders()-method>The <code>getAllResponseHeaders()</code> method</h4>

<p>A <a>byte sequence</a> <var>a</var> is <dfn>legacy-uppercased-byte less than</dfn> a
<a>byte sequence</a> <var>b</var> if the following steps return true:

<ol>
 <li><p>Let <var>A</var> be <var>a</var>, <a>byte-uppercased</a>.

 <li><p>Let <var>B</var> be <var>b</var>, <a>byte-uppercased</a>.

 <li><p>Return <var>A</var> is <a>byte less than</a> <var>B</var>.
</ol>

<p>The <dfn method for=XMLHttpRequest><code>getAllResponseHeaders()</code></dfn> method steps are:

<ol>
 <li><p>Let <var>output</var> be an empty byte sequence.

 <li><p>Let <var>initialHeaders</var> be the result of running <a>sort and combine</a> with
 <a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>header list</a>.

 <li>
  <p>Let <var>headers</var> be the result of <a for=list>sorting</a> <var>initialHeaders</var> in
  ascending order, with <var>a</var> being less than <var>b</var> if <var>a</var>'s
  <a for=header>name</a> is <a>legacy-uppercased-byte less than</a> <var>b</var>'s
  <a for=header>name</a>.

  <p class=note>Unfortunately, this is needed for compatibility with deployed content.

 <li><p><a for=list>For each</a> <var>header</var> in <var>headers</var>, append <var>header</var>'s
 <a for=header>name</a>, followed by a 0x3A 0x20 byte pair, followed by <var>header</var>'s
 <a for=header>value</a>, followed by a 0x0D 0x0A byte pair, to <var>output</var>.

 <li><p>Return <var>output</var>.
</ol>

<p class=note>The Fetch Standard filters <a>this</a>'s <a for=XMLHttpRequest>response</a>'s
<a for=response>header list</a>. [[!FETCH]]

<div id=example-getresponseheaders class=example>
 <p>For the following script:

 <pre><code class=lang-javascript>
var client = new XMLHttpRequest();
client.open("GET", "narwhals-too.txt", true);
client.send();
client.onreadystatechange = function() {
  if(this.readyState == this.HEADERS_RECEIVED) {
    print(this.getAllResponseHeaders());
  }
}</code></pre>

 <p>The <code>print()</code> function will get to process something
 like:

 <pre><code>
connection: Keep-Alive
content-type: text/plain; charset=utf-8
date: Sun, 24 Oct 2004 04:58:38 GMT
keep-alive: timeout=15, max=99
server: Apache/1.3.31 (Unix)
transfer-encoding: chunked</code></pre>
</div>


<h4 id=response-body>Response body</h4>

<p>To <dfn id=response-mime-type>get a response MIME type</dfn> for an {{XMLHttpRequest}} object
<var>xhr</var>, run these steps:

<ol>
 <li><p>Let <var>mimeType</var> be the result of <a for="header list">extracting a MIME type</a>
 from <var>xhr</var>'s <a for=XMLHttpRequest>response</a>'s <a for=response>header list</a>.

 <li><p>If <var>mimeType</var> is failure, then set <var>mimeType</var> to <code>text/xml</code>.

 <li><p>Return <var>mimeType</var>.
</ol>

<p>To <dfn id=final-mime-type>get a final MIME type</dfn> for an {{XMLHttpRequest}} object
<var>xhr</var>, run these steps:

<ol>
 <li><p>If <var>xhr</var>'s <a>override MIME type</a> is null, return the result of
 <a>get a response MIME type</a> for <var>xhr</var>.

 <li><p>Return <var>xhr</var>'s <a>override MIME type</a>.
</ol>

<p>To <dfn id=final-charset>get a final encoding</dfn> for an {{XMLHttpRequest}} object
<var>xhr</var>, run these steps:

<ol>
 <li><p>Let <var>label</var> be null.

 <li><p>Let <var>responseMIME</var> be the result of <a>get a response MIME type</a> for
 <var>xhr</var>.

 <li><p>If <var>responseMIME</var>'s <a for="MIME type">parameters</a>["<code>charset</code>"]
 <a for=map>exists</a>, then set <var>label</var> to it.

 <li><p>If <var>xhr</var>'s <a>override MIME type</a>'s
 <a for="MIME type">parameters</a>["<code>charset</code>"] <a for=map>exists</a>, then set
 <var>label</var> to it.

 <li><p>If <var>label</var> is null, then return null.

 <li><p>Let <var>encoding</var> be the result of <a>getting an encoding</a> from <var>label</var>.

 <li><p>If <var>encoding</var> is failure, then return null.

 <li><p>Return <var>encoding</var>.
</ol>

<p class=note>The above steps intentionally do not use the <a>get a final MIME type</a> as it would
not be web compatible.

<hr>

<p>To <dfn id=document-response>set a document response</dfn> for an {{XMLHttpRequest}} object
<var>xhr</var>, run these steps:

<ol>
 <li><p>If <var>xhr</var>'s <a for=XMLHttpRequest>response</a>'s <a for=response>body</a> is null,
 then return.

 <li><p>Let <var>finalMIME</var> be the result of <a>get a final MIME type</a> for <var>xhr</var>.

 <li><p>If <var>finalMIME</var> is not an <a>HTML MIME type</a> or an <a>XML MIME type</a>, then
 return.

 <li>
  <p>If <var>xhr</var>'s <a>response type</a> is the empty string and <var>finalMIME</var> is an
  <a>HTML MIME type</a>, then return.

  <p class=note>This is restricted to <var>xhr</var>'s <a>response type</a> being
  "<code>document</code>" in order to prevent breaking legacy content.

 <li>
  <p>If <var>finalMIME</var> is an <a>HTML MIME type</a>, then:

  <ol>
   <li><p>Let <var>charset</var> be the result of <a>get a final encoding</a> for <var>xhr</var>.

   <li><p>If <var>charset</var> is null,
   <a lt="prescan a byte stream to determine its encoding">prescan</a>
   the first 1024 bytes of <var>xhr</var>'s <a>received bytes</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, then set <var>charset</var> to <a>UTF-8</a>.

   <li><p>Let <var>document</var> be a
   <a>document</a> that
   represents the result parsing <var>xhr</var>'s <a>received bytes</a> following the rules set
   forth in the HTML Standard for an HTML parser with scripting disabled and
   <a>a known definite encoding</a> <var>charset</var>.
   [[!HTML]]

   <li><p>Flag <var>document</var> as an
   <a>HTML document</a>.
  </ol>

 <li>
  <p>Otherwise, let <var>document</var> be a <a>document</a> that represents the result of running
  the <a>XML parser</a> with <a>XML scripting support disabled</a> on <var>xhr</var>'s
  <a>received bytes</a>. If that fails (unsupported character encoding,
  namespace well-formedness error, etc.), then return null. [[!HTML]]

  <p class=note>Resources referenced will not be loaded and no associated XSLT will be
  applied. <!-- XXX more formally?! -->

 <li><p>If <var>charset</var> is null, then set <var>charset</var> to <a>UTF-8</a>.
 <!-- can only happen in the XML case -->

 <li><p>Set <var>document</var>'s <a for=Document>encoding</a> to <var>charset</var>.

 <li><p>Set <var>document</var>'s <a for=Document>content type</a> to <var>finalMIME</var>.

 <li><p>Set <var>document</var>'s <a for=Document>URL</a> to <var>xhr</var>'s
 <a for=XMLHttpRequest>response</a>'s <a for=response>URL</a>.

 <li><p>Set <var>document</var>'s <a for=Document>origin</a> to <var>xhr</var>'s
 <a>relevant settings object</a>'s <a for="environment settings object">origin</a>.

 <li><p>Set <var>xhr</var>'s <a>response object</a> to <var>document</var>.
</ol>

<p>To <dfn id="text-response" lt="getting a text response">get a text response</dfn> for an
{{XMLHttpRequest}} object <var>xhr</var>, run these steps:

<ol>
 <li><p>If <var>xhr</var>'s <a for=XMLHttpRequest>response</a>'s <a for=response>body</a> is null,
 then return the empty string.

 <li><p>Let <var>charset</var> be the result of <a>get a final encoding</a> for <var>xhr</var>.

 <li>
  <p>If <var>xhr</var>'s <a>response type</a> is the empty string, <var>charset</var> is null, and
  the result of <a>get a final MIME type</a> for <var>xhr</var> is an <a>XML MIME type</a>, then use
  the rules set forth in the XML specifications to determine the encoding. Let <var>charset</var> be
  the determined encoding. [[!XML]] [[!XML-NAMES]]

  <p class=note>This is restricted to <var>xhr</var>'s <a>response type</a> being the empty string
  to keep the non-legacy <a>response type</a> value "<code>text</code>" simple.

 <li><p>If <var>charset</var> is null, then set <var>charset</var> to <a>UTF-8</a>.

 <li><p>Return the result of running <a>decode</a> on <var>xhr</var>'s <a>received bytes</a> using
 fallback encoding <var>charset</var>.
</ol>

<p class=note>Authors are strongly encouraged to always encode their resources using <a>UTF-8</a>.


<h4 id=the-overridemimetype()-method>The <code>overrideMimeType()</code> method</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a method for=XMLHttpRequest>overrideMimeType(<var>mime</var>)</a></code>
 <dd>
  <p>Acts as if the `<code>Content-Type</code>` header value for a response is <var>mime</var>. (It
  does not change the header.)

  <p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if <a>state</a> is <i>loading</i>
  or <i>done</i>.
</dl>

<p>The <dfn method for=XMLHttpRequest><code>overrideMimeType(<var>mime</var>)</code></dfn> method
steps are:

<ol>
 <li><p>If <a>this</a>'s <a>state</a> is <i>loading</i> or <i>done</i>, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>Set <a>this</a>'s <a>override MIME type</a> to the result of
 <a lt="parse a MIME type">parsing</a> <var>mime</var>.

 <li><p>If <a>this</a>'s <a>override MIME type</a> is failure, then set <a>this</a>'s
 <a>override MIME type</a> to <code>application/octet-stream</code>.
</ol>


<h4 id=the-responsetype-attribute>The <code>responseType</code> getter and setter</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>responseType</a> [ = <var>value</var> ]</code>
 <dd>
  <p>Returns the response type.

  <p>Can be set to change the response type. Values are:
  the empty string (default),
  "<code>arraybuffer</code>",
  "<code>blob</code>",
  "<code>document</code>",
  "<code>json</code>", and
  "<code>text</code>".

  <p>When set: setting to "<code>document</code>" is ignored if the <a>current global object</a> is
  not a {{Window}} object.

  <p>When set: throws an "{{InvalidStateError!!exception}}" {{DOMException}} if <a>state</a> is
  <i>loading</i> or <i>done</i>.

  <p>When set: throws an "{{InvalidAccessError!!exception}}" {{DOMException}} if the
  <a>synchronous flag</a> is set and the <a>current global object</a> is a {{Window}} object.
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>responseType</code></dfn> getter steps are to return
<a>this</a>'s <a>response type</a>.

<p>The {{XMLHttpRequest/responseType}} setter steps are:

<ol>
 <li><p>If the <a>current global object</a> is not a {{Window}} object and the given value is
 "<code>document</code>", then return.

 <li><p>If <a>this</a>'s <a>state</a> is <i>loading</i> or <i>done</i>, then <a>throw</a> an
 "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If the <a>current global object</a> is a {{Window}} object and <a>this</a>'s
 <a>synchronous flag</a> is set, then <a>throw</a> an "{{InvalidAccessError!!exception}}"
 {{DOMException}}.

 <li><p>Set <a>this</a>'s <a>response type</a> to the given value.
</ol>


<h4 id=the-response-attribute>The <code>response</code> getter</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>response</a></code>
 <dd><p>Returns the response body.
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>response</code></dfn> getter steps are:

<ol>
 <li>
  <p>If <a>this</a>'s <a>response type</a> is the empty string or "<code>text</code>", then:

  <ol>
   <li><p>If <a>this</a>'s <a>state</a> is not <i>loading</i> or <i>done</i>, then return
   the empty string.

   <li><p>Return the result of <a>getting a text response</a> for <a>this</a>.
  </ol>

 <li><p>If <a>this</a>'s <a>state</a> is not <i>done</i>, then return null.

 <li><p>If <a>this</a>'s <a>response object</a> is failure, then return null.

 <li><p>If <a>this</a>'s <a>response object</a> is non-null, then return it.

 <li id=arraybuffer-response>
  <p>If <a>this</a>'s <a>response type</a> is "<code>arraybuffer</code>", then set <a>this</a>'s
  <a>response object</a> to a <a for=/>new</a> {{ArrayBuffer}} object representing <a>this</a>'s
  <a>received bytes</a>. If this throws an exception, then set <a>this</a>'s <a>response object</a>
  to failure and return null.

  <p class=note>Allocating an {{ArrayBuffer}} object is not guaranteed to succeed. [[!ECMASCRIPT]]

 <li id=blob-response><p>Otherwise, if <a>this</a>'s <a>response type</a> is "<code>blob</code>",
 set <a>this</a>'s <a>response object</a> to a <a for=/>new</a> {{Blob}} object representing
 <a>this</a>'s <a>received bytes</a> with {{Blob/type}} set to the result of
 <a>get a final MIME type</a> for <a>this</a>.

 <li><p>Otherwise, if <a>this</a>'s <a>response type</a> is "<code>document</code>",
 <a>set a document response</a> for <a>this</a>.

 <li>
  <p>Otherwise:

  <ol>
   <li id=json-response><p>Assert: <a>this</a>'s <a>response type</a> is "<code>json</code>".

   <li><p>If <a>this</a>'s <a for=XMLHttpRequest>response</a>'s <a for=response>body</a> is null,
   then return null.

   <li><p>Let <var>jsonObject</var> be the result of running <a>parse JSON from bytes</a> on
   <a>this</a>'s <a>received bytes</a>. If that threw an exception, then return null.

   <li><p>Set <a>this</a>'s <a>response object</a> to <var>jsonObject</var>.
  </ol>

 <li><p>Return <a>this</a>'s <a>response object</a>.
</ol>


<h4 id=the-responsetext-attribute>The <code>responseText</code> getter</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>responseText</a></code>
 <dd>
  <p>Returns response as text.

  <p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if
  {{XMLHttpRequest/responseType}} is not the empty string or "<code>text</code>".
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>responseText</code></dfn> getter steps are:

<ol>
 <li><p>If <a>this</a>'s <a>response type</a> is not the empty string or "<code>text</code>", then
 <a>throw</a> an "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If <a>this</a>'s <a>state</a> is not <i>loading</i> or <i>done</i>, then return
 the empty string.

 <li><p>Return the result of <a>getting a text response</a> for <a>this</a>.
</ol>


<h4 id=the-responsexml-attribute>The <code>responseXML</code> getter</h4>

<dl class=domintro>
 <dt><code><var>client</var> . <a attribute for=XMLHttpRequest>responseXML</a></code>
 <dd>
  <p>Returns the response as document.

  <p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if
  {{XMLHttpRequest/responseType}} is not the empty string or "<code>document</code>".
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>responseXML</code></dfn> getter steps are:

<ol>
 <li><p>If <a>this</a>'s <a>response type</a> is not the empty string or "<code>document</code>",
 then <a>throw</a> an "{{InvalidStateError!!exception}}" {{DOMException}}.

 <li><p>If <a>this</a>'s <a>state</a> is not <i>done</i>, then return null.

 <li><p>Assert: <a>this</a>'s <a>response object</a> is not failure.

 <li><p>If <a>this</a>'s <a>response object</a> is non-null, then return it.

 <li><p><a>Set a document response</a> for <a>this</a>.

 <li><p>Return <a>this</a>'s <a>response object</a>.
</ol>


<h3 id=events>Events summary</h3>

<p><em>This section is non-normative.</em>

<p>The following events are dispatched on {{XMLHttpRequest}} or {{XMLHttpRequestUpload}} objects:

<table>
 <thead>
  <tr>
   <th>Event name
   <th>Interface
   <th>Dispatched when…
 <tbody>
  <tr>
   <td><dfn id=event-xhr-readystatechange event for=XMLHttpRequest><code>readystatechange</code></dfn>
   <td><code>Event</code>
   <td>The {{XMLHttpRequest/readyState}} attribute changes
   value, except when it changes to <a const for=XMLHttpRequest>UNSENT</a>.
  <tr>
   <td><dfn id=event-xhr-loadstart event for=XMLHttpRequestEventTarget><code>loadstart</code></dfn>
   <td>{{ProgressEvent}}
   <td>The fetch initiates.
  <tr>
   <td><dfn id=event-xhr-progress event for=XMLHttpRequestEventTarget><code>progress</code></dfn>
   <td>{{ProgressEvent}}
   <td>Transmitting data.
  <tr>
   <td><dfn id=event-xhr-abort event for=XMLHttpRequestEventTarget><code>abort</code></dfn>
   <td>{{ProgressEvent}}
   <td>When the fetch has been aborted. For instance, by invoking the
   {{XMLHttpRequest/abort()}} method.
  <tr>
   <td><dfn id=event-xhr-error event for=XMLHttpRequestEventTarget><code>error</code></dfn>
   <td>{{ProgressEvent}}
   <td>The fetch failed.
  <tr>
   <td><dfn id=event-xhr-load event for=XMLHttpRequestEventTarget><code>load</code></dfn>
   <td>{{ProgressEvent}}
   <td>The fetch succeeded.
  <tr>
   <td><dfn id=event-xhr-timeout event for=XMLHttpRequestEventTarget><code>timeout</code></dfn>
   <td>{{ProgressEvent}}
   <td>The author specified timeout has passed before the fetch completed.
  <tr>
   <td><dfn id=event-xhr-loadend event for=XMLHttpRequestEventTarget><code>loadend</code></dfn>
   <td>{{ProgressEvent}}
   <td>The fetch completed (success or failure).
</table>


<h2 id=interface-formdata>Interface {{FormData}}</h2>

<pre class=idl>
typedef (File or USVString) FormDataEntryValue;

[Exposed=(Window,Worker)]
interface FormData {
  constructor(optional HTMLFormElement form, optional HTMLElement? submitter = null);

  undefined append(USVString name, USVString value);
  undefined append(USVString name, Blob blobValue, optional USVString filename);
  undefined delete(USVString name);
  FormDataEntryValue? get(USVString name);
  sequence&lt;FormDataEntryValue> getAll(USVString name);
  boolean has(USVString name);
  undefined set(USVString name, USVString value);
  undefined set(USVString name, Blob blobValue, optional USVString filename);
  iterable&lt;USVString, FormDataEntryValue>;
};
</pre>

<p>Each {{FormData}} object has an associated
<dfn id=concept-formdata-entry-list export for=FormData>entry list</dfn> (an
<a for=/>entry list</a>). It is initially empty.

<p class="note">This section used to define
<a id="concept-formdata-entry" for="entry list">entry</a>, an entry's
<a id="concept-formdata-entry-name" for="entry list/entry">name</a> and
<a id="concept-formdata-entry-value" for="entry list/entry">value</a>, and the
<a id="create-an-entry" for="entry list">create an entry</a> algorithm. These definitions have been
moved to the HTML Standard. [[HTML]]

<p>The
<dfn id=dom-formdata constructor for=FormData lt="FormData(form)"><code>new FormData(<var>form</var>, <var>submitter</var>)</code></dfn>
constructor steps are:

<ol>
 <li>
  <p>If <var>form</var> is given, then:

  <ol>
   <li>
    <p>If <var>submitter</var> is non-null, then:

    <ol>
     <li><p>If <var>submitter</var> is not a <a>submit button</a>, then <a>throw</a> a
     {{TypeError}}.

     <li><p>If <var>submitter</var>'s <a>form owner</a> is not <var>form</var>, then <a>throw</a> a
     "{{NotFoundError!!exception}}" {{DOMException}}.
    </ol>

   <li><p>Let <var>list</var> be the result of <a>constructing the entry list</a> for
   <var>form</var> and <var>submitter</var>.

   <li><p>If <var>list</var> is null, then <a>throw</a> an "{{InvalidStateError!!exception}}"
   {{DOMException}}.

   <li><p>Set <a>this</a>'s <a for=FormData>entry list</a> to <var>list</var>.
  </ol>
</ol>

<p>The
<dfn id=dom-formdata-append method for=FormData><code>append(<var>name</var>, <var>value</var>)</code></dfn>
and
<dfn id=dom-formdata-append-blob method for=FormData><code>append(<var>name</var>, <var>blobValue</var>, <var>filename</var>)</code></dfn>
method steps are:

<ol>
 <li><p>Let <var>value</var> be <var>value</var> if given; otherwise <var>blobValue</var>.

 <li><p>Let <var>entry</var> be the result of <a for="entry list">creating an entry</a> with
 <var>name</var>, <var>value</var>, and <var>filename</var> if given.

 <li><p><a for=list>Append</a> <var>entry</var> to <a>this</a>'s <a for=FormData>entry list</a>.
</ol>

<p class=note>The reason there is an argument named <var>value</var> as well as <var>blobValue</var>
is due to a limitation of the editing software used to write the XMLHttpRequest Standard.

<p>The <dfn id=dom-formdata-delete method for=FormData><code>delete(<var>name</var>)</code></dfn>
method steps are to <a for=list>remove</a> all <a for="entry list">entries</a> whose
<a for="entry list/entry">name</a> is <var>name</var> from <a>this</a>'s
<a for=FormData>entry list</a>.

<p>The <dfn id=dom-formdata-get method for=FormData><code>get(<var>name</var>)</code></dfn> method
steps are:

<ol>
 <li><p>If there is no <a for="entry list">entry</a> whose <a for="entry list/entry">name</a> is
 <var>name</var> in <a>this</a>'s <a for=FormData>entry list</a>, then return null.

 <li><p>Return the <a for="entry list/entry">value</a> of the first <a for="entry list">entry</a>
 whose <a for="entry list/entry">name</a> is <var>name</var> from <a>this</a>'s
 <a for=FormData>entry list</a>.
</ol>

<p>The <dfn id=dom-formdata-getall method for=FormData><code>getAll(<var>name</var>)</code></dfn>
method steps are:

<ol>
 <li><p>If there is no <a for="entry list">entry</a> whose <a for="entry list/entry">name</a> is
 <var>name</var> in <a>this</a>'s <a for=FormData>entry list</a>, then return the empty list.

 <li><p>Return the <a for="entry list/entry">values</a> of all <a for="entry list">entries</a> whose
 <a for="entry list/entry">name</a> is <var>name</var>, in order, from <a>this</a>'s
 <a for=FormData>entry list</a>.
</ol>

<p>The <dfn id=dom-formdata-has method for=FormData><code>has(<var>name</var>)</code></dfn> method
steps are to return true if there is an <a for="entry list">entry</a> whose
<a for="entry list/entry">name</a> is <var>name</var> in <a>this</a>'s
<a for=FormData>entry list</a>; otherwise false.

<p>The
<dfn id=dom-formdata-set method for=FormData><code>set(<var>name</var>, <var>value</var>)</code></dfn>
and
<dfn id=dom-formdata-set-blob method for=FormData><code>set(<var>name</var>, <var>blobValue</var>, <var>filename</var>)</code></dfn>
method steps are:

<ol>
 <li><p>Let <var>value</var> be <var>value</var> if given; otherwise <var>blobValue</var>.

 <li><p>Let <var>entry</var> be the result of <a for="entry list">creating an entry</a> with
 <var>name</var>, <var>value</var>, and <var>filename</var> if given.

 <li><p>If there are <a for="entry list">entries</a> in <a>this</a>'s <a for=FormData>entry list</a>
 whose <a for="entry list/entry">name</a> is <var>name</var>, then <a for=list>replace</a> the first
 such <a for="entry list">entry</a> with <var>entry</var> and <a for=list>remove</a> the others.

 <li><p>Otherwise, <a for=list>append</a> <var>entry</var> to <a>this</a>'s
 <a for=FormData>entry list</a>.
</ol>

<p class=note>The reason there is an argument named <var>value</var> as well as <var>blobValue</var>
is due to a limitation of the editing software used to write the XMLHttpRequest Standard.

<p>The <a>value pairs to iterate over</a> are <a>this</a>'s <a for=FormData>entry list</a>'s
<a for="entry list">entries</a> with the key being the <a for="entry list/entry">name</a> and the
value being the <a for="entry list/entry">value</a>.


<h2 id=interface-progressevent>Interface {{ProgressEvent}}</h2>

<pre class=idl>
[Exposed=(Window,Worker)]
interface ProgressEvent : Event {
  constructor(DOMString type, optional ProgressEventInit eventInitDict = {});

  readonly attribute boolean lengthComputable;
  readonly attribute unsigned long long loaded;
  readonly attribute unsigned long long total;
};

dictionary ProgressEventInit : EventInit {
  boolean lengthComputable = false;
  unsigned long long loaded = 0;
  unsigned long long total = 0;
};
</pre>

<p><a>Events</a> using the {{ProgressEvent}} interface indicate some kind of progression.

<p>The
<dfn attribute for=ProgressEvent><code>lengthComputable</code></dfn>,
<dfn attribute for=ProgressEvent><code>loaded</code></dfn>, and
<dfn attribute for=ProgressEvent><code>total</code></dfn>
getter steps are to return the value they were initialized to.


<h3 id=firing-events-using-the-progressevent-interface>Firing events using the {{ProgressEvent}} interface</h3>

<p>To <dfn id=concept-event-fire-progress>fire a progress event</dfn> named <var>e</var> at
<var>target</var>, given <var>transmitted</var> and <var>length</var>, means to <a>fire an event</a>
named <var>e</var> at <var>target</var>, using {{ProgressEvent}}, with the {{ProgressEvent/loaded}}
attribute initialized to <var>transmitted</var>, and if <var>length</var> is not 0, with the
{{ProgressEvent/lengthComputable}} attribute initialized to true and the {{ProgressEvent/total}}
attribute initialized to <var>length</var>.


<h3 id=suggested-names-for-events-using-the-progressevent-interface>Suggested names for events using the {{ProgressEvent}} interface</h3>

<p><em>This section is non-normative.</em>

<p>The suggested {{Event/type}}
attribute values for use with
<a>events</a> using the
{{ProgressEvent}} interface are summarized in the table below.
Specification editors are free to tune the details to their specific
scenarios, though are strongly encouraged to discuss their usage with the
WHATWG community to ensure input from people familiar with the subject.

<table>
 <tbody>
  <tr>
   <th>{{Event/type}} attribute value
   <th>Description
   <th>Times
   <th>When
  <tr>
   <th><code>loadstart</code>
   <td>Progress has begun.
   <td>Once.
   <td>First.
  <tr>
   <th><a event><code>progress</code></a>
   <td>In progress.
   <td>Once or more.
   <td>After <code>loadstart</code> has been
    <a>dispatched</a>.
  <tr>
   <th><code>error</code>
   <td>Progression failed.
   <td rowspan=4>Zero or once (mutually exclusive).
   <td rowspan=4>After the last <a event><code>progress</code></a> has
    been
    <a>dispatched</a>.
  <tr>
   <th><code>abort</code>
   <td>Progression is terminated.
  <tr>
   <th><code>timeout</code>
   <td>Progression is terminated due to preset time expiring.
  <tr>
   <th><code>load</code>
   <td>Progression is successful.
  <tr>
   <th><code>loadend</code>
   <td>Progress has stopped.
   <td>Once.
   <td>After one of <code>error</code>, <code>abort</code>,
    <code>timeout</code> or <code>load</code> has been
    <a>dispatched</a>.
</table>

<p>The <code>error</code>, <code>abort</code>, <code>timeout</code>, and
<code>load</code> event types are mutually exclusive.

<p>Throughout the web platform the <code>error</code>, <code>abort</code>,
<code>timeout</code> and <code>load</code> event types have
their {{Event/bubbles}} and {{Event/cancelable}}
attributes initialized to false, so it is suggested that for consistency all
<a>events</a> using the
{{ProgressEvent}} interface do the same.


<h3 id=security-considerations>Security considerations</h3>

<p>For cross-origin requests some kind of opt-in, e.g., the
<a>CORS protocol</a> defined in the Fetch Standard, has to be
used before <a>events</a> using the
{{ProgressEvent}} interface are
<a>dispatched</a>
as information (e.g., size) would be revealed that cannot be obtained
otherwise. [[!FETCH]]


<h3 id=example>Example</h3>

<div id=example-progress-events class=example>
 <p>In this example {{XMLHttpRequest}}, combined with concepts
 defined in the sections before, and the HTML
 <{progress}> element are used together to
 display the process of
 <a for=/>fetching</a> a resource.

 <pre><code class=lang-html>
&lt;!DOCTYPE html>
&lt;title>Waiting for Magical Unicorns&lt;/title>
&lt;progress id=p>&lt;/progress>
&lt;script>
  var progressBar = document.getElementById("p"),
      client = new XMLHttpRequest()
  client.open("GET", "magical-unicorns")
  client.onprogress = function(pe) {
    if(pe.lengthComputable) {
      progressBar.max = pe.total
      progressBar.value = pe.loaded
    }
  }
  client.onloadend = function(pe) {
    progressBar.value = pe.loaded
  }
  client.send()
&lt;/script></code></pre>

 <p>Fully working code would of course be more elaborate and deal with more
 scenarios, such as network errors or the end user terminating the request.
</div>



<h2 class=no-num id=acknowledgments>Acknowledgments</h2>

<p>Thanks to
Addison Phillips,
Adrian Bateman,
Ahmed Kamel,
Alan Thomas,
Alex Hopmann,
Alex Vincent,
Alexey Proskuryakov,
Ali Alabbas,
Andrea Marchesini,
Asbjørn Ulsberg,
Bertrand Guay-Paquet,
Björn Höhrmann,
Boris Zbarsky,
Caitlin Potter,
Cameron McCormack,
白丞祐 (Cheng-You Bai),
Chris Marrin,
Christophe Jolif,
Charles McCathieNevile,
Chirag S Kumar<!-- fictionistique; GitHub -->,
Dan Winship,
David Andersson,
David Flanagan,
David Håsäther,
David Levin,
Dean Jackson,
Denis Sureau,
Domenic Denicola,
Dominik Röttsches,
Doug Schepers,
Douglas Livingstone,
Elliott Sprehn,
Elliotte Harold,
Eric Lawrence,
Eric Uhrhane,
Erik Arvidsson,
Erik Dahlström,
Feras Moussa,
Gideon Cohn,
Glenn Adams,
Gorm Haug Eriksen,
Gregory Terzian,
Håkon Wium Lie,
Hallvord R. M. Steen,
Henri Sivonen,
Hiroshige Hayashizaki,
Huub Schaeks,
Ian Clelland,
Ian Davis,
Ian Hickson,
Ivan Herman,
Jake Archibald,
Jared Jacobs,
Jarred Nicholls,
Jeff Walden,
Jens Lindström,
Jim Deegan,
Jim Ley,
Joe Farro,
Jonas Sicking,
Julian Reschke,
송정기 (Jungkee Song),
呂康豪 (Kang-Hao Lu),
Karl Dubost,
Keith Yeung,
田村健人 (Kent TAMURA),
Lachlan Hunt,
Maciej Stachowiak,
Magnus Kristiansen,
Manish Goregaokar,
Marc Hadley,
Marcos Caceres,
Mark Baker,
Mark Birbeck,
Mark Nottingham,
Mark S. Miller,
Martin Hassman,
Mike Pennisi,
Mohamed Zergaoui,
Ms2ger,
Noam Rosenthal,
Odin Hørthe Omdal,
Olli Pettay,
Pawel Glowacki,
Peter Michaux,
Philip Jägenstedt,
Philip Taylor,
Rashika Jaggi,
Robin Berjon,
Rune <span title=Fabulous>F.</span> Halvorsen,
Ruud Steltenpool,
Ryo Onodera,
Sam Sneddon,
Sergiu Dumitriu,
Shivakumar Jagalur Matt,
Sigbjørn Finne,
Simon Pieters,
Stewart Brodie,
Sunava Dutta,
Takeshi Kurosawa,
Takeshi Yoshino,
Thomas Roessler,
Thomas Wisniewski,
Tom Magliery,
Travis Leithead,
triple-underscore,
Yaron Tausky,
Yehuda Katz,
Youenn Fablet, and
Zhenbin Xu
for their contributions to this standard.

<p>Special thanks to the Microsoft employees who first implemented the
{{XMLHttpRequest}} interface, which was first widely deployed by the
Windows Internet Explorer browser.

<p>Special thanks to Ian Hickson for drafting an initial version of this specification in
the HTML Standard (then Web Applications 1.0). [[!HTML]]

<p>Special thanks to the W3C SVG WG for drafting the original
{{ProgressEvent}} class as part of the
<a href=https://www.w3.org/TR/2008/REC-SVGTiny12-20081222/svgudom.html>SVG Micro DOM</a>.

<p>This standard is written by <a href=https://annevankesteren.nl/ lang=nl>Anne van Kesteren</a>
(<a href=https://www.apple.com/>Apple</a>, <a href=mailto:annevk@annevk.nl>annevk@annevk.nl</a>).