elemental.xml

Interface XMLHttpRequest

All Superinterfaces:

EventTarget

All Known Implementing Classes:

JsXMLHttpRequest

public interface XMLHttpRequest
extends EventTarget

XMLHttpRequest is a JavaScript object that was designed by Microsoft and adopted by Mozilla, Apple, and Google. It's now being standardized in the W3C. It provides an easy way to retrieve data at a URL. Despite its name, XMLHttpRequest can be used to retrieve any type of data, not just XML, and it supports protocols other than HTTP (including file and ftp).

To create an instance of XMLHttpRequest, simply do this:

var req = new XMLHttpRequest();

For details about how to use XMLHttpRequest, see Using XMLHttpRequest.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DONE The operation is complete.
static int	HEADERS_RECEIVED send() has been called, and headers and status are available.
static int	LOADING Downloading; responseText holds partial data.
static int	OPENED send()has not been called yet.
static int	UNSENT open()has not been called yet.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() Aborts the request if it has already been sent.
EventRemover	addEventListener(String type, EventListener listener) Register an event handler of a specific event type on the EventTarget.
EventRemover	addEventListener(String type, EventListener listener, boolean useCapture) Register an event handler of a specific event type on the EventTarget.
boolean	dispatchEvent(Event evt) Dispatch an event to this EventTarget.
String	getAllResponseHeaders() string getAllResponseHeaders();
EventListener	getOnabort()
EventListener	getOnerror()
EventListener	getOnload()
EventListener	getOnloadend()
EventListener	getOnloadstart()
EventListener	getOnprogress()
EventListener	getOnreadystatechange()
int	getReadyState() The state of the request:
Object	getResponse() The response entity body according to responseType, as an ArrayBuffer, Blob, Document , JavaScript object (for "moz-json"), or string.
Blob	getResponseBlob()
String	getResponseHeader(String header) Returns the string containing the text of the specified header, or null if either the response has not yet been received or the header doesn't exist in the response.
String	getResponseText() The response to the request as text, or null if the request was unsuccessful or has not yet been sent.
String	getResponseType() Can be set to change the response type.
Document	getResponseXML() The response to the request as a DOM Document object, or null if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML.
int	getStatus() The status of the response to the request.
String	getStatusText() The response string returned by the HTTP server.
XMLHttpRequestUpload	getUpload() The upload process can be tracked by adding an event listener to upload.
boolean	isAsBlob()
boolean	isWithCredentials() Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies or authorization headers.
void	open(String method, String url) Initializes a request.
void	open(String method, String url, boolean async) Initializes a request.
void	open(String method, String url, boolean async, String user) Initializes a request.
void	open(String method, String url, boolean async, String user, String password) Initializes a request.
void	overrideMimeType(String override) Overrides the MIME type returned by the server.
void	removeEventListener(String type, EventListener listener) Removes an event listener from the EventTarget.
void	removeEventListener(String type, EventListener listener, boolean useCapture) Removes an event listener from the EventTarget.
void	send() Sends the request.
void	send(ArrayBuffer data) Sends the request.
void	send(Blob data) Sends the request.
void	send(Document data) Sends the request.
void	send(FormData data) Sends the request.
void	send(String data) Sends the request.
void	setAsBlob(boolean arg)
void	setOnabort(EventListener arg)
void	setOnerror(EventListener arg)
void	setOnload(EventListener arg)
void	setOnloadend(EventListener arg)
void	setOnloadstart(EventListener arg)
void	setOnprogress(EventListener arg)
void	setOnreadystatechange(EventListener arg)
void	setRequestHeader(String header, String value) Sets the value of an HTTP request header.You must call open()before using this method.
void	setResponseType(String arg)
void	setWithCredentials(boolean arg)

Field Detail

DONE

static final int DONE

The operation is complete.

See Also:

Constant Field Values

HEADERS_RECEIVED

static final int HEADERS_RECEIVED

send() has been called, and headers and status are available.

See Also:

Constant Field Values

LOADING

static final int LOADING

Downloading; responseText holds partial data.

See Also:

Constant Field Values

OPENED

static final int OPENED

send()has not been called yet.

See Also:

Constant Field Values

UNSENT

static final int UNSENT

open()has not been called yet.

See Also:

Constant Field Values

Method Detail

isAsBlob

boolean isAsBlob()

setAsBlob

void setAsBlob(boolean arg)

getOnabort

EventListener getOnabort()

setOnabort

void setOnabort(EventListener arg)

getOnerror

EventListener getOnerror()

setOnerror

void setOnerror(EventListener arg)

getOnload

EventListener getOnload()

setOnload

void setOnload(EventListener arg)

getOnloadend

EventListener getOnloadend()

setOnloadend

void setOnloadend(EventListener arg)

getOnloadstart

EventListener getOnloadstart()

setOnloadstart

void setOnloadstart(EventListener arg)

getOnprogress

EventListener getOnprogress()

setOnprogress

void setOnprogress(EventListener arg)

getOnreadystatechange

EventListener getOnreadystatechange()

setOnreadystatechange

void setOnreadystatechange(EventListener arg)

getReadyState

int getReadyState()

The state of the request:

Value	State	Description
0	UNSENT	open()has not been called yet.
1	OPENED	send()has not been called yet.
2	HEADERS_RECEIVED	send() has been called, and headers and status are available.
3	LOADING	Downloading; responseText holds partial data.
4	DONE	The operation is complete.

getResponse

Object getResponse()

The response entity body according to responseType, as an ArrayBuffer, Blob, Document , JavaScript object (for "moz-json"), or string. This is NULL if the request is not complete or was not successful.

getResponseBlob

Blob getResponseBlob()

getResponseText

String getResponseText()

The response to the request as text, or null if the request was unsuccessful or has not yet been sent. Read-only.

getResponseType

String getResponseType()

Can be set to change the response type. This tells the server what format you want the response to be in.

Value	Data type of response property
empty string	String (this is the default)
"arraybuffer"	ArrayBuffer
"blob"	Blob
"document"	Document
"text"	String
"moz-json"	JavaScript object, parsed from a JSON string returned by the server Requires Gecko 9.0

setResponseType

void setResponseType(String arg)

getResponseXML

Document getResponseXML()

The response to the request as a DOM Document object, or null if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML. The response is parsed as if it were a text/xml stream. Read-only.

Note: If the server doesn't apply the text/xml Content-Type header, you can use overrideMimeType()to force XMLHttpRequest to parse it as XML anyway.

getStatus

int getStatus()

The status of the response to the request. This is the HTTP result code (for example, status is 200 for a successful request). Read-only.

getStatusText

String getStatusText()

The response string returned by the HTTP server. Unlike status, this includes the entire text of the response message ("200 OK", for example). Read-only.

getUpload

XMLHttpRequestUpload getUpload()

The upload process can be tracked by adding an event listener to upload. New in Firefox 3.5

isWithCredentials

boolean isWithCredentials()

Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies or authorization headers. New in Firefox 3.5

Note: This never affects same-site requests.

The default is false.

setWithCredentials

void setWithCredentials(boolean arg)

abort

void abort()

Aborts the request if it has already been sent.

addEventListener

EventRemover addEventListener(String type,
                            EventListener listener)

Description copied from interface: EventTarget

Register an event handler of a specific event type on the EventTarget.

Specified by:

addEventListener in interface EventTarget

addEventListener

EventRemover addEventListener(String type,
                            EventListener listener,
                            boolean useCapture)

Description copied from interface: EventTarget

Register an event handler of a specific event type on the EventTarget.

Specified by:

addEventListener in interface EventTarget

dispatchEvent

boolean dispatchEvent(Event evt)

Description copied from interface: EventTarget

Dispatch an event to this EventTarget.

Specified by:

dispatchEvent in interface EventTarget

getAllResponseHeaders

String getAllResponseHeaders()

string getAllResponseHeaders();

Returns all the response headers as a string, or null if no response has been received. Note: For multipart requests, this returns the headers from the current part of the request, not from the original channel.

getResponseHeader

String getResponseHeader(String header)

Returns the string containing the text of the specified header, or null if either the response has not yet been received or the header doesn't exist in the response.

open

void open(String method,
        String url)

Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.

Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().

Parameters

method

The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.

url

The URL to which to send the request.

async

An optional boolean parameter, defaulting to true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown.

user

The optional user name to use for authentication purposes; by default, this is an empty string.

password

The optional password to use for authentication purposes; by default, this is an empty string.

open

void open(String method,
        String url,
        boolean async)

Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.

Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().

Parameters

method

The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.

url

The URL to which to send the request.

async

An optional boolean parameter, defaulting to true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown.

user

The optional user name to use for authentication purposes; by default, this is an empty string.

password

The optional password to use for authentication purposes; by default, this is an empty string.

open

void open(String method,
        String url,
        boolean async,
        String user)

Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.

Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().

Parameters

method

The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.

url

The URL to which to send the request.

async

An optional boolean parameter, defaulting to true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown.

user

The optional user name to use for authentication purposes; by default, this is an empty string.

password

The optional password to use for authentication purposes; by default, this is an empty string.

open

void open(String method,
        String url,
        boolean async,
        String user,
        String password)

Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()instead.

Note: Calling this method an already active request (one for which open()or openRequest()has already been called) is the equivalent of calling abort().

Parameters

method

The HTTP method to use; either "POST" or "GET". Ignored for non-HTTP(S) URLs.

url

The URL to which to send the request.

async

An optional boolean parameter, defaulting to true, indicating whether or not to perform the operation asynchronously. If this value is false, the send()method does not return until the response is received. If true, notification of a completed transaction is provided using event listeners. This must be true if the multipart attribute is true, or an exception will be thrown.

user

The optional user name to use for authentication purposes; by default, this is an empty string.

password

The optional password to use for authentication purposes; by default, this is an empty string.

overrideMimeType

void overrideMimeType(String override)

Overrides the MIME type returned by the server. This may be used, for example, to force a stream to be treated and parsed as text/xml, even if the server does not report it as such.This method must be called before send().

removeEventListener

void removeEventListener(String type,
                       EventListener listener)

Description copied from interface: EventTarget

Removes an event listener from the EventTarget.

Specified by:

removeEventListener in interface EventTarget

removeEventListener

void removeEventListener(String type,
                       EventListener listener,
                       boolean useCapture)

Description copied from interface: EventTarget

Removes an event listener from the EventTarget.

Specified by:

removeEventListener in interface EventTarget

send

void send()

Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.

Note: Any event listeners you wish to set must be set before calling send().

Parameters

body

This may be an nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile , and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) you may also specify a FormData object.

send

void send(ArrayBuffer data)

Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.

Note: Any event listeners you wish to set must be set before calling send().

Parameters

body

This may be an nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile , and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) you may also specify a FormData object.

send

void send(Blob data)

Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.

Note: Any event listeners you wish to set must be set before calling send().

Parameters

body

This may be an nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile , and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) you may also specify a FormData object.

send

void send(Document data)

Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.

Note: Any event listeners you wish to set must be set before calling send().

Parameters

body

This may be an nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile , and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) you may also specify a FormData object.

send

void send(String data)

Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.

Note: Any event listeners you wish to set must be set before calling send().

Parameters

body

This may be an nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile , and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) you may also specify a FormData object.

send

void send(FormData data)

Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.

Note: Any event listeners you wish to set must be set before calling send().

Parameters

body

This may be an nsIDocument, nsIInputStream, or a string (an nsISupportsString if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOMFile , and starting with Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) you may also specify a FormData object.

setRequestHeader

void setRequestHeader(String header,
                    String value)

Sets the value of an HTTP request header.You must call open()before using this method.

Parameters

header

The name of the header whose value is to be set.

value

The value to set as the body of the header.