/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: NPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Netscape Public License * Version 1.1 (the "License"); you may not use this file except in * compliance with the License. You may obtain a copy of the License at * http://www.mozilla.org/NPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 1998 * the Initial Developer. All Rights Reserved. * * Contributor(s): * * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the NPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the NPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" interface nsIDOMDocument; interface nsIDOMEventListener; interface nsIChannel; interface nsIVariant; /** * 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/ * * 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 : * * 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 target(do_QuertyInterface(myxmlhttpreq)); * * target->AddEventListener(NS_LITERAL_STRING("load"), mylistener, * PR_FALSE) * * where mylistener is your event listener object that implements the * interface nsIDOMEventListener. * * The 'onload' and 'onerror' attributes moved to nsIJSXMLHttRequest, * but if you're coding in C++ you should avoid using those. */ [scriptable, uuid(b7215e70-4157-11d4-9a42-000064657374)] interface nsIXMLHttpRequest : nsISupports { /** * 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. * * Mozilla only. */ readonly attribute nsIChannel channel; /** * The 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. */ readonly attribute nsIDOMDocument responseXML; /** * The response to the request as text. * NULL if the request is unsuccessful or * has not yet been sent. */ readonly attribute wstring responseText; /** * The status of the response to the request for HTTP requests. */ readonly attribute unsigned long status; /** * The string representing the status of the response for * HTTP requests. */ readonly attribute string statusText; /** * If the request has been sent already, this method will * abort the request. */ void abort(); /** * Returns all of the response headers as a string for HTTP * requests. * * @returns A string containing all of the response headers. * NULL if the response has not yet been received. */ string getAllResponseHeaders(); /** * Returns the text of the header with the specified name for * HTTP requests. * * @param header The name of the header to retrieve * @returns A string containing the text of the header specified. * NULL if the response has not yet been received or the * header does not exist in the response. */ string getResponseHeader(in string header); /** * Native (non-script) method to initialize a request. Note that * the request is not sent until the send method * is invoked. * * @param method The HTTP method - either "POST" or "GET". Ignored * if the URL is not a HTTP URL. * @param url The URL to which to send the request. * @param 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. * @param user A username for authentication if necessary. * @param password A password for authentication if necessary. */ [noscript] void openRequest(in string method, in string url, in boolean async, in string user, in string 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. * * @param method The HTTP method - either "POST" or "GET". Ignored * if the URL is not a HTTP URL. * @param url The URL to which to send the request. * @param 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. * @param user (optional) A username for authentication if necessary. * The default value is the empty string * @param password (optional) A password for authentication if necessary. * The default value is the empty string */ void open(in string method, in string url); /** * 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. * * @param body Either an instance of nsIDOMDocument, nsIInputStream * or a string (nsISupportsWString 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, it is expected * to contain the ContentType: and ContentLength: headers * and trailing carriage-return/line-feed pairs. */ void send(in nsIVariant body); /** * Sets a HTTP request header for HTTP requests. You must call open * before setting the request headers. * * @param header The name of the header to set in the request. * @param value The body of the header. */ void setRequestHeader(in string header, in string value); /** * 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. */ readonly attribute long readyState; /** * 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. * * @param mimetype The type used to override that returned by the server * (if any). */ void overrideMimeType(in string mimetype); }; [scriptable, function, uuid(6459B7CE-6B57-4934-A0AF-0133BA6F9085)] interface nsIOnReadystatechangeHandler : nsISupports { /** * Helper to implement the onreadystatechange callback member. * You should not need to use this. */ void handleEvent(); }; [scriptable, uuid(9deabc90-28d5-41d3-a660-474f2254f4ba)] interface nsIJSXMLHttpRequest : nsISupports { /** * Meant to be a script-only mechanism for setting a load event listener. * The attribute is expected to be JavaScript function object. When * the load event occurs, the function is invoked. * This attribute should not be used from native code!! * * Mozilla only. */ attribute nsIDOMEventListener onload; /** * Meant to be a script-only mechanism for setting an error event listener. * The attribute is expected to be JavaScript function object. When * the error event occurs, the function is invoked. * This attribute should not be used from native code!! * * Mozilla only. */ attribute nsIDOMEventListener onerror; /** * Meant to be a script-only mechanism for setting a callback function. * The attribute is expected to be JavaScript function object. When the * readyState changes, the callback function will be called. * This attribute should not be used from native code!! */ attribute nsIOnReadystatechangeHandler onreadystatechange; }; %{ C++ #define NS_XMLHTTPREQUEST_CID \ { /* d164e770-4157-11d4-9a42-000064657374 */ \ 0xd164e770, 0x4157, 0x11d4, \ {0x9a, 0x42, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74} } #define NS_XMLHTTPREQUEST_CONTRACTID \ "@mozilla.org/xmlextras/xmlhttprequest;1" %}