firefox-dev 11.0+build1-0ubuntu4 / usr / share / idl / firefox / nsIXMLHttpRequest.idl

/* -*- 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 "nsIDOMEventTarget.idl"

interface nsIChannel;
interface nsIDOMDocument;
interface nsIDOMEventListener;
interface nsIPrincipal;
interface nsIScriptContext;
interface nsIURI;
interface nsIVariant;
interface nsPIDOMWindow;
interface nsIInputStream;
interface nsIDOMBlob;

%{C++
// for jsval
#include "jsapi.h"
%}

[scriptable, builtinclass, uuid(e2b59e48-3655-4429-a94c-b4332c346ba2)]
interface nsIXMLHttpRequestEventTarget : nsIDOMEventTarget {
  // event handler attributes
  attribute nsIDOMEventListener onabort;
  attribute nsIDOMEventListener onerror;
  attribute nsIDOMEventListener onload;
  attribute nsIDOMEventListener onloadstart;
  attribute nsIDOMEventListener onprogress;
  attribute nsIDOMEventListener onloadend;
};

[scriptable, builtinclass, uuid(db9357fc-edf7-42b2-aab2-c24ab19ece20)]
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(5cf8d518-51d0-4cd6-a69a-c3674c2de599)]
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;

  /**
   * 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.
   */
  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);

%{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.
   *              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
   */
  [optional_argc] void open(in AUTF8String 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 AUTF8String header, in AUTF8String value);

  /**
   * 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).
   */
  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;

  /**
   * 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 ownerWindow The associated window for the request. May be null.
   * @param baseURI The base URI to use when resolving relative URIs. May be
   *                null.
   */
  [noscript] void init(in nsIPrincipal principal,
                       in nsIScriptContext scriptContext,
                       in nsPIDOMWindow ownerWindow,
                       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.
   */
  attribute nsIDOMEventListener onreadystatechange;
};

[scriptable, uuid(840d0d00-e83e-4a29-b3c7-67e96e90a499)]
interface nsIXHRSendable : nsISupports {
  void getSendInfo(out nsIInputStream body,
                   out ACString contentType,
                   out ACString charset);
};

/**
 * @deprecated
 */
[deprecated, scriptable, uuid(423fdd3d-41c9-4149-8fe5-b14a1d3912a0)]
interface nsIJSXMLHttpRequest : nsISupports {
  /**
   * 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;
};

%{ 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"
%}