mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-30 05:35:31 +00:00
364 lines
13 KiB
Plaintext
364 lines
13 KiB
Plaintext
/* -*- 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(ac97e161-9f1d-4163-adc9-e9a59e18682c)]
|
|
interface nsIXMLHttpRequestEventTarget : nsIDOMEventTarget {
|
|
// event handler attributes
|
|
[implicit_jscontext] attribute jsval onabort;
|
|
[implicit_jscontext] attribute jsval onerror;
|
|
[implicit_jscontext] attribute jsval onload;
|
|
[implicit_jscontext] attribute jsval onloadstart;
|
|
[implicit_jscontext] attribute jsval onprogress;
|
|
[implicit_jscontext] attribute jsval ontimeout;
|
|
[implicit_jscontext] attribute jsval onloadend;
|
|
};
|
|
|
|
[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;
|
|
};
|
|
|
|
[scriptable, 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 */ \
|
|
0xd164e770, 0x4157, 0x11d4, \
|
|
{0x9a, 0x42, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74} }
|
|
#define NS_XMLHTTPREQUEST_CONTRACTID \
|
|
"@mozilla.org/xmlextras/xmlhttprequest;1"
|
|
%}
|