1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/base/public/nsIXMLHttpRequest.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,356 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsIDOMEventTarget.idl"
1.10 +
1.11 +interface nsIChannel;
1.12 +interface nsIDOMDocument;
1.13 +interface nsIDOMEventListener;
1.14 +interface nsIPrincipal;
1.15 +interface nsIScriptContext;
1.16 +interface nsIURI;
1.17 +interface nsIVariant;
1.18 +interface nsIGlobalObject;
1.19 +interface nsIInputStream;
1.20 +interface nsIDOMBlob;
1.21 +
1.22 +[scriptable, builtinclass, uuid(5ced7e7a-e2c3-4563-a57d-31b97ce64dc5)]
1.23 +interface nsIXMLHttpRequestEventTarget : nsIDOMEventTarget {
1.24 + // event handler attributes
1.25 +};
1.26 +
1.27 +[scriptable, builtinclass, uuid(df3796fa-d98a-4185-9dda-d2f2b56a5d38)]
1.28 +interface nsIXMLHttpRequestUpload : nsIXMLHttpRequestEventTarget {
1.29 + // for future use
1.30 +};
1.31 +
1.32 +/**
1.33 + * Mozilla's XMLHttpRequest is modelled after Microsoft's IXMLHttpRequest
1.34 + * object. The goal has been to make Mozilla's version match Microsoft's
1.35 + * version as closely as possible, but there are bound to be some differences.
1.36 + *
1.37 + * In general, Microsoft's documentation for IXMLHttpRequest can be used.
1.38 + * Mozilla's interface definitions provide some additional documentation. The
1.39 + * web page to look at is http://www.mozilla.org/xmlextras/
1.40 + *
1.41 + * Mozilla's XMLHttpRequest object can be created in JavaScript like this:
1.42 + * new XMLHttpRequest()
1.43 + * compare to Internet Explorer:
1.44 + * new ActiveXObject("Msxml2.XMLHTTP")
1.45 + *
1.46 + * From JavaScript, the methods and properties visible in the XMLHttpRequest
1.47 + * object are a combination of nsIXMLHttpRequest and nsIJSXMLHttpRequest;
1.48 + * there is no need to differentiate between those interfaces.
1.49 + *
1.50 + * From native code, the way to set up onload and onerror handlers is a bit
1.51 + * different. Here is a comment from Johnny Stenback <jst@netscape.com>:
1.52 + *
1.53 + * The mozilla implementation of nsIXMLHttpRequest implements the interface
1.54 + * nsIDOMEventTarget and that's how you're supported to add event listeners.
1.55 + * Try something like this:
1.56 + *
1.57 + * nsCOMPtr<nsIDOMEventTarget> target(do_QueryInterface(myxmlhttpreq));
1.58 + *
1.59 + * target->AddEventListener(NS_LITERAL_STRING("load"), mylistener,
1.60 + * PR_FALSE)
1.61 + *
1.62 + * where mylistener is your event listener object that implements the
1.63 + * interface nsIDOMEventListener.
1.64 + *
1.65 + * The 'onload', 'onerror', and 'onreadystatechange' attributes moved to
1.66 + * nsIJSXMLHttpRequest, but if you're coding in C++ you should avoid using
1.67 + * those.
1.68 + *
1.69 + * Conclusion: Do not use event listeners on XMLHttpRequest from C++, unless
1.70 + * you're aware of all the security implications. And then think twice about
1.71 + * it.
1.72 + */
1.73 +[scriptable, uuid(2e91e088-e9fa-4ba4-9887-2a0b7cf27a3e)]
1.74 +interface nsIXMLHttpRequest : nsISupports
1.75 +{
1.76 + /**
1.77 + * The request uses a channel in order to perform the
1.78 + * request. This attribute represents the channel used
1.79 + * for the request. NULL if the channel has not yet been
1.80 + * created.
1.81 + *
1.82 + * Mozilla only. Requires elevated privileges to access.
1.83 + */
1.84 + readonly attribute nsIChannel channel;
1.85 +
1.86 + /**
1.87 + * The response to the request is parsed as if it were a
1.88 + * text/xml stream. This attributes represents the response as
1.89 + * a DOM Document object. NULL if the request is unsuccessful or
1.90 + * has not yet been sent.
1.91 + */
1.92 + readonly attribute nsIDOMDocument responseXML;
1.93 +
1.94 + /**
1.95 + * The response to the request as text.
1.96 + * NULL if the request is unsuccessful or
1.97 + * has not yet been sent.
1.98 + */
1.99 + readonly attribute AString responseText;
1.100 +
1.101 + /**
1.102 + * Determine a response format which response attribute returns.
1.103 + * empty string (initial value) or "text": as text.
1.104 + * "arraybuffer": as a typed array ArrayBuffer.
1.105 + * "blob": as a File API Blob.
1.106 + * "document": as a DOM Document object.
1.107 + */
1.108 + attribute AString responseType;
1.109 +
1.110 + /**
1.111 + * The response to the request as a specified format by responseType.
1.112 + * NULL if the request is unsuccessful or
1.113 + * has not yet been sent.
1.114 + */
1.115 + [implicit_jscontext] readonly attribute jsval /* any */ response;
1.116 +
1.117 + /**
1.118 + * The status of the response to the request for HTTP requests.
1.119 + */
1.120 + // XXX spec says unsigned short
1.121 + readonly attribute unsigned long status;
1.122 +
1.123 + /**
1.124 + * The string representing the status of the response for
1.125 + * HTTP requests.
1.126 + */
1.127 + readonly attribute ACString statusText;
1.128 +
1.129 + /**
1.130 + * If the request has been sent already, this method will
1.131 + * abort the request.
1.132 + */
1.133 + [binaryname(SlowAbort)] void abort();
1.134 +
1.135 + /**
1.136 + * Returns all of the response headers as a string for HTTP
1.137 + * requests.
1.138 + *
1.139 + * @returns A string containing all of the response headers.
1.140 + * The empty string if the response has not yet been received.
1.141 + */
1.142 + ACString getAllResponseHeaders();
1.143 +
1.144 + /**
1.145 + * Returns the text of the header with the specified name for
1.146 + * HTTP requests.
1.147 + *
1.148 + * @param header The name of the header to retrieve
1.149 + * @returns A string containing the text of the header specified.
1.150 + * NULL if the response has not yet been received or the
1.151 + * header does not exist in the response.
1.152 + */
1.153 + ACString getResponseHeader(in ACString header);
1.154 +
1.155 +%{C++
1.156 + // note this is NOT virtual so this won't muck with the vtable!
1.157 + inline nsresult Open(const nsACString& method, const nsACString& url,
1.158 + bool async, const nsAString& user,
1.159 + const nsAString& password) {
1.160 + return Open(method, url, async, user, password, 3);
1.161 + }
1.162 +%}
1.163 + /**
1.164 + * Meant to be a script-only method for initializing a request.
1.165 + *
1.166 + * If there is an "active" request (that is, if open() has been called
1.167 + * already), this is equivalent to calling abort() and then open().
1.168 + *
1.169 + * @param method The HTTP method - either "POST" or "GET". Ignored
1.170 + * if the URL is not a HTTP URL.
1.171 + * @param url The URL to which to send the request.
1.172 + * @param async (optional) Whether the request is synchronous or
1.173 + * asynchronous i.e. whether send returns only after
1.174 + * the response is received or if it returns immediately after
1.175 + * sending the request. In the latter case, notification
1.176 + * of completion is sent through the event listeners.
1.177 + * The default value is true.
1.178 + * @param user (optional) A username for authentication if necessary.
1.179 + * The default value is the empty string
1.180 + * @param password (optional) A password for authentication if necessary.
1.181 + * The default value is the empty string
1.182 + */
1.183 + [optional_argc] void open(in ACString method, in AUTF8String url,
1.184 + [optional] in boolean async,
1.185 + [optional,Undefined(Empty)] in DOMString user,
1.186 + [optional,Undefined(Empty)] in DOMString password);
1.187 +
1.188 + /**
1.189 + * Sends the request. If the request is asynchronous, returns
1.190 + * immediately after sending the request. If it is synchronous
1.191 + * returns only after the response has been received.
1.192 + *
1.193 + * All event listeners must be set before calling send().
1.194 + *
1.195 + * After the initial response, all event listeners will be cleared.
1.196 + * // XXXbz what does that mean, exactly?
1.197 + *
1.198 + * @param body Either an instance of nsIDOMDocument, nsIInputStream
1.199 + * or a string (nsISupportsString in the native calling
1.200 + * case). This is used to populate the body of the
1.201 + * HTTP request if the HTTP request method is "POST".
1.202 + * If the parameter is a nsIDOMDocument, it is serialized.
1.203 + * If the parameter is a nsIInputStream, then it must be
1.204 + * compatible with nsIUploadChannel.setUploadStream, and a
1.205 + * Content-Length header will be added to the HTTP request
1.206 + * with a value given by nsIInputStream.available. Any
1.207 + * headers included at the top of the stream will be
1.208 + * treated as part of the message body. The MIME type of
1.209 + * the stream should be specified by setting the Content-
1.210 + * Type header via the setRequestHeader method before
1.211 + * calling send.
1.212 + */
1.213 + void send([optional] in nsIVariant body);
1.214 +
1.215 + /**
1.216 + * A variant of the send() method used to send binary data.
1.217 + *
1.218 + * @param body The request body as a DOM string. The string data will be
1.219 + * converted to a single-byte string by truncation (i.e., the
1.220 + * high-order byte of each character will be discarded).
1.221 + */
1.222 + void sendAsBinary(in DOMString body);
1.223 +
1.224 + /**
1.225 + * Sets a HTTP request header for HTTP requests. You must call open
1.226 + * before setting the request headers.
1.227 + *
1.228 + * @param header The name of the header to set in the request.
1.229 + * @param value The body of the header.
1.230 + */
1.231 + void setRequestHeader(in ACString header, in ACString value);
1.232 +
1.233 + /**
1.234 + * The amount of milliseconds a request can take before being terminated.
1.235 + * Initially zero. Zero means there is no timeout.
1.236 + */
1.237 + attribute unsigned long timeout;
1.238 +
1.239 + /**
1.240 + * The state of the request.
1.241 + *
1.242 + * Possible values:
1.243 + * 0 UNSENT open() has not been called yet.
1.244 + * 1 OPENED send() has not been called yet.
1.245 + * 2 HEADERS_RECEIVED
1.246 + * send() has been called, headers and status are available.
1.247 + * 3 LOADING Downloading, responseText holds the partial data.
1.248 + * 4 DONE Finished with all operations.
1.249 + */
1.250 + const unsigned short UNSENT = 0;
1.251 + const unsigned short OPENED = 1;
1.252 + const unsigned short HEADERS_RECEIVED = 2;
1.253 + const unsigned short LOADING = 3;
1.254 + const unsigned short DONE = 4;
1.255 + readonly attribute unsigned short readyState;
1.256 +
1.257 + /**
1.258 + * Override the mime type returned by the server (if any). This may
1.259 + * be used, for example, to force a stream to be treated and parsed
1.260 + * as text/xml, even if the server does not report it as such. This
1.261 + * must be done before the <code>send</code> method is invoked.
1.262 + *
1.263 + * @param mimetype The type used to override that returned by the server
1.264 + * (if any).
1.265 + */
1.266 + [binaryname(SlowOverrideMimeType)] void overrideMimeType(in DOMString mimetype);
1.267 +
1.268 + /**
1.269 + * Set to true if this is a background service request. This will
1.270 + * prevent a load group being associated with the request, and
1.271 + * suppress any security dialogs from being shown * to the user.
1.272 + * In the cases where one of those dialogs would be shown, the request
1.273 + * will simply fail instead.
1.274 + */
1.275 + attribute boolean mozBackgroundRequest;
1.276 +
1.277 + /**
1.278 + * When set to true attempts to make cross-site Access-Control requests
1.279 + * with credentials such as cookies and authorization headers.
1.280 + *
1.281 + * Never affects same-site requests.
1.282 + *
1.283 + * Defaults to false.
1.284 + */
1.285 + attribute boolean withCredentials;
1.286 +
1.287 + /**
1.288 + * Initialize the object for use from C++ code with the principal, script
1.289 + * context, and owner window that should be used.
1.290 + *
1.291 + * @param principal The principal to use for the request. This must not be
1.292 + * null.
1.293 + * @param scriptContext The script context to use for the request. May be
1.294 + * null.
1.295 + * @param globalObject The associated global for the request. Can be the
1.296 + * outer window, a sandbox, or a backstage pass.
1.297 + * May be null, but then the request cannot create a
1.298 + * document.
1.299 + * @param baseURI The base URI to use when resolving relative URIs. May be
1.300 + * null.
1.301 + */
1.302 + [noscript] void init(in nsIPrincipal principal,
1.303 + in nsIScriptContext scriptContext,
1.304 + in nsIGlobalObject globalObject,
1.305 + in nsIURI baseURI);
1.306 +
1.307 + /**
1.308 + * Upload process can be tracked by adding event listener to |upload|.
1.309 + */
1.310 + readonly attribute nsIXMLHttpRequestUpload upload;
1.311 +
1.312 + /**
1.313 + * Meant to be a script-only mechanism for setting a callback function.
1.314 + * The attribute is expected to be JavaScript function object. When the
1.315 + * readyState changes, the callback function will be called.
1.316 + * This attribute should not be used from native code!!
1.317 + *
1.318 + * After the initial response, all event listeners will be cleared.
1.319 + * // XXXbz what does that mean, exactly?
1.320 + *
1.321 + * Call open() before setting an onreadystatechange listener.
1.322 + */
1.323 + [implicit_jscontext] attribute jsval onreadystatechange;
1.324 +
1.325 + /**
1.326 + * If true, the request will be sent without cookie and authentication
1.327 + * headers.
1.328 + */
1.329 + readonly attribute boolean mozAnon;
1.330 +
1.331 + /**
1.332 + * If true, the same origin policy will not be enforced on the request.
1.333 + */
1.334 + readonly attribute boolean mozSystem;
1.335 +};
1.336 +
1.337 +[uuid(840d0d00-e83e-4a29-b3c7-67e96e90a499)]
1.338 +interface nsIXHRSendable : nsISupports {
1.339 + void getSendInfo(out nsIInputStream body,
1.340 + out uint64_t contentLength,
1.341 + out ACString contentType,
1.342 + out ACString charset);
1.343 +};
1.344 +
1.345 +/**
1.346 + * @deprecated
1.347 + */
1.348 +[scriptable, uuid(8ae70a39-edf1-40b4-a992-472d23421c25)]
1.349 +interface nsIJSXMLHttpRequest : nsISupports {
1.350 +};
1.351 +
1.352 +%{ C++
1.353 +#define NS_XMLHTTPREQUEST_CID \
1.354 + { /* d164e770-4157-11d4-9a42-000064657374 */ \
1.355 + 0xd164e770, 0x4157, 0x11d4, \
1.356 + {0x9a, 0x42, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74} }
1.357 +#define NS_XMLHTTPREQUEST_CONTRACTID \
1.358 +"@mozilla.org/xmlextras/xmlhttprequest;1"
1.359 +%}
