W3C

XMLHttpRequest Level 2

W3C Working Draft 20 August 2009

This Version:
http://www.w3.org/TR/2009/WD-XMLHttpRequest2-20090820/
Latest Version:
http://www.w3.org/TR/XMLHttpRequest2/
Latest Editor Version:
http://dev.w3.org/2006/webapi/XMLHttpRequest-2/
Previous Version:
http://www.w3.org/TR/2008/WD-XMLHttpRequest2-20080930/
http://www.w3.org/TR/2008/WD-XMLHttpRequest2-20080225/
Editor:
Anne van Kesteren (Opera Software ASA) <annevk@opera.com>

Abstract

The XMLHttpRequest Level 2 specification enhances the XMLHttpRequest object with new features, such as cross-origin requests, progress events, and the handling of byte streams for both sending and receiving.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the 20 August 2009 Working Draft of XMLHttpRequest Level 2. Please send comments to public-webapps@w3.org (archived) with [XHR2] at the start of the subject line.

In case of conflict with the editor's draft of XMLHttpRequest that draft is likely to be more accurate. Please raise such differences on the public-webapps@w3.org mailing list taking into account that this draft defines a superset.

This document is produced by the Web Applications (WebApps) Working Group. The WebApps Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

1 Introduction

To be written.

2 Conformance Criteria

Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.

The key words must, must not, should and may in this document are to be interpreted as described in RFC 2119. [RFC2119]

This specification defines a single conformance class:

Conforming user agent

A user agent must behave as described in this specification in order to be considered conformant.

User agents may optimize any algorithm given in this specification, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

This specification uses both the terms "conforming user agent(s)" and "user agent(s)" to refer to this product class.

2.1 Dependencies

This specification relies on several underlying specifications.

Cross-Origin Resource Sharing

A conforming user agent must support the algorithms of the Cross-Origin Resource Sharing specification. [CORS]

Document Object Model

A conforming user agent must support at least the subset of the functionality defined in DOM Events and DOM Core that this specification relies upon, such as various exceptions EventTarget. [DOM2Events] [DOM3Core]

HTML 5

A conforming user agent must support at least the subset of the functionality defined in HTML 5 that this specification relies upon, such as the Window object and serializing a Document object. [HTML5]

The Window Object 1.0 draft is not referenced normatively as it appears to be no longer maintained and HTML 5 defines the Window object in more detail. This specification already depends on HTML 5 for other reasons so there is not much additional overhead because of this.

HTTP

A conforming user agent must support some version of the HTTP protocol. Requirements regarding HTTP are made throughout the specification. [RFC2616]

Web IDL

A conforming user agent must also be a conforming implementation of the IDL fragments in this specification, as described in the Web IDL specification. [WebIDL]

XML

A conforming user agent must be a conforming XML processor that reports violations of namespace well-formedness. [XML]

2.2 Terminology

Comparing two strings in a case-sensitive manner means comparing them exactly, codepoint for codepoint.

Comparing two strings in an ASCII case-insensitive manner means comparing them exactly, codepoint for codepoint, except that the characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are considered to also match.

Converting a string to ASCII uppercase means replacing all characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) with the corresponding characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).

The terms and algorithms <fragment>, <scheme>, document base URL, event handler attributes, event handler event type, fully active, Function, innerHTML, origin, resolve a URL, same origin, storage mutex, task, task source, URL, URL character encoding, and queue a task are defined by the HTML 5 specification. [HTML5]

The term entity body is used as described in RFC 2616. Method token is used as described in section 5.1.1 of RFC 2616. field-name and field-value are used as described in section 4.2 of RFC 2616. [RFC2616]

userinfo is used as described in section 3.2.1 of RFC 3986. [RFC3986]

The terms cross-origin request and cross-origin request status are defined by the Cross-Origin Resource Sharing specification. [CORS]

To dispatch a readystatechange event means that an event with the name readystatechange, with no namespace, which does not bubble and is not cancelable, and which uses the Event interface, is to be dispatched at the XMLHttpRequest object.

To dispatch a progress event called e means… [PE]

2.3 Extensibility

Extensions of the API defined by this specification are strongly discouraged. User agents, Working Groups and other interested parties should discuss extensions on a relevant public forum, preferably public-webapps@w3.org.

3 The XMLHttpRequest Interface

The XMLHttpRequest object can be used by scripts to programmatically connect to servers via HTTP.

[NoInterfaceObject]
interface XMLHttpRequestEventTarget : EventTarget {
  // event handler attributes
           attribute Function onloadstart;
           attribute Function onprogress;
           attribute Function onabort;
           attribute Function onerror;
           attribute Function onload;
           attribute Function onloadend;
};

interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
  // for future use
};

[Constructor]
interface XMLHttpRequest : XMLHttpRequestEventTarget {
  // event handler attributes
           attribute Function 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
  void open(DOMString method, DOMString url);
  void open(DOMString method, DOMString url, boolean async);
  void open(DOMString method, DOMString url, boolean async, DOMString? user);
  void open(DOMString method, DOMString url, boolean async, DOMString? user, DOMString? password);
  void setRequestHeader(DOMString header, DOMString value);
           attribute boolean withCredentials;
  readonly attribute XMLHttpRequestUpload upload;
  void send();
  void send(ByteArray data);
  void send(Document data);
  void send([AllowAny] DOMString? data);
  void abort();

  // response
  readonly attribute unsigned short status;
  readonly attribute DOMString statusText;
  DOMString getResponseHeader(DOMString header);
  DOMString getAllResponseHeaders();
  void overrideMimeType(DOMString mime);
  readonly attribute ByteArray responseBody;
  readonly attribute DOMString responseText;
  readonly attribute Document responseXML;
};

3.1 Origin and Base URL

Each XMLHttpRequest object has an associated XMLHttpRequest origin and an XMLHttpRequest base URL.

This specification defines their values when the global object is represented by the Window object. When the XMLHttpRequest object used in other contexts their values will have to be defined as appropriate for that context. That is considered to be out of scope for this specification.


In environments where the global object is represented by the Window object the XMLHttpRequest object has an associated XMLHttpRequest Document which is the Document object associated with the Window object for which the XMLHttpRequest interface object was created.

The XMLHttpRequest Document is used to determine the XMLHttpRequest origin and XMLHttpRequest base URL at a later stage.

3.2 Task Sources

The following task sources are used by this specification:

The XMLHttpRequest event task source
This task source is used for events that are to be asynchronously dispatched.
The XMLHttpRequest networking task source
This task source is used for network activity.

Unless otherwise stated the task source used for all tasks queued in this specification is the XMLHttpRequest event task source.

3.3 Constructors

When the XMLHttpRequest() constructor is invoked, the user agent must return a new XMLHttpRequest object.

3.4 Event Handler Attributes

The following are the event handler attributes (and their corresponding event handler event types) that must be supported on objects implementing an interface that inherits from XMLHttpRequestEventTarget as DOM attributes:

event handler attribute event handler event type
onloadstart loadstart
onprogress progress
onabort abort
onerror error
onload load
onloadend loadend

The following is the event handler attribute (and its corresponding event handler event type) that must be supported as DOM attribute solely by the XMLHttpRequest object:

event handler attribute event handler event type
onreadystatechange readystatechange

3.5 States

The XMLHttpRequest object can be in several states. The readyState attribute, on getting, must return the current state, which must be one of the following values:

UNSENT (numeric value 0)

The object has been constructed.

OPENED (numeric value 1)

The open() method has been successfully invoked. During this state request headers can be set using setRequestHeader() and the request can be made using the send() method.

HEADERS_RECEIVED (numeric value 2)

All HTTP headers have been received. Several response members of the object are now available.

LOADING (numeric value 3)

The response entity body is being received.

DONE (numeric value 4)

The data transfer has been completed or something went wrong during the transfer (e.g. infinite redirects).

The OPENED state has an associated send() flag that indicates whether the send() method has been invoked. It can be either true or false and has an initial value of false.

The DONE state has an associated error flag that indicates some type of network error or abortion. It can be either true or false and has an initial value of false.

3.6 Request

The XMLHttpRequest object holds the following request metadata variables:

The asynchronous flag
A flag that is either true or false that indicates whether the request is done asynchronously.
The request method
The method used in the request.
The request URL
The URL used in the request.
The request username
The username used in the request or null if there is no username.
The request password
The password used in the request or null if there is no password.
The author request headers
A list consisting of HTTP header name/value pairs to be used in the request.
The request entity body
The entity body used in the request.
The credentials flag
Indicates whether a cross-origin request will include cookie and HTTP authentication data and whether cookies can be set. The flag is either true or false. The default value is false.
The upload complete flag
Used to determine whether to send upload progress events. The flag is either true or false.
The upload events flag
Used to determine whether to send upload progress events for cross-origin requests. The flag is either true or false.

The XMLHttpRequest object also has an associated XMLHttpRequestUpload object.

3.6.1 The open() method

When the open(method, url, async, user, password) method is invoked, the user agent must run these steps (unless otherwise indicated):

  1. If the XMLHttpRequest object has an associated XMLHttpRequest Document run these substeps:

    1. If the XMLHttpRequest Document is not fully active raise an INVALID_STATE_ERR exception and terminate the overall set of steps.

    2. Let XMLHttpRequest base URL be the document base URL of the XMLHttpRequest Document.

    3. Let XMLHttpRequest origin be the origin of the XMLHttpRequest Document.

  2. If method does not match the Method token production raise a SYNTAX_ERR exception and terminate these steps.

  3. If method is an ASCII case-insensitive match for CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, TRACE, or TRACK convert method to ASCII uppercase.

    If it does not match any of the above, it is passed through literally, including in the final request.

  4. If method is a case-sensitive match for CONNECT, TRACE, or TRACK the user agent should raise a SECURITY_ERR exception and terminate these steps.

    Allowing these methods poses a security risk. [HTTPVERBSEC]

  5. Let url be a URL.

  6. Let URL character encoding of url be UTF-8.

  7. Resolve url relative to the XMLHttpRequest base URL. If the algorithm returns an error raise a SYNTAX_ERR exception and terminate these steps.

  8. Drop <fragment> from url.

  9. If url contains an unsupported <scheme> raise a NOT_SUPPORTED_ERR and terminate these steps.

  10. If the "user:password" format in the userinfo production is not supported for the relevant scheme and url contains this format raise a SYNTAX_ERR and terminate these steps.

  11. If url contains the "user:password" format let temp user be the user part and temp password be the password part.

  12. If url just contains the "user" format let temp user be the user part.

  13. The previous level of this specification raised a SECURITY_ERR at this place in case of a non same origin stored url. This specification supports non same origin requests and therefore this exception is no longer raised.

  14. Let async be the value of the async argument or true if it was omitted.

  15. If the user argument was not omitted follow these sub steps:

    1. If the syntax of user does not match the syntax specified by the relevant authentication scheme, raise a SYNTAX_ERR exception and terminate the overall set of steps.

    2. If user is null let temp user be null.

    3. Otherwise let temp user be user.

    These steps override anything that may have been set by the url argument.

  16. If the password argument was not omitted follow these sub steps:

    1. If the syntax of password does not match the syntax specified by the relevant authentication scheme, raise a SYNTAX_ERR exception and terminate the overall set of steps.

    2. If password is null let temp password be null.

    3. Otherwise let temp password be password.

    These steps override anything that may have been set by the url argument.

  17. Abort the send() algorithm.

  18. The user agent should cancel any network activity for which the object is responsible.

  19. Set variables associated with the object as follows:

  20. Switch the the state to OPENED.

  21. Dispatch a readystatechange event.

3.6.2 The setRequestHeader() method

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 send() method section.

The setRequestHeader() method appends a value if the HTTP header given as argument is already part of the author request headers list.

For non same origin requests using the HTTP GET method a preflight request is made when headers other than Accept and Accept-Language are set.

When the setRequestHeader(header, value) method is invoked, the user agent must run these steps (unless otherwise indicated):

  1. If the state is not OPENED raise an INVALID_STATE_ERR exception and terminate these steps.

  2. If the send() flag is true raise an INVALID_STATE_ERR exception and terminate these steps.

  3. If header does not match the field-name production raise a SYNTAX_ERR exception and terminate these steps.

  4. If the value argument does not match the field-value production raise a SYNTAX_ERR and terminate these steps.

    The empty string is legal and represents the empty header value.

  5. For security reasons, these steps should be terminated if header is an ASCII case-insensitive match for one of the following headers:

    … or if the start of header is an ASCII case-insensitive match for Proxy- or Sec- (including when header is just Proxy- or Sec-).

    The above headers are not allowed to be set as they are better controlled by the user agent as it knows best what value they should have. Header names starting with Sec- are not allowed to be set to allow new headers to be minted in the future that are guaranteed not to come from XMLHttpRequest. (Older clients would however still be vulnerable as they allow such headers to be set.)

  6. If header is not in the author request headers list append header with its associated value to the list and terminate these steps.

  7. If header is in the author request headers list either use multiple headers, combine the values or use a combination of those (section 4.2, RFC 2616). [RFC2616]

See also the send() method regarding user agent header handling for caching, authentication, proxies, and cookies.

// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send();

// ...would result in the following header being sent:
...
X-Test: one, two
...

3.6.3 The withCredentials attribute

The withCredentials attribute controls the credentials flag.

When the withCredentials attribute is set, the user agent must run these steps:

  1. If the state is not OPENED raise an INVALID_STATE_ERR exception and terminate these steps.

  2. If the send() flag is true raise an INVALID_STATE_ERR exception and terminate these steps.

  3. If the given value is true, set the credentials flag to true. Otherwise, set the credentials flag to false.

On getting, the withCredentials attribute must return true if the credentials flag is true, and false if the credentials flag is false.

3.6.4 The upload attribute

The upload attribute, on getting, must return the associated XMLHttpRequestUpload object.

3.6.5 The send() method

The send(data) method initiates the request and its optional argument provides the entity body for the request. Authors are encouraged to ensure that they have specified the Content-Type header via setRequestHeader() before invoking send() with a non-null data argument.

When invoked, the user agent must run these steps (unless otherwise noted). This algorithm might get aborted if the open() or abort() method is invoked. When the send() algorithm is aborted the user agent must terminate the algorithm after finishing the step it is on.

The send() algorithm can only be aborted when async is true (i.e., the request is done asynchronously) and only after the method call has returned.

  1. If the state is not OPENED raise an INVALID_STATE_ERR exception and terminate these steps.

  2. If the send() flag is true raise an INVALID_STATE_ERR exception and terminate these steps.

  3. If stored method is GET or HEAD act as if the data argument is null.

    If the data argument has not been omitted and is not null use it for the entity body observing the following rules:

    data is a ByteArray

    This will be done in terms of the File API in due course.

    Use data literally for transmission.

    data is a DOMString

    Encode data using UTF-8 for transmission.

    data is a Document

    Let tempdata be the result of getting the innerHTML attribute on the data object and encode it using data.inputEncoding or UTF-8 if data.inputEncoding is null. Re-raise any exception this raises.

    If the document cannot be serialized an INVALID_STATE_ERR exception is raised.

    Let data be tempdata.

    If no Content-Type header has been set using setRequestHeader() set a Content-Type request header with a value of application/xml;charset=charset where charset is the encoding used to encode the document.

    Subsequent changes to the Document have no effect on what is submitted.

    If the data argument has been omitted, or is null, no entity body is used in the request.

  4. If the asynchronous flag is false release the storage mutex.

  5. If the asynchronous flag is true and one or more event listeners are registered on the XMLHttpRequestUpload object set the upload events flag to true. Otherwise, set the upload events flag to false.

  6. Set the error flag to false.

  7. Set the upload complete flag to true if there is no request entity body or if the request entity body is empty. Otherwise, set the upload complete flag to false.

  8. If the asynchronous flag is true run these substeps:

    1. Set the send() flag to true.

    2. Dispatch a readystatechange event.

      The state does not change. The event is dispatched for historical reasons.

    3. Dispatch a progress event called loadstart.

    4. If the upload complete flag is false dispatch a progress event called loadstart on the XMLHttpRequestUpload object.

    5. Return the send() method call, but continue running the steps in this algorithm.

  9. If the XMLHttpRequest origin and the request URL are same origin

    These are the same-origin request steps.

    Make a request to request URL, using HTTP method request method, user request username (if non-null) and password request password (if non-null), taking into account the request entity body, list of author request headers and the rules listed at the end of this section.

    If there are cookies to be set, run the cookie steps.

    If the asynchronous flag is false

    While making the request also follow the same-origin request event rules.

    The send() method call will now be returned by virtue of this algorithm ending.

    If the asynchronous flag is true

    Make progress notifications.

    Make upload progress notifications.

    While processing the request, as data becomes available and when the user interferes with the request, queue tasks to follow the same-origin request event rules using the XMLHttpRequest networking task source as task source.

    Otherwise

    These are the cross-origin request steps.

    Make a cross-origin request, passing these as parameters:

    request URL
    The request URL.
    request method
    The request method.
    custom request headers
    The list of author request headers.
    request entity body
    The request entity body.
    source origin
    The XMLHttpRequest origin.
    credentials flag
    The credentials flag.
    force preflight flag
    The upload events flag.

    Request username and request password are always ignored as part of a cross-origin request; including them would allow a site to perform a distributed password search. However, user agents will include credentials in the request (if the user has any) as required elsewhere.

    If there are cookies to be set and the credentials flag is true, run the cookie steps.

    If the asynchronous flag is false

    While making the request also follow the cross-origin request event rules.

    The send() method call will now be returned by virtue of this algorithm ending.

    If the asynchronous flag is true

    While processing the request, as data becomes available and when the end user interferes with the request, queue tasks to follow the cross-origin request event rules using the XMLHttpRequest networking task source as task source.


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 Request-Line and send Proxy-Authorization headers as specified.

If the user agent supports HTTP Authentication and Authorization is not in the list of author request headers, it should consider requests originating from the XMLHttpRequest object to be part of the protection space that includes the accessed URIs and send Authorization headers and handle 401 Unauthorized requests appropriately. If authentication fails, and request username and request password are both null, user agents should prompt the end user for credentials. If authentication fails, and request username and request password are provided, user agents must not prompt the end user for credentials. [RFC2617]

End users are not prompted if credentials are provided through the open() API so that authors can implement their own user interface. They are also not prompted for cross-site requests.

If the user agent supports HTTP State Management it should persist, discard and send cookies (as received in the Set-Cookie and Set-Cookie2 response headers, and sent in the Cookie header) as applicable. [COOKIES]

If the user agent implements a HTTP cache it should respect Cache-Control request headers set by the setRequestHeader() (e.g., Cache-Control: no-cache bypasses the cache). It must not send Cache-Control or Pragma request headers automatically unless the end user explicitly requests such behavior (e.g., by (force-)reloading the page).

For 304 Not Modified responses that are a result of a user agent generated conditional request the user agent must act as if the server gave a 200 OK response with the appropriate content. The user agent must allow setRequestHeader() to override automatic cache validation by setting request headers (e.g., If-None-Match, If-Modified-Since), in which case 304 Not Modified responses must be passed through. [RFC2616]

If the user agent implements server-driven content-negotiation it should set Accept-Encoding and Accept-Charset headers as appropriate. Unless set through setRequestHeader() user agents should set the Accept and Accept-Language headers as well. If Accept is set by the user agent it must have the value */*. Responses must have the content-encodings automatically decoded. [RFC2616]

Besides the author request headers user agents should not include additional request headers other than those mentioned above or other than those authors are not allowed to set using setRequestHeader(). This ensures that authors have a reasonably predictable API.

3.6.6 Infrastructure for the send() method

The cookie steps are as follows:

  1. Wait until ownership of the storage mutex can be taken.

  2. Take ownership of the storage mutex.

  3. Update the cookies. [COOKIES]

  4. Release the storage mutex so that it is once again free.


The same-origin request event rules are as follows:

If the response is an HTTP redirect

If the redirect violates security or infinite loop precautions or the scheme is not supported this is a network error.

Otherwise, run these steps:

  1. Set the request URL to the URL conveyed by the Location header.

  2. If the XMLHttpRequest origin and request URL are same origin follow the redirect while observing the same-origin request event rules.

  3. Otherwise, follow the cross-origin request steps and terminate the steps for this algorithm.

HTTP places requirements on the user agent regarding the preservation of the request method and request entity body during redirects, and also requires end users to be notified of certain kinds of automatic redirections.

If the end user cancels the download

This is an abort error.

In case of network errors

In case of DNS errors, TLS negotiation failure, or other type of network errors, this is a network error. Do not request any kind of end user interaction.

This does not include HTTP responses that indicate some type of error, such as HTTP status code 410.

Once all HTTP headers have been received and the asynchronous flag is true

Switch to the HEADERS_RECEIVED state.

Once the first byte (or more) of the response entity body has been received and the asynchronous flag is true
If there is no response entity body and the asynchronous flag is true

Switch to the LOADING state.

Once the whole response entity body has been received
If there is no response entity body and the asynchronous flag is false or the state is LOADING

Switch to the DONE state.


The cross-origin request event rules are as follows:

If the cross-origin request status is preflight complete

Make upload progress notifications.

If the cross-origin request status is network error

This is a network error.

If the cross-origin request status is abort error

This is an abort error.

Once all HTTP headers have been received, the cross-origin request status is success, and the asynchronous flag is true

Switch to the HEADERS_RECEIVED state.

Make progress notifications.

Once the first byte (or more) of the response entity body has been received, the cross-origin request status is success, and the asynchronous flag is true
If there is no response entity body, the cross-origin request status is success, and the asynchronous flag is true

Switch to the LOADING state.

Once the whole response entity body has been received and the cross-origin request status is success
If there is no response entity body, the cross-origin request status is success, and the asynchronous flag is false or the state is LOADING

Switch to the DONE state.


When something is said to be a network error run these steps:

  1. Set the response entity body to null.

  2. Set the the error flag to true.

  3. Empty the list of author request headers.

  4. Switch the state to DONE.

  5. If the asynchronous flag is false raise a NETWORK_ERR exception and terminate the overall set of steps.

  6. Queue a task to dispatch a readystatechange event.

    At this point it is clear that the asynchronous flag is true.

  7. Queue a task to dispatch a progress event called error.

  8. Queue a task to dispatch a progress event called loadend.

  9. If the upload complete flag is false, follow these substeps:

    1. Set the upload complete flag to true.

    2. Queue a task to dispatch a progress event called error on the XMLHttpRequestUpload object.

    3. Queue a task to dispatch a progress event called loadend on the XMLHttpRequestUpload object.

  10. Terminate the overall algorithm.


When something is said to be an abort error run these steps:

  1. Set the response entity body to null.

  2. Set the the error flag to true.

  3. Empty the list of author request headers.

  4. Switch the state to DONE.

  5. If the asynchronous flag is false raise a ABORT_ERR exception and terminate the overall set of steps.

  6. Queue a task to dispatch a readystatechange event.

    At this point it is clear that the asynchronous flag is true.

  7. Queue a task to dispatch a progress event called abort.

  8. Queue a task to dispatch a progress event called loadend.

  9. If the upload complete flag is false, follow these substeps:

    1. Set the upload complete flag to true.

    2. Queue a task to dispatch a progress event called abort on the XMLHttpRequestUpload object.

    3. Queue a task to dispatch a progress event called loadend on the XMLHttpRequestUpload object.

  10. Terminate the overall algorithm.


When it is said to switch to the HEADERS_RECEIVED state run these steps:

  1. Switch the state to HEADERS_RECEIVED.

  2. Queue a task to dispatch a readystatechange event.


When it is said to switch to the LOADING state run these steps:

  1. Switch the state to LOADING.

  2. Queue a task to dispatch a readystatechange event.


When it is said to switch to the DONE state run these steps:

  1. Switch the state to DONE.

  2. If the asynchronous flag is false run these substeps:

    1. Dispatch a readystatechange event.

    2. Dispatch a progress event called load.

    3. Dispatch a progress event called loadend.

  3. If the asynchronous flag is true run these substeps:

    1. Queue a task to dispatch a readystatechange event.

    2. Queue a task to dispatch a progress event called load.

    3. Queue a task to dispatch a progress event called loadend.


When it is said to make progress notifications, while the download is progressing, queue a task to dispatch a progress event called progress about every 50ms or for every byte received, whichever is least frequent.


When it is said to make upload progress notifications run these steps:

3.6.7 The abort() method

When the abort() method is invoked, the user agent must run these steps (unless otherwise noted):

  1. Abort the send() algorithm.

  2. The user agent should cancel any network activity for which the object is responsible.

  3. Set the response entity body to null.

  4. Set the error flag to true.

  5. Empty the list of author request headers.

  6. If the state is UNSENT, OPENED with the send() flag being false, or DONE go to the next step.

    Otherwise run these substeps:

    1. Switch the state to DONE.

    2. Set the send() flag to false.

    3. Dispatch a readystatechange event.

    4. Dispatch a progress event called abort.

    5. Dispatch a progress event called loadend.

    6. If the upload complete flag is false run these substeps:

      1. Set the upload complete flag to true.

      2. Dispatch a progress event called abort on the XMLHttpRequestUpload object.

      3. Dispatch a progress event called loadend on the XMLHttpRequestUpload object.

  7. Switch the state to UNSENT.

    No readystatechange event is dispatched.

3.7 Response

3.7.1 The status attribute

The status attribute must return the result of running these steps:

  1. If the state is UNSENT or OPENED raise an INVALID_STATE_ERR exception and terminate these steps.

  2. If the error flag is true return 0 and terminate these steps.

  3. Return the HTTP status code.

3.7.2 The statusText attribute

The statusText attribute must return the result of running these steps:

  1. If the state is UNSENT or OPENED raise an INVALID_STATE_ERR exception and terminate these steps.

  2. If the error flag is true return the empty string and terminate these steps.

  3. Return the HTTP status text.

3.7.3 The getResponseHeader() method

When the getResponseHeader(header) is invoked, the user agent must run these steps:

  1. If the state is UNSENT or OPENED raise an INVALID_STATE_ERR exception and terminate these steps.

  2. If header does not match the field-name production return null and terminate these steps.

  3. If the error flag is true return null and terminate these steps.

  4. If header is an ASCII case-insensitive match for Set-Cookie or Set-Cookie2 return null and terminate these steps.

  5. If header is an ASCII 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.

  6. If header is an ASCII case-insensitive match for a single HTTP response header, return the value of that header and terminate these steps.

  7. Return null.

The Cross-Origin Resource Sharing specification filters the headers that are exposed by getResponseHeader() for non same-origin requests. [CORS]

// The following script:
var client = new XMLHttpRequest();
client.open("GET", "test.txt", true);
client.send();
client.onreadystatechange = function() {
 if(this.readyState == 2) {
  print(client.getResponseHeader("Content-Type"));
 }
}

// ...should output something similar to the following text:
Content-Type: text/plain; charset=utf-8

3.7.4 The getAllResponseHeaders() method

When the getAllResponseHeaders() method is invoked, the user agent must run the following steps:

  1. If the state is UNSENT or OPENED raise an INVALID_STATE_ERR exception and terminate these steps.

  2. If the error flag is true return the empty string and terminate these steps.

  3. Return all the HTTP headers, excluding headers that are an ASCII case-insensitive match for Set-Cookie or Set-Cookie2, 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.

// The following script:
var client = new XMLHttpRequest();
client.open("GET", "test.txt", true);
client.send();
client.onreadystatechange = function() {
 if(this.readyState == 2) {
  print(this.getAllResponseHeaders());
 }
}

// ...should output something similar to the following text:
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

The Cross-Origin Resource Sharing specification filters the headers that are exposed by getAllResponseHeaders() for non same-origin requests. [CORS]

3.7.5 Response Entity Body

The response MIME type is the MIME type the Content-Type header contains without any parameters or null if the header could not be parsed properly or was omitted. The override MIME type is initially null and can get a value if overrideMimeType() is invoked. Final MIME type is the override MIME type unless that is null in which case it is the response MIME type.

The response charset is the value of the charset parameter of the Content-Type header or null if there was no charset parameter or if the header could not be parsed properly or was omitted. The override charset is initially null and can get a value if overrideMimeType() is invoked. Final charset is the override charset unless that is null in which case it is the response charset.

The response entity body is the fragment of the entity body received so far (LOADING state) or the complete entity body (DONE state). If there is no entity body the response entity body is null.

The text response entity body is a DOMString representing the response entity body. The text response entity body is the return value of the following algorithm:

  1. If the response entity body is null return the empty string and terminate these steps.

  2. Let charset be the final charset.

  3. Let mime be the final MIME type.

  4. If charset is null and mime is null, text/xml, application/xml or ends in +xml use the rules set forth in the XML specifications to determine the character encoding. Let charset be the determined character encoding.

  5. If charset is null and mime is text/html follow the rules set forth in the HTML specification to determine the character encoding. Let charset be the determined character encoding. [HTML5]

  6. If charset is null then, for each of the rows in the following table, starting with the first one and going down, if the first bytes of bytes match the bytes given in the first column, then let charset be the encoding given in the cell in the second column of that row. If there is no match charset remains null.

    Bytes in Hexadecimal Description
    FE FF UTF-16BE BOM
    FF FE UTF-16LE BOM
    EF BB BF UTF-8 BOM
  7. If charset is null let charset be UTF-8.

  8. Return the result of decoding the response entity body using charset. Replace bytes or sequences of bytes that are not valid accordng to the charset with a single U+FFFD character.

Authors are encouraged to encode their resources using UTF-8.

The document response entity body is either a Document representing the response entity body or null. The document response entity body is the return value of the following algorithm:

  1. If the response entity body is null terminate these steps and return null.

  2. If final MIME type is not null, text/html, text/xml, application/xml, and does not end in +xml terminate these steps and return null.

  3. If final MIME type is text/html let document be an object implementing the Document interface that represents the response entity body parsed following the rules set forth in the HTML specification for an HTML parser with scripting disabled and then terminate this algorithm. [HTML5]

  4. Otherwise, let document be an object implementing the Document interface that represents the result of parsing the response entity body into a document tree following the rules from the XML specifications. If this fails (unsupported character encoding, namespace well-formedness error et cetera) terminate these steps return null. [XML]

    Scripts in the resulting document tree will not be executed, resources referenced will not be loaded and no associated XSLT will be applied.

  5. Ensure that the cookie attribute on document returns the empty string if the same origin flag is false.

  6. Return document.

3.7.6 The overrideMimeType() method

When the overrideMimeType(mime) method is invoked, the user agent must run the following steps:

  1. If parsing mime analogously to the value of the Content-Type headers fails raise a SYNTAX_ERR exception and abort this algorithm.

  2. If a MIME type (without any parameters) is successfully parsed set override MIME type to that MIME type.

  3. If a charset parameter is successfully parsed set override charset to its value.

3.7.7 The responseBody attribute

This will be done in terms of the File API in due course.

The responseBody attribute, on getting, must return the result of running the following steps:

  1. If the state is not LOADING or DONE raise an INVALID_STATE_ERR exception and terminate these steps.

  2. Return a ByteArray object representing the response entity body or return null if the response entity body is null.

3.7.8 The responseText attribute

The responseText attribute, on getting, must return the result of running the following steps:

  1. If the state is not LOADING or DONE return the empty string and terminate these steps.

  2. Return the text response entity body.

3.7.9 The responseXML attribute

The responseXML attribute, on getting, must return the result of running the following steps:

  1. If the state is not DONE return null and terminate these steps.

  2. Return the document response entity body.

The responseXML attribute has XML in its name for historical reasons. It also returns documents created using an HTML parser.

3.8 Events summary

The following events are dispatched on XMLHttpRequest and/or XMLHttpRequestUpload objects:

Event name Interface Dispatched when…
readystatechange Event The readyState attribute changes at some seemingly arbitrary times for historical reasons.
loadstart ProgressEvent When the request starts.
progress ProgressEvent While loading and sending data.
abort ProgressEvent When the request has been aborted. For instance, by invoking the abort() method.
error ProgressEvent When the request has failed.
load ProgressEvent When the request has successfully completed.
loadend ProgressEvent When the request has completed (either in success or failure).

3.9 Exceptions

Several algorithms in this specification may result in an exception being thrown. These exceptions are all part of the group ExceptionCode and use the DOMException object, which is defined in DOM Level 3 Core. In addition this specification extends the ExceptionCode group with several new constants as indicated below. [DOM3Core]

Thus, exceptions used by this specification and not defined in this section are defined by DOM Level 3 Core.

const unsigned short SECURITY_ERR = 18;
const unsigned short NETWORK_ERR = 19;
const unsigned short ABORT_ERR = 20;

The SECURITY_ERR exception is raised if an attempt is made to perform an operation or access some data in a way that would be a security risk or a violation of the user agent's security policy.

The NETWORK_ERR exception is raised when a network error occurs in synchronous requests.

The ABORT_ERR exception is raised when the user aborts a request in synchronous requests.

These exceptions might be folded into an update of DOM Level 3 Core in due course, as they are appropriate for other API specifications as well.

Differences from XMLHttpRequest

XMLHttpRequest Level 2 adds the following new features:

References

Unless marked "Non-normative" these references are normative.

[COOKIES]
HTTP State Management Mechanism, D. Kristol, L. Montulli, editors. IETF, February 1997.
HTTP State Management Mechanism, D. Kristol, L. Montulli, editors. IETF, October 2000.
[CORS]
Cross-Origin Resource Sharing (work in progress), A. van Kesteren, editor. W3C, 2009.
[DOM2Events]
Document Object Model (DOM) Level 2 Events Specification, T. Pixley, editor. W3C, November 2000.
[DOM3Core]
Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. W3C, April 2004.
[ECMAScript]
ECMAScript Language Specification, Third Edition. ECMA, December 1999.
[HTML5]
HTML 5 (work in progress), I. Hickson, D. Hyatt, editors. W3C, 2008.
HTML 5 (work in progress), I. Hickson, editor. WHATWG, 2008.
[HTTPVERBSEC]
(Non-normative) Multiple vendors' web servers enable HTTP TRACE method by default, US-CERT.
(Non-normative) Microsoft Internet Information Server (IIS) vulnerable to cross-site scripting via HTTP TRACK method, US-CERT.
(Non-normative) HTTP proxy default configurations allow arbitrary TCP connections, US-CERT.
[PE]
Progress Events 1.0 (work in progress), C. McCathieNeville, editor. W3C, 2007.
[RFC2046]
Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, N. Freed, N. Borenstein, editors. IETF, November 1996.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
[RFC2616]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, editors. IETF, June 1999.
[RFC2617]
HTTP Authentication: Basic and Digest Access Authentication, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart, editors. IETF, June 1999.
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, editors. IETF, January 2005.
[RFC3987]
Internationalized Resource Identifiers (IRIs), M. Duerst, M. Suignard, editors. IETF, January 2005. L. Masinter, editors. IETF, January 2005.
[WebIDL]
Web IDL (work in progress), C. McCormack, editor. W3C, 2008.
[XML]
Extensible Markup Language (XML) 1.0 (Fifth Edition), T. Bray, J. Paoli, C. Sperberg-McQueen, E. Maler, F. Yergeau, editors. W3C, November 2008.
Namespaces in XML (Second Edition), T. Bray, D. Hollander, A. Layman, R. Tobin, editors. W3C, August 2006.

Acknowledgments

The editor would like to thank Alexey Proskuryakov, Cameron McCormack, David Andersson, David Levin, Elliotte Harold, Lachlan Hunt, Ian Hickson, Jonas Sicking, Maciej Stachowiak, Martin Hassman, Mohamed Zergaoui, Olli Pettay, and Rune Halvorsen for their contributions to this specification.

Thanks also to all who have contributed to the XMLHttpRequest specification.

Thanks also to all those who have helped to improve this specification by sending suggestions and corrections. (Please, keep bugging us with your issues!)