/* -*- 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 nsIChannel;
[scriptable, uuid(b7215e70-4157-11d4-9a42-000064657374)]
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.
*/
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 wstring responseText;
/**
* 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 string 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.
*
* @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.
*/
string getResponseHeader(in string header);
/**
* Native (non-script) method to initialize a request. Note that
* the request is not sent until the send method
* is invoked.
*
* @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 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 openRequest, but the last
* 3 are optional.
*
* @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
*/
void open(in string method, in string url);
/**
* 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.
*
* @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 for HTTP requests.
*
* @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);
};
[scriptable, uuid(9deabc90-28d5-41d3-a660-474f2254f4ba)]
interface nsIJSXMLHttpRequest : 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 nsIDOMEventListener 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 nsIDOMEventListener onerror;
};
%{ 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"
%}