gecko-dev/content/base/public/nsIXMLHttpRequest.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Netscape 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/NPL/
 *
 * 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 Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"

interface nsIDOMDocument;
interface nsIDOMEventListener;
interface nsIHttpChannel;

[scriptable, uuid(b7215e70-4157-11d4-9a42-000064657374)]
interface nsIXMLHttpRequest : nsISupports {
  /**
   * Meant to be a script-only mechanism for setting a load event listener.
   * The attribute is expected to be JavaScript function object. When
   * the load event occurs, the function is invoked. 
   * This attribute should not be used from native code!!
   */
  attribute nsISupports onload;

  /**
   * Meant to be a script-only mechanism for setting an error event listener.
   * The attribute is expected to be JavaScript function object. When
   * the error event occurs, the function is invoked. 
   * This attribute should not be used from native code!!
   */
  attribute nsISupports onerror;

  /**
   * The HTTP request uses an HTTP channel in order to perform the
   * request.  This attribute represents the HTTP channel used
   * for the request.  NULL if the HTTP channel has not yet been
   * created.
   */
  readonly attribute nsIHttpChannel channel;

  /**
   * The response to the HTTP 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 HTTP request as text. 
   * NULL if the request is unsuccessful or
   * has not yet been sent.
   */
  readonly attribute wstring responseText;


  /**
   * The status of the response to the HTTP request.
   */
  readonly attribute unsigned long status;

  /**
   * The string representing the status of the response to the
   * HTTP request.
   */
  readonly attribute string statusText;

  /**
   * If the HTTP request has been sent already, this method will
   * abort the request.
   */
  void   abort();

  /**
   * Returns all of the HTTP response headers as a string string.
   * 
   * @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.
   *
   * @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.
   */
  string getResponseHeader(in string header);

  /**
   * Native (non-script) method to initialize a request. Note that
   * the HTTP request is not sent until the <code>send</code> method 
   * is invoked.
   *
   * @param method The HTTP method - either "POST" or "GET".
   * @param url The URL to which to send the request.
   * @param async 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.
   * @param user A username for authentication if necessary.
   * @param password A password for authentication if necessary.
   */
  [noscript] void   openRequest(in string method, 
                                in string url, 
                                in boolean async,
                                in string user, 
                                in string password);

  /**
   * Meant to be a script-only method for initializing a request.
   * The parameters are similar to the ones detailed in the
   * description of <code>openRequest</code>, but the last
   * 3 are optional.
   *
   * @param method The HTTP method - either "POST" or "GET".
   * @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
   */
  void   open(in string method, in string url);

  /**
   * Sends the HTTP request. If the request is asynchronous, returns
   * immediately after sending the request. If it is synchronous
   * returns only after the response has been received.
   *
   * @param body Either an instance of nsIDOMDocument, nsIInputStream
   *             or a string (nsISupportsWString 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, it is expected
   *             to contain the ContentType: and ContentLength: headers
   *             and trailing carriage-return/line-feed pairs.
   */
  void   send(in nsISupports body);

  /**
   * Sets a HTTP request header.
   *
   * @param header The name of the header to set in the request.
   * @param value The body of the header.
   */
  void   setRequestHeader(in string header, in string value);  
};

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