Skip to main content

Visit Mozilla.org

nsIXMLHttpRequest

From MDC

Mozilla's XMLHttpRequest is modelled after Microsoft's IXMLHttpRequest object. The goal has been to make Mozilla's version match Microsoft's version as closely as possible, but there are bound to be some differences.

In general, Microsoft's documentation for IXMLHttpRequest can be used. Mozilla's interface definitions provide some additional documentation. The web page to look at is http://www.mozilla.org/xmlextras/.

See also XMLHttpRequest.

Contents


Mozilla's XMLHttpRequest object can be created in JavaScript like this: 

  new XMLHttpRequest()

compare to Internet Explorer: 

  new ActiveXObject("Msxml2.XMLHTTP")

From JavaScript, the methods and properties visible in the XMLHttpRequest object are a combination of nsIXMLHttpRequest and nsIJSXMLHttpRequest there is no need to differentiate between those interfaces.

From native code, the way to set up onload and onerror handlers is a bit different. Here is a comment from Johnny Stenback <jst@netscape.com>:

The mozilla implementation of nsIXMLHttpRequest implements the interface nsIDOMEventTarget and that's how you're supported to add event listeners. Try something like this: nsCOMPtr<nsIDOMEventTarget> target(do_QueryInterface(myxmlhttpreq)); target->AddEventListener(NS_LITERAL_STRING("load"), mylistener, PR_FALSE) where mylistener is your event listener object that implements the interface nsIDOMEventListener. The 'onload', 'onerror', and 'onreadystatechange' attributes moved to nsIJSXMLHttpRequest, but if you're coding in C++ you should avoid using those.

Though actually, if you use addEventListener from C++ weird things will happen too, since the result will depend on what JS happens to be on the stack when you do it....

Conclusion: Do not use event listeners on XMLHttpRequest from C++, unless you're aware of all the security implications. And then think twice about it.

[edit] Method Overview

void abort();
string getAllResponseHeaders();
void openRequest(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password);
void open(in AUTF8String method, in AUTF8String url);
void send(in nsIVariant body);
void overrideMimeType(in AUTF8String mimetype);

[edit] Attributes

Attribute Type Description
channel nsIChannel readonly The request uses a channel in order to perform the request. This attribute represents the channel used for the request. NULL if the channel has not yet been created.

In a multipart request case, this is the initial channel, not the different parts in the multipart request.

Mozilla only. Requires elevated privileges to access.

responseXML nsIDOMDocument readonlyThe response to the request is parsed as if it were a text/xml stream. This attributes represents the response as a DOM Document object. NULL if the request is unsuccessful or has not yet been sent.
responseText AString The response to the request as text. NULL if the request is unsuccessful or has not yet been sent.
status unsigned long readonly The status of the response to the request for HTTP requests.
statusText AUTF8String readonly The string representing the status of the response for HTTP requests.
readyState long readonly The state of the request.

Possible values:

0 UNINITIALIZED open() has not been called yet.
1 LOADING send() has not been called yet.
2 LOADED send() has been called, headers and status are available.
3 INTERACTIVE Downloading, responseText holds the partial data.
4 COMPLETED Finished with all operations.
multipart boolean Set to true if the response is expected to be a stream of possibly multiple (XML) documents. If set to true, the content type of the initial response must be multipart/x-mixed-replace or an error will be triggerd. All requests must be asynchronous.

This enables server push. For each XML document that's written to this request, a new XML DOM document is created and the onload handler is called inbetween documents. Note that when this is set, the onload handler and other event handlers are not reset after the first XML document is loaded, and the onload handler will be called as each part of the response is received.

[edit] Methods

[edit] abort()

 void   abort();

If the request has been sent already, this method will abort the request.

[edit] getAllResponseHeaders()

 string getAllResponseHeaders();
[edit] Return value

All of the response headers as a string for HTTP requests.

Note that this will return all the headers from the *current* part of a multipart request, not from the original channel. Returns A string containing all of the response headers or NULL if the response has not yet been received.

[edit] getResponseHeader()

 ACString getResponseHeader(in AUTF8String header);
[edit] Parameters
header

The name of the header to retrieve

[edit] Return value

Returns a string containing the text of the header specified or NULL if the response has not yet been received or the header does not exist in the response.

[edit] openRequest()

  [noscript] void   openRequest(in AUTF8String method,
                                in AUTF8String url,
                                in boolean async,
                                in AString user,
                                in AString password);

Native (non-script) method to initialize a request. Note that the request is not sent until the send method is invoked. If there is an "active" request (that is, if open() or openRequest() has been called already), this is equivalent to calling abort().

[edit] Parameters
method

The HTTP method, for example "POST" or "GET". Ignored if the URL is not a HTTP(S) URL.

url

The URL to which to send the request.

async

Whether the request is synchronous or asynchronous i.e. whether send returns only after the response is received or if it returns immediately after sending the request. In the latter case, notification of completion is sent through the event listeners. This argument must be true if the multipart attribute has been set to true, or an exception will be thrown.

user

A username for authentication if necessary.

password

A password for authentication if necessary.

[edit] open()

 void   open(in AUTF8String method, in AUTF8String url);
 void   open(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password);

Meant to be a script-only method for initializing a request. The parameters are similar to the ones detailed in the description of openRequest, but the last 3 are optional.

If there is an "active" request (that is, if open() or openRequest() has been called already), this is equivalent to calling abort().

[edit] Parameters
method

The HTTP method - either "POST" or "GET". Ignored if the URL is not a HTTP URL.

url

The URL to which to send the request.

async

(optional) Whether the request is synchronous or asynchronous i.e. whether send returns only after the response is received or if it returns immediately after sending the request. In the latter case, notification of completion is sent through the event listeners. The default value is true. This argument must be true if the multipart attribute has been set to true, or an exception will be thrown.

user

(optional) A username for authentication if necessary. The default value is the empty string

password

(optional) A password for authentication if necessary. The default value is the empty string

[edit] send()

 void   send(in nsIVariant body);

Sends the request. If the request is asynchronous, returns immediately after sending the request. If it is synchronous returns only after the response has been received.

All event listeners must be set before calling send().

After the initial response, all event listeners will be cleared.

[edit] Parameters
body

Either an instance of nsIDOMDocument, nsIInputStream or a string (nsISupportsString in the native calling case). This is used to populate the body of the HTTP request if the HTTP request method is "POST". If the parameter is a nsIDOMDocument, it is serialized. If the parameter is a nsIInputStream, then it must be compatible with nsIUploadChannel.setUploadStream, and a Content-Length header will be added to the HTTP request with a value given by nsIInputStream.available. Any headers included at the top of the stream will be treated as part of the message body. The MIME type of the stream should be specified by setting the Content- Type header via the setRequestHeader method before calling send.

Note: When sending a nsIDOMDocument, versions of Firefox prior to version 3 always send the request using UTF-8 encoding; Firefox 3 properly sends the document using the encoding specified by body.xmlEncoding, or UTF-8 if no encoding is specified.

[edit] sendAsBinary()

New in Firefox 3 

 void sendAsBinary(in DOMString body);

Sends the request, with the given string in binary. The string is converted to 8-bit by truncation (i.e. the high-order byte of each character is discarded).

[edit] setRequestHeader()

 void   setRequestHeader(in AUTF8String header, in AUTF8String value);

Sets a HTTP request header for HTTP requests. You must call open before setting the request headers.

[edit] Parameters
header

The name of the header to set in the request.

value

The body of the header.

[edit] overrideMimeType()

 void   overrideMimeType(in AUTF8String mimetype);

Override the mime type returned by the server (if any). 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 must be done before the send method is invoked.

[edit] Parameters

mimetype - The type used to override that returned by the server (if any).

[edit] Example code

This is a simple example code for opening a simple HTTPRequest from a xul application (like a mozilla extension) without using observers: 

 var req = Components.classes["@mozilla.org/xmlextras/xmlhttprequest;1"].createInstance();
 req.open('POST', "http://www.foo.bar:8080/nietzsche.do", true);
 req.send('your=data&and=more&stuff=here');
Retrieved from "http://developer.mozilla.org/en/docs/nsIXMLHttpRequest"