Section 25.320. XMLHttpRequest: An HTTP request and response

25.320. XMLHttpRequest: An HTTP request and response

Firefox 1.0, Internet Explorer 5.0, Safari 1.2, Opera 7.60: Object XMLHttpRequest

25.320.1. Constructor

 new XMLHttpRequest( )                     // All browsers except IE 5 and IE 6 new ActiveXObject("Msxml2.XMLHTTP")      // IE new ActiveXObject("Microsoft.XMLHTTP")   // IE with older system libraries 

25.320.2. Properties

readonly short readyState

The state of the HTTP request. The value of this property begins at 0 when an XMLHttpRequest is first created and increases to 4 when the complete HTTP response has been received. Each of the five states has an informal name associated with it, and the table below lists the states, their names, and their meanings:

State	Name	Description
0	Uninitialized	This is the initial state. The XMLHttpRequest object has just been created or has been reset with the abort( ) method.
1	Open	The open( ) method has been called, but send( ) has not. The request has not yet been sent.
2	Sent	The send( ) method has been called, and the HTTP request has been transmitted to the web server. No response has been received yet.
3	Receiving	All response headers have been received. The response body is being received but is not complete.
4	Loaded	The HTTP response has been fully received.

The value of readyState never decreases, unless abort( ) or open( ) are called on a request that is already in progress. Every time the value of this property increases, the onreadystatechange event handler is triggered.

readonly String responseText

The body of the response (not including headers) that has been received from the server so far, or the empty string if no data has been received yet. If readyState is less than 3, this property is the empty string. When readyState is 3, this property returns whatever portion of the response has been received so far. If readyState is 4, this property holds the complete body of the response.

If the response includes headers that specify a character encoding for the body, that encoding is used. Otherwise, the Unicode UTF-8 encoding is assumed.

readonly Document responseXML

The response to the request, parsed as XML and returned as a Document object. This property will be null unless all three of the following conditions are true:

• readyState is 4.

• The response includes a Content-Type header of "text/xml", "application/xml", or anything ending with "+xml" to indicate that the response is an XML document.

• The response body consists of well-formed XML markup that can be parsed without errors.

readonly short status

The HTTP status code returned by the server, such as 200 for success and 404 for "Not Found" errors. Reading this property when readyState is less than 3 causes an exception.

readonly String statusText

This property specifies the HTTP status code of the request by name rather than by number. That is, it is "OK" when status is 200 and "Not Found" when status is 404. As with the status property, reading this property when readyState is less than 3 causes an exception.

25.320.3. Methods

abort( )

Cancels the current request, closing connections and stopping any pending network activity.

getAllResponseHeaders( )

Returns the HTTP response headers as an unparsed string.

getResponseHeader( )

Returns the value of a named HTTP response header

open( )

Initializes HTTP request parameters, such as the URL and HTTP method, but does not send the request.

send( )

Sends the HTTP request, using parameters passed to the open( ) method and an optional request body passed to this method.

setRequestHeader( )

Sets or adds an HTTP request header to an open but unsent request.

25.320.4. Event Handlers

onreadystatechange

Event-handler function invoked each time the readyState property changes. It may also be invoked multiple times while readyState is 3.

25.320.5. Description

The XMLHttpRequest object allows client-side JavaScript to issue HTTP requests and receive responses (which need not be XML) from web servers. XMLHttpRequest is the subject of Chapter 20, and that chapter contains many examples of its use.

XMLHttpRequest is quite portable and well supported by all modern browsers. The only browser dependency involves the creation of an XMLHttpRequest object. In Internet Explorer 5 and 6, you must use the IE-specific ActiveXObject( ) constructor, as shown in the Constructor section earlier.

Once an XMLHttpRequest object has been created, you typically use it like this:

1. Call open( ) to specify the URL and method (usually "GET" or "POST") for the request. When you call open( ), you also specify whether you want the request to be synchronous or asynchronous.

2. If you specified an asynchronous request, set the onreadystatechange property to the function that will be notified of the progress of the request.

3. Call setRequestHeader( ), if needed, to specify additional request parameters.

4. Call send( ) to send the request to the web server. If it is a POST request, you may also pass a request body to this method. If you specify a synchronous request in your call to open( ), the send( ) method blocks until the response is complete and readyState is 4. Otherwise, your onreadystatechange event-handler function must wait until the readyState property reaches 4 (or at least 3).

5. Once send( ) has returned for synchronous requests, or readyState has reached 4 for asynchronous requests, you can use the server's response. First, check the status code to ensure that the request was successful. If so, use geTResponseHeader( ) or geTResponseHeaders( ) to retrieve values from the response header, and use the responseText or responseXML properties to obtain the response body.

The XMLHttpRequest object has not been standardized, but work on a standard has begun at the W3C at the time of this writing. This documentation is based on working drafts of the standard. Current XMLHttpRequest implementations are quite interoperable but differ in minor ways from the standard. An implementation might return null where the standard requires the empty string, for example, or might set readyState to 3 without guaranteeing that all response headers are available.

25.320.6. See Also

Chapter 20