The Tor Browser: content/base/public/nsIXMLHttpRequest.idl@8bccb770b82d (annotated)

content/base/public/nsIXMLHttpRequest.idl@8bccb770b82d (annotated)

content/base/public/nsIXMLHttpRequest.idl

Wed, 31 Dec 2014 13:27:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 13:27:57 +0100
branch: TOR_BUG_3246
changeset 6: 8bccb770b82d
permissions: -rw-r--r--

Ignore runtime configuration files generated during quality assurance.

 /* -*- 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 nsIPrincipal;
 interface nsIScriptContext;
 interface nsIURI;
 interface nsIVariant;
 interface nsIGlobalObject;
 interface nsIInputStream;
 interface nsIDOMBlob;
 [scriptable, builtinclass, uuid(5ced7e7a-e2c3-4563-a57d-31b97ce64dc5)]
 interface nsIXMLHttpRequestEventTarget : nsIDOMEventTarget {
   // event handler attributes
 };
 [scriptable, builtinclass, uuid(df3796fa-d98a-4185-9dda-d2f2b56a5d38)]
 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(2e91e088-e9fa-4ba4-9887-2a0b7cf27a3e)]
 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);
   /**
    * 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 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 scriptContext The script context to use for the request. May 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.
    */
   [noscript] void init(in nsIPrincipal principal,
                        in nsIScriptContext scriptContext,
                        in nsIGlobalObject globalObject,
                        in nsIURI baseURI);
   /**
    * 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 */       \
 xd164e770, 0x4157, 0x11d4,                       \
  {0x9a, 0x42, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74} }
 #define NS_XMLHTTPREQUEST_CONTRACTID \
 "@mozilla.org/xmlextras/xmlhttprequest;1"
 %}

The Tor Browser / annotate

content/base/public/nsIXMLHttpRequest.idl@8bccb770b82d (annotated)

content/base/public/nsIXMLHttpRequest.idl