diff options
Diffstat (limited to 'dom/xhr/nsIXMLHttpRequest.idl')
| -rw-r--r-- | dom/xhr/nsIXMLHttpRequest.idl | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/dom/xhr/nsIXMLHttpRequest.idl b/dom/xhr/nsIXMLHttpRequest.idl new file mode 100644 index 000000000..53e80bab7 --- /dev/null +++ b/dom/xhr/nsIXMLHttpRequest.idl @@ -0,0 +1,349 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsIDOMEventTarget.idl" + +interface nsIChannel; +interface nsIDOMDocument; +interface nsIDOMEventListener; +interface nsILoadGroup; +interface nsIPrincipal; +interface nsIScriptContext; +interface nsIURI; +interface nsIVariant; +interface nsIGlobalObject; +interface nsIInputStream; +interface nsIDOMBlob; + +[builtinclass, uuid(88e7d2a0-2e5b-4f65-9624-a61e607a9948)] +interface nsIXMLHttpRequestEventTarget : nsIDOMEventTarget { + // event handler attributes +}; + +[builtinclass, uuid(d74c4dc4-bc8c-4f5d-b7f1-121a48750abe)] +interface nsIXMLHttpRequestUpload : nsIXMLHttpRequestEventTarget { + // for future use +}; + +/** + * 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. + * + * 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(6f54214c-7175-498d-9d2d-0429e38c2869)] +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. 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; + + /** + * Determine a response format which response attribute returns. + * empty string (initial value) or "text": as text. + * "arraybuffer": as a typed array ArrayBuffer. + * "blob": as a File API Blob. + * "document": as a DOM Document object. + */ + attribute AString responseType; + + /** + * The response to the request as a specified format by responseType. + * NULL if the request is unsuccessful or + * has not yet been sent. + */ + [implicit_jscontext] readonly attribute jsval /* any */ response; + + /** + * The status of the response to the request for HTTP requests. + */ + // XXX spec says unsigned short + readonly attribute unsigned long status; + + /** + * The string representing the status of the response for + * HTTP requests. + */ + readonly attribute ACString statusText; + + /** + * If the request has been sent already, this method will + * abort the request. + */ + [binaryname(SlowAbort)] void abort(); + + /** + * Returns all of the response headers as a string for HTTP + * requests. + * + * @returns A string containing all of the response headers. + * The empty string if the response has not yet been received. + */ + ACString 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 ACString header); + +%{C++ + // note this is NOT virtual so this won't muck with the vtable! + inline nsresult Open(const nsACString& method, const nsACString& url, + bool async, const nsAString& user, + const nsAString& password) { + return Open(method, url, async, user, password, 3); + } +%} + /** + * Meant to be a script-only method for initializing a request. + * + * If there is an "active" request (that is, if open() has been called + * already), this is equivalent to calling abort() and then open(). + * + * @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 + */ + [optional_argc] void open(in ACString method, in AUTF8String url, + [optional] in boolean async, + [optional,Undefined(Empty)] in DOMString user, + [optional,Undefined(Empty)] in DOMString password); + + /** + * 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([optional] 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 ACString header, in ACString value); + + /** + * The amount of milliseconds a request can take before being terminated. + * Initially zero. Zero means there is no timeout. + */ + attribute unsigned long timeout; + + /** + * The state of the request. + * + * Possible values: + * 0 UNSENT open() has not been called yet. + * 1 OPENED send() has not been called yet. + * 2 HEADERS_RECEIVED + * send() has been called, headers and status are available. + * 3 LOADING Downloading, responseText holds the partial data. + * 4 DONE Finished with all operations. + */ + const unsigned short UNSENT = 0; + const unsigned short OPENED = 1; + const unsigned short HEADERS_RECEIVED = 2; + const unsigned short LOADING = 3; + const unsigned short DONE = 4; + readonly attribute unsigned short 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). + */ + [binaryname(SlowOverrideMimeType)] void overrideMimeType(in DOMString mimetype); + + /** + * 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; + + /** + * When set to true attempts to make cross-site Access-Control requests + * with credentials such as cookies and authorization headers. + * + * Never affects same-site requests. + * + * Defaults to false. + */ + attribute boolean withCredentials; + + /** + * 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 globalObject The associated global for the request. Can be the + * outer window, a sandbox, or a backstage pass. + * May be null, but then the request cannot create a + * document. + * @param baseURI The base URI to use when resolving relative URIs. May be + * null. + * @param loadGroup An optional load group to use when performing the request. + * This will be used even if the global has a window with a + * load group. + */ + [noscript] void init(in nsIPrincipal principal, + in nsIGlobalObject globalObject, + in nsIURI baseURI, + [optional] in nsILoadGroup loadGroup); + + /** + * Upload process can be tracked by adding event listener to |upload|. + */ + readonly attribute nsIXMLHttpRequestUpload upload; + + /** + * 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. + */ + [implicit_jscontext] attribute jsval onreadystatechange; + + /** + * If true, the request will be sent without cookie and authentication + * headers. + */ + readonly attribute boolean mozAnon; + + /** + * If true, the same origin policy will not be enforced on the request. + */ + readonly attribute boolean mozSystem; +}; + +[uuid(840d0d00-e83e-4a29-b3c7-67e96e90a499)] +interface nsIXHRSendable : nsISupports { + void getSendInfo(out nsIInputStream body, + out uint64_t contentLength, + out ACString contentType, + out ACString charset); +}; + +/** + * @deprecated + */ +[scriptable, uuid(8ae70a39-edf1-40b4-a992-472d23421c25)] +interface nsIJSXMLHttpRequest : nsISupports { +}; + +%{ 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" +%} |