| /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ |
| /* ***** BEGIN LICENSE BLOCK ***** |
| * Version: MPL 1.1/GPL 2.0/LGPL 2.1 |
| * |
| * The contents of this file are subject to the Mozilla 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/MPL/ |
| * |
| * 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 MPL, 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 MPL, the GPL or the LGPL. |
| * |
| * ***** END LICENSE BLOCK ***** */ |
| |
| #include "nsISupports.idl" |
| |
| interface nsIChannel; |
| interface nsIDOMDocument; |
| interface nsIDOMEventListener; |
| interface nsIPrincipal; |
| interface nsIScriptContext; |
| interface nsIVariant; |
| interface nsPIDOMWindow; |
| |
| /** |
| * 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 <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. |
| */ |
| [scriptable, uuid(acda85ab-d06c-4176-b834-6d129ca97ca3)] |
| 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. |
| * |
| * 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. |
| */ |
| 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 AString 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 AUTF8String 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. |
| * |
| * 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. |
| * 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. |
| */ |
| ACString getResponseHeader(in AUTF8String header); |
| |
| /** |
| * Native (non-script) method to initialize a request. Note that |
| * the request is not sent until the <code>send</code> 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(). |
| * |
| * @param method The HTTP method, for example "POST" or "GET". Ignored |
| * if the URL is not a HTTP(S) 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. |
| * This argument must be true if the multipart |
| * attribute has been set to true, or an exception will |
| * be thrown. |
| * @param user A username for authentication if necessary. |
| * @param password A password for authentication if necessary. |
| */ |
| [noscript] void openRequest(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 <code>openRequest</code>, 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(). |
| * |
| * @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. |
| * This argument must be true if the multipart |
| * attribute has been set to true, or an exception will |
| * be thrown. |
| * @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 AUTF8String method, in AUTF8String 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. |
| * |
| * All event listeners must be set before calling send(). |
| * |
| * After the initial response, all event listeners will be cleared. |
| * // XXXbz what does that mean, exactly? |
| * |
| * @param 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. |
| */ |
| void send(in nsIVariant body); |
| |
| /** |
| * A variant of the send() method used to send binary data. |
| * |
| * @param body The request body as a DOM string. The string data will be |
| * converted to a single-byte string by truncation (i.e., the |
| * high-order byte of each character will be discarded). |
| */ |
| void sendAsBinary(in DOMString 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 AUTF8String header, in AUTF8String 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 <code>send</code> method is invoked. |
| * |
| * @param mimetype The type used to override that returned by the server |
| * (if any). |
| */ |
| void overrideMimeType(in AUTF8String mimetype); |
| |
| /** |
| * 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. |
| */ |
| attribute boolean multipart; |
| |
| /** |
| * Set to true if this is a background service request. This will |
| * prevent a load group being associated with the request, and |
| * suppress any security dialogs from being shown * to the user. |
| * In the cases where one of those dialogs would be shown, the request |
| * will simply fail instead. |
| */ |
| attribute boolean mozBackgroundRequest; |
| |
| /** |
| * Initialize the object for use from C++ code with the principal, script |
| * context, and owner window that should be used. |
| * |
| * @param principal The principal to use for the request. This must not be |
| * null. |
| * @param scriptContext The script context to use for the request. May be |
| * null. |
| * @param ownerWindow The associated window for the request. May be null. |
| */ |
| [noscript] void init(in nsIPrincipal principal, |
| in nsIScriptContext scriptContext, |
| in nsPIDOMWindow ownerWindow); |
| }; |
| |
| [scriptable, uuid(261676b4-d508-43bf-b099-74635a0ee2e9)] |
| 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!! |
| * |
| * After the initial response, all event listeners will be cleared. |
| * // XXXbz what does that mean, exactly? |
| * |
| * Call open() before setting an onload listener. |
| * |
| * 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!! |
| * |
| * After the initial response, all event listeners will be cleared. |
| * // XXXbz what does that mean, exactly? |
| * |
| * Call open() before setting an onerror listener. |
| * |
| * Mozilla only. |
| */ |
| attribute nsIDOMEventListener onerror; |
| |
| /** |
| * Meant to be a script-only mechanism for setting a progress 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!! |
| * This event listener may be called multiple times during the open request. |
| * |
| * After the initial response, all event listeners will be cleared. |
| * // XXXbz what does that mean, exactly? |
| * |
| * This event listener must be set BEFORE calling open(). |
| * |
| * Mozilla only. |
| */ |
| attribute nsIDOMEventListener onprogress; |
| |
| /** |
| * Meant to be a script-only mechanism for setting an upload progress event |
| * listener. |
| * This attribute should not be used from native code!! |
| * This event listener may be called multiple times during the upload.. |
| * |
| * After the initial response, all event listeners will be cleared. |
| * // XXXbz what does that mean, exactly? |
| * |
| * This event listener must be set BEFORE calling open(). |
| * |
| * Mozilla only. |
| */ |
| attribute nsIDOMEventListener onuploadprogress; |
| |
| /** |
| * 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!! |
| * |
| * After the initial response, all event listeners will be cleared. |
| * // XXXbz what does that mean, exactly? |
| * |
| * Call open() before setting an onreadystatechange listener. |
| */ |
| attribute nsIDOMEventListener 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" |
| %} |
