The XMLHttpRequest Object

When invoked, this method MUST cancel any network activity for which the object is responsible and reset the object.

No Parameters

No Return Value

No Exceptions

If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), it MUST return null. Otherwise, it MUST return all the HTTP headers, as a single string, with each header line separated by a CR (U+000D) LF (U+000A) pair. The status line MUST not be included.

// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'test.txt', false);
client.send();
print(client.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

No Parameters

Return Value

A single string consisting of all HTTP headers. See prose for details.

No Exceptions

If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), it MUST return the empty string. Otherwise, it MUST represent the value of the given HTTP header in the data received so far for the last request sent, as a single string. If more than one header of the given name was received, then the values MUST be concatenated, separated from each other by an U+002C COMMA followed by an U+0020 SPACE. If no headers of that name were received, then it MUST return the empty string. Header names MUST be compared case-insensitively to the method its argument (header).

// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'test.txt', false);
client.send();
print(client.getResponseHeader('Content-Type'));
// ...should output something similar to the following text:
Content-Type: text/plain; charset=utf-8

Parameters

header of type DOMString

Name of the HTTP header.

Return Value

Value of the given HTTP header.

No Exceptions

Calling this method MUST initialize the object by remembering the method, uri, async (defaulting to true if omitted), user (defaulting to null if omitted), and password (defaulting to null if omitted) arguments, setting the readyState attribute to 1 (Open), resetting the responseText, responseXML, status, and statusText attributes to their initial values, and resetting the list of request headers.

Same-origin security restrictions SHOULD apply.

If the URI given to this method contains userinfo ([RFC3986], section 3.2.1) then the user name and password specified MUST be used if the user and password arguments are omitted. If the arguments are not omitted, they take precedence, even if they are null. The usage of userinfo is discouraged MAY not work in implementations.

If open() is called when readyState is 4 (Loaded) the entire object MUST be reset.

Parameters

method of type DOMString

A valid HTTP method name. The GET, POST, PUT, DELETE and HEAD values MUST be supported [RFC2616].

uri of type DOMString

A URI, which MUST be resolved to an absolute URI using the cached base URI.

async of type boolean, optional

Whether or not script execution can continue.

user of type DOMString, optional

Username.

password of type DOMString, optional

Password.

No Return Value

No Exceptions

If the readyState attribute has a value other than 1 (Open), an exception MUST be raised. Otherwise, the readyState attribute MUST be set to 2 (Sent) and a request to uri using method method is sent. If the async flag is set to false, then the method MUST not return until the request has completed. Otherwise, it MUST return immediately. (See: open().)

If data passed to the send() method it MUST be used for the entity body following these rules:

• If data is a DOMString, it MUST be encoded as UTF-8 for transmission.
• If the data is a Document, it MUST be serialized using the encoding given by data.xmlEncoding, if specified and supported, or UTF-8 otherwise [DOM3].
• If data is not a DOMString or a Document the host language its stringification mechanisms MUST be used on the argument that was passed and the result MUST be encoded as UTF-8 for transmission.

Invoking send without the data argument MUST give the same result as if it was invoked with null as argument. Authors SHOULD specify the Content-Type header via setRequestHeader before invoking send with an argument.

If the response is an HTTP redirect (status code 301, 302, 303 or 307), then it MUST be transparently followed (unless it violates security, infinite loop precautions or the scheme isn't supported). Note that HTTP [RFC2616] places requirements on UAs regarding the preservation of the request method during redirects, and also requires users to be notified of certain kinds of automatic redirections.

If the UA allows the specification of 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 UA supports HTTP Authentication [RFC2617] it SHOULD consider requests originating from this object to be part of the protection space that includes the accessed URIs and send Authorization headers and handle 401 Unauthorised requests appropriately. if authentication fails, UAs should prompt the users for credentials.

If the UA supports HTTP State Mangement [RFC2109][RFC2965] 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.

If the UA implements a HTTP cache [RFC2616] it should respect Cache-Control request headers set by the author (e.g., Cache-Control: no-cache bypasses the cache). It MUST NOT send Cache-Control or Pragma request headers automatically unless the user explicitly requests such behaviour (e.g., by (force-)reloading the page). 304 Not Modified responses that are a result of a UA-generated conditional request MUST be presented as 200 OK responses with the appropriate content. Such UAs MUST allow authors 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.

If the UA implements server-driven content-negotiation [RFC2616], it SHOULD set Accept-Language, Accept-Encoding and Accept-Charset headers as appropriate; it MUST NOT automatically set the Accept header. Responses to such requests MUST have content-codings automatically removed.

Immediately before receiving the message body (if any), the readyState attribute MUST be set to to 3 (Receiving). When the request has completed loading, the readyState attribute MUST be set to 4 (Loaded). In case of a HEAD request readyState MUST be set to 4 (Loaded) immediatly after having gone to 3 (Receiving).

If the UA supports Expect/Continue for request bodies [RFC2616] it SHOULD insert Expect headers and handle 100 Continue responses appropriately.

Parameters

data of varying types (see IDL)

Data to send.

No Return Value

Exceptions

DOMException

INVALID_STATE_ERR MUST be raised if this method is called when readyState has an inappropriate value.

The nominated request header (header) field value MUST be set to value, with the following exceptions:

• If the readyState attribute has a value other than 1 (Open), an exception MUST be raised.
• Nothing MUST be done if the header or value arguments contain any U+000A LINE FEED or U+000D CARRIAGE RETURN characters, or if the header argument contains any U+0020 SPACE or U+003A COLON charecters.
• Nothing MUST be done if the header argument matches Accept-Charset, Accept-Encoding, Content-Length, Expect, Date, Host, Keep-Alive, Referer, TE, Trailer, Transfer-Encoding or Upgrade case-insensitively.

// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send(null);
// ...would result in the following header being sent:
...
X-Test: one, two
...

Implementations MUST replace any existing value if the nominated request header field value is one of: Authorization, Content-Base, Content-Location, Content-MD5, Content-Range, Content-Type, Content-Version, Delta-Base, Depth, Destinaion, ETag, Expect, From, If-Modified-Since, If-Range, If-Unmodified-Since, Max-Forwards, MIME-Version, Overwrite, Proxy-Authorization, SOAPAction or Timeout.

Otherwise, if the nominated request header field already has a value, the new value MUST be combined with the existing value (section 4.2, [RFC2616]). See also the send() method regarding UA header handling for caching, authentication, proxies, and cookies.

The list of request headers must be reset when the open() method is called.

Parameters

header of type DOMString

Name of the HTTP header.

value of type DOMString

Value of the HTTP header.

No Return Value

Exceptions

DOMException

INVALID_STATE_ERR MUST be raised if readyState has an inappropriate value. (See prose above.)