michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsIDOMEventTarget.idl" michael@0: michael@0: interface nsIChannel; michael@0: interface nsIDOMDocument; michael@0: interface nsIDOMEventListener; michael@0: interface nsIPrincipal; michael@0: interface nsIScriptContext; michael@0: interface nsIURI; michael@0: interface nsIVariant; michael@0: interface nsIGlobalObject; michael@0: interface nsIInputStream; michael@0: interface nsIDOMBlob; michael@0: michael@0: [scriptable, builtinclass, uuid(5ced7e7a-e2c3-4563-a57d-31b97ce64dc5)] michael@0: interface nsIXMLHttpRequestEventTarget : nsIDOMEventTarget { michael@0: // event handler attributes michael@0: }; michael@0: michael@0: [scriptable, builtinclass, uuid(df3796fa-d98a-4185-9dda-d2f2b56a5d38)] michael@0: interface nsIXMLHttpRequestUpload : nsIXMLHttpRequestEventTarget { michael@0: // for future use michael@0: }; michael@0: michael@0: /** michael@0: * Mozilla's XMLHttpRequest is modelled after Microsoft's IXMLHttpRequest michael@0: * object. The goal has been to make Mozilla's version match Microsoft's michael@0: * version as closely as possible, but there are bound to be some differences. michael@0: * michael@0: * In general, Microsoft's documentation for IXMLHttpRequest can be used. michael@0: * Mozilla's interface definitions provide some additional documentation. The michael@0: * web page to look at is http://www.mozilla.org/xmlextras/ michael@0: * michael@0: * Mozilla's XMLHttpRequest object can be created in JavaScript like this: michael@0: * new XMLHttpRequest() michael@0: * compare to Internet Explorer: michael@0: * new ActiveXObject("Msxml2.XMLHTTP") michael@0: * michael@0: * From JavaScript, the methods and properties visible in the XMLHttpRequest michael@0: * object are a combination of nsIXMLHttpRequest and nsIJSXMLHttpRequest; michael@0: * there is no need to differentiate between those interfaces. michael@0: * michael@0: * From native code, the way to set up onload and onerror handlers is a bit michael@0: * different. Here is a comment from Johnny Stenback : michael@0: * michael@0: * The mozilla implementation of nsIXMLHttpRequest implements the interface michael@0: * nsIDOMEventTarget and that's how you're supported to add event listeners. michael@0: * Try something like this: michael@0: * michael@0: * nsCOMPtr target(do_QueryInterface(myxmlhttpreq)); michael@0: * michael@0: * target->AddEventListener(NS_LITERAL_STRING("load"), mylistener, michael@0: * PR_FALSE) michael@0: * michael@0: * where mylistener is your event listener object that implements the michael@0: * interface nsIDOMEventListener. michael@0: * michael@0: * The 'onload', 'onerror', and 'onreadystatechange' attributes moved to michael@0: * nsIJSXMLHttpRequest, but if you're coding in C++ you should avoid using michael@0: * those. michael@0: * michael@0: * Conclusion: Do not use event listeners on XMLHttpRequest from C++, unless michael@0: * you're aware of all the security implications. And then think twice about michael@0: * it. michael@0: */ michael@0: [scriptable, uuid(2e91e088-e9fa-4ba4-9887-2a0b7cf27a3e)] michael@0: interface nsIXMLHttpRequest : nsISupports michael@0: { michael@0: /** michael@0: * The request uses a channel in order to perform the michael@0: * request. This attribute represents the channel used michael@0: * for the request. NULL if the channel has not yet been michael@0: * created. michael@0: * michael@0: * Mozilla only. Requires elevated privileges to access. michael@0: */ michael@0: readonly attribute nsIChannel channel; michael@0: michael@0: /** michael@0: * The response to the request is parsed as if it were a michael@0: * text/xml stream. This attributes represents the response as michael@0: * a DOM Document object. NULL if the request is unsuccessful or michael@0: * has not yet been sent. michael@0: */ michael@0: readonly attribute nsIDOMDocument responseXML; michael@0: michael@0: /** michael@0: * The response to the request as text. michael@0: * NULL if the request is unsuccessful or michael@0: * has not yet been sent. michael@0: */ michael@0: readonly attribute AString responseText; michael@0: michael@0: /** michael@0: * Determine a response format which response attribute returns. michael@0: * empty string (initial value) or "text": as text. michael@0: * "arraybuffer": as a typed array ArrayBuffer. michael@0: * "blob": as a File API Blob. michael@0: * "document": as a DOM Document object. michael@0: */ michael@0: attribute AString responseType; michael@0: michael@0: /** michael@0: * The response to the request as a specified format by responseType. michael@0: * NULL if the request is unsuccessful or michael@0: * has not yet been sent. michael@0: */ michael@0: [implicit_jscontext] readonly attribute jsval /* any */ response; michael@0: michael@0: /** michael@0: * The status of the response to the request for HTTP requests. michael@0: */ michael@0: // XXX spec says unsigned short michael@0: readonly attribute unsigned long status; michael@0: michael@0: /** michael@0: * The string representing the status of the response for michael@0: * HTTP requests. michael@0: */ michael@0: readonly attribute ACString statusText; michael@0: michael@0: /** michael@0: * If the request has been sent already, this method will michael@0: * abort the request. michael@0: */ michael@0: [binaryname(SlowAbort)] void abort(); michael@0: michael@0: /** michael@0: * Returns all of the response headers as a string for HTTP michael@0: * requests. michael@0: * michael@0: * @returns A string containing all of the response headers. michael@0: * The empty string if the response has not yet been received. michael@0: */ michael@0: ACString getAllResponseHeaders(); michael@0: michael@0: /** michael@0: * Returns the text of the header with the specified name for michael@0: * HTTP requests. michael@0: * michael@0: * @param header The name of the header to retrieve michael@0: * @returns A string containing the text of the header specified. michael@0: * NULL if the response has not yet been received or the michael@0: * header does not exist in the response. michael@0: */ michael@0: ACString getResponseHeader(in ACString header); michael@0: michael@0: %{C++ michael@0: // note this is NOT virtual so this won't muck with the vtable! michael@0: inline nsresult Open(const nsACString& method, const nsACString& url, michael@0: bool async, const nsAString& user, michael@0: const nsAString& password) { michael@0: return Open(method, url, async, user, password, 3); michael@0: } michael@0: %} michael@0: /** michael@0: * Meant to be a script-only method for initializing a request. michael@0: * michael@0: * If there is an "active" request (that is, if open() has been called michael@0: * already), this is equivalent to calling abort() and then open(). michael@0: * michael@0: * @param method The HTTP method - either "POST" or "GET". Ignored michael@0: * if the URL is not a HTTP URL. michael@0: * @param url The URL to which to send the request. michael@0: * @param async (optional) Whether the request is synchronous or michael@0: * asynchronous i.e. whether send returns only after michael@0: * the response is received or if it returns immediately after michael@0: * sending the request. In the latter case, notification michael@0: * of completion is sent through the event listeners. michael@0: * The default value is true. michael@0: * @param user (optional) A username for authentication if necessary. michael@0: * The default value is the empty string michael@0: * @param password (optional) A password for authentication if necessary. michael@0: * The default value is the empty string michael@0: */ michael@0: [optional_argc] void open(in ACString method, in AUTF8String url, michael@0: [optional] in boolean async, michael@0: [optional,Undefined(Empty)] in DOMString user, michael@0: [optional,Undefined(Empty)] in DOMString password); michael@0: michael@0: /** michael@0: * Sends the request. If the request is asynchronous, returns michael@0: * immediately after sending the request. If it is synchronous michael@0: * returns only after the response has been received. michael@0: * michael@0: * All event listeners must be set before calling send(). michael@0: * michael@0: * After the initial response, all event listeners will be cleared. michael@0: * // XXXbz what does that mean, exactly? michael@0: * michael@0: * @param body Either an instance of nsIDOMDocument, nsIInputStream michael@0: * or a string (nsISupportsString in the native calling michael@0: * case). This is used to populate the body of the michael@0: * HTTP request if the HTTP request method is "POST". michael@0: * If the parameter is a nsIDOMDocument, it is serialized. michael@0: * If the parameter is a nsIInputStream, then it must be michael@0: * compatible with nsIUploadChannel.setUploadStream, and a michael@0: * Content-Length header will be added to the HTTP request michael@0: * with a value given by nsIInputStream.available. Any michael@0: * headers included at the top of the stream will be michael@0: * treated as part of the message body. The MIME type of michael@0: * the stream should be specified by setting the Content- michael@0: * Type header via the setRequestHeader method before michael@0: * calling send. michael@0: */ michael@0: void send([optional] in nsIVariant body); michael@0: michael@0: /** michael@0: * A variant of the send() method used to send binary data. michael@0: * michael@0: * @param body The request body as a DOM string. The string data will be michael@0: * converted to a single-byte string by truncation (i.e., the michael@0: * high-order byte of each character will be discarded). michael@0: */ michael@0: void sendAsBinary(in DOMString body); michael@0: michael@0: /** michael@0: * Sets a HTTP request header for HTTP requests. You must call open michael@0: * before setting the request headers. michael@0: * michael@0: * @param header The name of the header to set in the request. michael@0: * @param value The body of the header. michael@0: */ michael@0: void setRequestHeader(in ACString header, in ACString value); michael@0: michael@0: /** michael@0: * The amount of milliseconds a request can take before being terminated. michael@0: * Initially zero. Zero means there is no timeout. michael@0: */ michael@0: attribute unsigned long timeout; michael@0: michael@0: /** michael@0: * The state of the request. michael@0: * michael@0: * Possible values: michael@0: * 0 UNSENT open() has not been called yet. michael@0: * 1 OPENED send() has not been called yet. michael@0: * 2 HEADERS_RECEIVED michael@0: * send() has been called, headers and status are available. michael@0: * 3 LOADING Downloading, responseText holds the partial data. michael@0: * 4 DONE Finished with all operations. michael@0: */ michael@0: const unsigned short UNSENT = 0; michael@0: const unsigned short OPENED = 1; michael@0: const unsigned short HEADERS_RECEIVED = 2; michael@0: const unsigned short LOADING = 3; michael@0: const unsigned short DONE = 4; michael@0: readonly attribute unsigned short readyState; michael@0: michael@0: /** michael@0: * Override the mime type returned by the server (if any). This may michael@0: * be used, for example, to force a stream to be treated and parsed michael@0: * as text/xml, even if the server does not report it as such. This michael@0: * must be done before the send method is invoked. michael@0: * michael@0: * @param mimetype The type used to override that returned by the server michael@0: * (if any). michael@0: */ michael@0: [binaryname(SlowOverrideMimeType)] void overrideMimeType(in DOMString mimetype); michael@0: michael@0: /** michael@0: * Set to true if this is a background service request. This will michael@0: * prevent a load group being associated with the request, and michael@0: * suppress any security dialogs from being shown * to the user. michael@0: * In the cases where one of those dialogs would be shown, the request michael@0: * will simply fail instead. michael@0: */ michael@0: attribute boolean mozBackgroundRequest; michael@0: michael@0: /** michael@0: * When set to true attempts to make cross-site Access-Control requests michael@0: * with credentials such as cookies and authorization headers. michael@0: * michael@0: * Never affects same-site requests. michael@0: * michael@0: * Defaults to false. michael@0: */ michael@0: attribute boolean withCredentials; michael@0: michael@0: /** michael@0: * Initialize the object for use from C++ code with the principal, script michael@0: * context, and owner window that should be used. michael@0: * michael@0: * @param principal The principal to use for the request. This must not be michael@0: * null. michael@0: * @param scriptContext The script context to use for the request. May be michael@0: * null. michael@0: * @param globalObject The associated global for the request. Can be the michael@0: * outer window, a sandbox, or a backstage pass. michael@0: * May be null, but then the request cannot create a michael@0: * document. michael@0: * @param baseURI The base URI to use when resolving relative URIs. May be michael@0: * null. michael@0: */ michael@0: [noscript] void init(in nsIPrincipal principal, michael@0: in nsIScriptContext scriptContext, michael@0: in nsIGlobalObject globalObject, michael@0: in nsIURI baseURI); michael@0: michael@0: /** michael@0: * Upload process can be tracked by adding event listener to |upload|. michael@0: */ michael@0: readonly attribute nsIXMLHttpRequestUpload upload; michael@0: michael@0: /** michael@0: * Meant to be a script-only mechanism for setting a callback function. michael@0: * The attribute is expected to be JavaScript function object. When the michael@0: * readyState changes, the callback function will be called. michael@0: * This attribute should not be used from native code!! michael@0: * michael@0: * After the initial response, all event listeners will be cleared. michael@0: * // XXXbz what does that mean, exactly? michael@0: * michael@0: * Call open() before setting an onreadystatechange listener. michael@0: */ michael@0: [implicit_jscontext] attribute jsval onreadystatechange; michael@0: michael@0: /** michael@0: * If true, the request will be sent without cookie and authentication michael@0: * headers. michael@0: */ michael@0: readonly attribute boolean mozAnon; michael@0: michael@0: /** michael@0: * If true, the same origin policy will not be enforced on the request. michael@0: */ michael@0: readonly attribute boolean mozSystem; michael@0: }; michael@0: michael@0: [uuid(840d0d00-e83e-4a29-b3c7-67e96e90a499)] michael@0: interface nsIXHRSendable : nsISupports { michael@0: void getSendInfo(out nsIInputStream body, michael@0: out uint64_t contentLength, michael@0: out ACString contentType, michael@0: out ACString charset); michael@0: }; michael@0: michael@0: /** michael@0: * @deprecated michael@0: */ michael@0: [scriptable, uuid(8ae70a39-edf1-40b4-a992-472d23421c25)] michael@0: interface nsIJSXMLHttpRequest : nsISupports { michael@0: }; michael@0: michael@0: %{ C++ michael@0: #define NS_XMLHTTPREQUEST_CID \ michael@0: { /* d164e770-4157-11d4-9a42-000064657374 */ \ michael@0: 0xd164e770, 0x4157, 0x11d4, \ michael@0: {0x9a, 0x42, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74} } michael@0: #define NS_XMLHTTPREQUEST_CONTRACTID \ michael@0: "@mozilla.org/xmlextras/xmlhttprequest;1" michael@0: %}