Annotation of 2006/webapi/XMLHttpRequest/Overview.html, revision 1.40
1.1 avankest 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
1.2 avankest 2:
1.25 avankest 3: <html lang=en-US>
1.1 avankest 4: <head>
5: <title>The XMLHttpRequest Object</title>
1.2 avankest 6:
1.20 avankest 7: <style type="text/css">
8: pre.idl { border:solid thin; background:#eee; color:#000; padding:0.5em }
9: pre.idl :link, pre.idl :visited { color:inherit; background:transparent }
10: div.example { margin-left:1em; padding-left:1em; border-left:double; color:#222; background:#fcfcfc }
11: p.note { margin-left:2em; font-weight:bold; font-style:italic; color:#008000 }
12: p.note::before { content:"Note: " }
13: p.issue { padding:.5em; border:solid #f00 }
14: p.issue::before { content:"Issue: " }
15: em.ct { text-transform:lowercase; font-variant:small-caps; font-style:normal }
16: dfn { font-weight:bold; font-style:normal }
17: code { color:orangered }
18: code :link, code :visited { color:inherit }
19: </style>
1.25 avankest 20: <link href="http://www.w3.org/StyleSheets/TR/base" rel=stylesheet>
1.2 avankest 21:
1.1 avankest 22: <body>
1.25 avankest 23: <div class=head>
24: <p><a href="http://www.w3.org/"><img alt=W3C height=48
25: src="http://www.w3.org/Icons/w3c_home" width=72></a></p>
1.2 avankest 26:
1.25 avankest 27: <h1 class=head id=the-xmlhttprequest>The <code
1.14 avankest 28: title="">XMLHttpRequest</code> Object</h1>
1.2 avankest 29:
1.25 avankest 30: <h2 class="no-num no-toc" id=pagesubtitle>Editors' draft
1.35 avankest 31: <!--W3C Working Draft--> 13 February 2007</h2>
1.2 avankest 32:
1.1 avankest 33: <dl>
1.14 avankest 34: <dt>This Version:
1.2 avankest 35:
36: <dd><a
1.35 avankest 37: href="http://www.w3.org/TR/2007/WD-XMLHttpRequest-20070213">http://www.w3.org/TR/2007/WD-XMLHttpRequest-20070213/</a>
1.2 avankest 38:
1.14 avankest 39: <dt>Latest Version:
1.2 avankest 40:
41: <dd><a
42: href="http://www.w3.org/TR/XMLHttpRequest/">http://www.w3.org/TR/XMLHttpRequest/</a>
43:
1.14 avankest 44: <dt>Previous Versions:
1.2 avankest 45:
46: <dd><a
1.25 avankest 47: href="http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060927/">http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060927/</a>
48:
49: <dd><a
1.2 avankest 50: href="http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060619/">http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060619/</a>
51:
52: <dd><a
53: href="http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060405/">http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060405/</a>
54:
55: <dt>Editor:
56:
57: <dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a> (<a
58: href="http://www.opera.com/">Opera Software ASA</a>) <<a
59: href="mailto:annevk@opera.com">annevk@opera.com</a>>
1.1 avankest 60: </dl>
1.2 avankest 61:
1.25 avankest 62: <p class=copyright><a
1.2 avankest 63: href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
64: ©2006 <a href="http://www.w3.org/"><abbr title="World Wide Web
65: Consortium">W3C</abbr></a><sup>®</sup> (<a
66: href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of
67: Technology">MIT</abbr></a>, <a href="http://www.ercim.org/"><abbr
68: title="European Research Consortium for Informatics and
69: Mathematics">ERCIM</abbr></a>, <a
70: href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
71: href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
72: <a
73: href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
74: and <a
75: href="http://www.w3.org/Consortium/Legal/copyright-documents">document
76: use</a> rules apply.</p>
1.1 avankest 77: </div>
1.2 avankest 78:
79: <hr>
80:
1.25 avankest 81: <h2 class="no-num no-toc" id=specabstract>Abstract</h2>
1.2 avankest 82:
1.25 avankest 83: <p>The <code title="">XMLHttpRequest</code> Object specification defines an
84: <abbr title="Application Programming Interface">API</abbr> that provides
85: scripted client functionality for transferring data between a client and a
86: server.
87:
88: <h2 class="no-num no-toc" id=sotd>Status of this Document</h2>
1.2 avankest 89:
90: <p><em>This section describes the status of this document at the time of
91: its publication. Other documents may supersede this document. A list of
92: current W3C publications and the latest revision of this technical report
93: can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
94: index</a> at http://www.w3.org/TR/.</em>
95:
1.38 avankest 96: <p>This is the 13 February 2007 <strong>Last Call</strong> Working Draft of
97: The <code title="">XMLHttpRequest</code> Object specifcation. This
98: document is produced by the <a href="http://www.w3.org/2006/webapi/">Web
99: API Working Group</a>, part of the <a
100: href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients Activity</a>
101: in the W3C <a href="http://www.w3.org/Interaction/">Interaction
102: Domain</a>.
1.2 avankest 103:
1.38 avankest 104: <p>Please send comments to <a
1.27 avankest 105: href="mailto:public-webapi@w3.org">public-webapi@w3.org</a> with either
1.30 avankest 106: <samp>[XHR]</samp> or <samp title="">[XMLHttpRequest]</samp> at the start
107: of the subject line. <a
1.2 avankest 108: href="http://lists.w3.org/Archives/Public/public-webapi/">Archives</a> of
1.37 avankest 109: this list are available.
1.2 avankest 110:
111: <p>Publication as a Working Draft does not imply endorsement by the W3C
112: Membership. This is a draft document and may be updated, replaced or
113: obsoleted by other documents at any time. It is inappropriate to cite this
114: document as other than work in progress.
115:
116: <p>This document was produced by a group operating under the <a
117: href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
118: 2004 W3C Patent Policy</a>. This document is informative only. W3C
119: maintains a <a href="http://www.w3.org/2004/01/pp-impl/38482/status"
1.25 avankest 120: rel=disclosure>public list of any patent disclosures</a> made in
1.2 avankest 121: connection with the deliverables of the group; that page also includes
122: instructions for disclosing a patent. An individual who has actual
123: knowledge of a patent which the individual believes contains <a
124: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
125: Claim(s)</a> must disclose the information in accordance with <a
126: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
127: 6 of the W3C Patent Policy</a>.
128:
1.25 avankest 129: <h2 class="no-num no-toc" id=toc>Table of Contents</h2>
1.2 avankest 130: <!--begin-toc-->
131:
1.25 avankest 132: <ul class=toc>
133: <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
134: <ul class=toc>
1.31 avankest 135: <li><a href="#examples"><span class=secno>1.1. </span>Examples of
1.2 avankest 136: Usage</a>
137:
1.31 avankest 138: <li><a href="#conformance"><span class=secno>1.2. </span>Conformance</a>
1.25 avankest 139:
1.31 avankest 140: <ul class=toc>
141: <li><a href="#dependencies"><span class=secno>1.2.1.
1.32 avankest 142: </span>Dependencies</a>
1.31 avankest 143: </ul>
1.2 avankest 144:
1.31 avankest 145: <li><a href="#extensibility"><span class=secno>1.3.
1.2 avankest 146: </span>Extensibility</a>
147: </ul>
148:
1.25 avankest 149: <li><a href="#xmlhttprequest"><span class=secno>2. </span>The <code
1.16 avankest 150: title="">XMLHttpRequest</code> Object</a>
1.25 avankest 151: <ul class=toc>
152: <li><a href="#xmlhttprequest-members"><span class=secno>2.1.
1.33 avankest 153: </span>Members of the <code title="">XMLHttpRequest</code> Object</a>
1.2 avankest 154:
1.33 avankest 155: <li><a href="#events"><span class=secno>2.2. </span>Events for the <code
156: title="">XMLHttpRequest</code> Object</a>
157:
158: <li><a href="#exceptions"><span class=secno>2.3. </span>Exceptions for
159: the <code title="">XMLHttpRequest</code> Object</a>
1.11 avankest 160: </ul>
1.2 avankest 161:
1.31 avankest 162: <li class=no-num><a href="#notcovered">Not in this Specification</a>
163:
1.25 avankest 164: <li class=no-num><a href="#bibref">References</a>
1.2 avankest 165:
1.25 avankest 166: <li class=no-num><a href="#acknowledgements">Acknowledgements</a>
1.2 avankest 167: </ul>
168: <!--end-toc-->
169:
1.25 avankest 170: <h2 id=introduction><span class=secno>1. </span>Introduction</h2>
1.2 avankest 171:
172: <p><em>This section is non-normative.</em>
173:
1.27 avankest 174: <p>The <code><a href="#xmlhttprequest0">XMLHttpRequest</a></code> object
1.25 avankest 175: implements an interface exposed by a scripting engine that allows scripts
176: to perform HTTP client functionality, such as submitting form data or
177: loading data from a server.
1.2 avankest 178:
179: <p>The name of the object is <code><a
1.27 avankest 180: href="#xmlhttprequest0">XMLHttpRequest</a></code> for compatibility with
1.25 avankest 181: the web, though each component of this name is potentially misleading.
182: First, the object is data transport agnostic — it supports any data
183: format, including XML. Second, it can be used to make requests over both
184: HTTP and HTTPS (some implementations support protocols in addition to HTTP
185: and HTTPS, but that functionality is not covered by this specification).
186: Finally, it supports "requests" in a broad sense of the term as it
187: pertains to HTTP; namely all activity involved with HTTP requests or
188: responses for the defined HTTP methods.
1.2 avankest 189:
1.31 avankest 190: <h3 id=examples><span class=secno>1.1. </span>Examples of Usage</h3>
1.2 avankest 191:
192: <p><em>This section is non-normative.</em>
193:
1.34 avankest 194: <p>Some [<cite><a href="#ref-ecmascript">ECMAScript</a></cite>] examples
195: are listed in the specification. In addition, you can find some below.
1.2 avankest 196:
1.25 avankest 197: <div class=example>
1.18 avankest 198: <p>Some simple code to do something with data from an XML document fetched
199: over the network:</p>
200:
201: <pre>function test(data) {
202: // taking care of data
203: }
204:
205: function handler() {
206: if(this.readyState == 4 && this.status == 200) {
207: // so far so good
208: if(this.responseXML != null && this.responseXML.getElementById('test').firstChild.data)
209: // success!
210: test(this.responseXML.getElementById('test').firstChild.data);
211: else
212: test(null);
213: } else if (this.readyState == 4 && this.status != 200) {
214: // fetched the wrong page or network error...
215: test(null);
216: }
217: }
218:
219: var client = new XMLHttpRequest();
220: client.onreadystatechange = handler;
221: client.open("GET", "test.xml");
222: client.send();</pre>
223:
224: <p>If you just want to ping the server with a message you could do
225: something like:</p>
226:
227: <pre>function ping(message) {
228: var client = new XMLHttpRequest();
229: client.open("POST", "/ping");
230: client.send(message);
231: }</pre>
232:
233: <p>Or if you want to check the status of a document on the server:</p>
234:
235: <pre>function fetchStatus(address) {
236: var client = new XMLHttpRequest();
237: client.onreadystatechange = function() {
238: // in case of network errors this might not give reliable results
239: if(this.readyState == 4)
240: returnStatus(this.status);
241: }
242: client.open("HEAD", address);
243: client.send();
244: }</pre>
245: </div>
1.2 avankest 246:
1.31 avankest 247: <h3 id=conformance><span class=secno>1.2. </span>Conformance</h3>
1.2 avankest 248:
1.29 avankest 249: <p>Everything in this specification is normative except for diagrams,
1.2 avankest 250: examples, notes and sections marked non-normative.
251:
1.25 avankest 252: <p>The key words <em class=ct>must</em>, <em class=ct>must not</em>, <em
253: class=ct>required</em>, <em class=ct>shall</em>, <em class=ct>shall
254: not</em>, <em class=ct>should</em>, <em class=ct>should not</em>, <em
255: class=ct>recommended</em>, <em class=ct>may</em> and <em
256: class=ct>optional</em> in this document are to be interpreted as described
257: in RFC 2119 [<cite><a href="#RFC2119">RFC2119</a></cite>].
1.2 avankest 258:
259: <p>This specification defines the following classes of products:
260:
261: <dl>
1.25 avankest 262: <dt><dfn id=conforming>conforming implementation</dfn>
1.2 avankest 263:
1.13 avankest 264: <dd>A user agent that implements all interfaces described in this
1.25 avankest 265: specification and follows all <em class=ct>must</em>-, <em
1.29 avankest 266: class=ct>required</em>- and <em class=ct>shall</em>-level of criteria in
1.25 avankest 267: this specification.
1.2 avankest 268:
1.25 avankest 269: <dt><dfn id=conforming0>conforming document</dfn>
1.2 avankest 270:
1.25 avankest 271: <dd>A document that follows all <em class=ct>must</em>-, <em
1.29 avankest 272: class=ct>required</em>- and <em class=ct>shall</em>-level of criteria in
1.25 avankest 273: this specification that apply to document authors.
1.2 avankest 274:
1.25 avankest 275: <dt><dfn id=conforming1>conforming authoring tool</dfn>
1.2 avankest 276:
277: <dd>One that produces conforming documents.
278: </dl>
279:
1.32 avankest 280: <h4 id=dependencies><span class=secno>1.2.1. </span>Dependencies</h4>
1.2 avankest 281:
1.31 avankest 282: <p>This specification relies on several underlying specifications.
1.2 avankest 283:
1.31 avankest 284: <dl>
285: <dt>DOM
1.2 avankest 286:
1.31 avankest 287: <dd>
288: <p>Implementations <em class=ct>must</em> support some version of DOM
1.39 avankest 289: Events because this specification uses some of the features defined in
290: that specification. [<cite><a href="#DOM3EV">DOM3Events</a></cite>]</p>
291:
292: <p>Implementations <em class=ct>must</em> support some version of DOM
293: Core because this specification uses some of the features defined in
294: that specification. [<cite><a href="#DOM3">DOM3Core</a></cite>]</p>
1.31 avankest 295:
296: <p>Implementations <em class=ct>must</em> support some version of the
1.39 avankest 297: Window Object because some of the functionality in this specification
298: relies on it. [<cite><a href="#ref-window">Window</a></cite>]</p>
1.2 avankest 299:
1.31 avankest 300: <dt>HTTP
1.11 avankest 301:
1.31 avankest 302: <dd>
303: <p>Implementations <em class=ct>must</em> support the <code>http</code>
304: scheme defined in HTTP. Other requirements regarding HTTP are made
305: throughout the specification [<cite><a
306: href="#RFC2616">RFC2616</a></cite>].</p>
307: </dl>
1.2 avankest 308:
1.31 avankest 309: <h3 id=extensibility><span class=secno>1.3. </span>Extensibility</h3>
1.2 avankest 310:
1.31 avankest 311: <p><em>This section is non-normative.</em>
1.2 avankest 312:
1.31 avankest 313: <p>Extensions of the APIs defined by this specification are <em>strongly
314: discouraged</em>. User agents, Working Groups and other interested parties
1.35 avankest 315: should discuss extensions on a relevant public forum, preferably <a
1.31 avankest 316: href="mailto:public-webapi@w3.org">public-webapi@w3.org</a>.
1.2 avankest 317:
1.25 avankest 318: <h2 id=xmlhttprequest><span class=secno>2. </span>The <code
1.16 avankest 319: title="">XMLHttpRequest</code> Object</h2>
1.2 avankest 320:
1.27 avankest 321: <p>The <code><a href="#xmlhttprequest0">XMLHttpRequest</a></code> interface
1.2 avankest 322: may be used to allow scripts to programmatically connect to their
323: originating server via HTTP.
324:
325: <p>Objects implementing the <code><a
1.27 avankest 326: href="#xmlhttprequest0">XMLHttpRequest</a></code> interface <em
1.25 avankest 327: class=ct>must</em> also implement the <code>EventTarget</code> interface
1.18 avankest 328: [<cite><a href="#DOM3EV">DOM3Events</a></cite>].
1.2 avankest 329:
1.18 avankest 330: <p>In [<cite><a href="#ref-ecmascript">ECMAScript</a></cite>], an instance
1.27 avankest 331: of <code><a href="#xmlhttprequest0">XMLHttpRequest</a></code> can be
1.18 avankest 332: created using the <code title="">XMLHttpRequest()</code> constructor:
1.2 avankest 333:
1.25 avankest 334: <div class=example>
1.2 avankest 335: <pre>var client = new XMLHttpRequest();</pre>
1.1 avankest 336: </div>
1.2 avankest 337:
1.39 avankest 338: <p>When the constructor is invoked a pointer to the <code
339: title="">Window</code> object which initially had <code
340: title="">XMLHttpRequest</code> as an attribute of which the constructor
341: was invoked <em class=ct>must</em> be stored on the newly created object,
342: called the <dfn id=window-pointer title="Window
343: pointer"><code>Window</code> pointer</dfn>. This <a href="#window-pointer"
344: title="Window pointer">pointer</a> <em class=ct>must</em> persist even if
345: the browsing context in which the <code title="">Window</code> is located
346: is destroyed (by removing it from a parent browsing context, for
347: instance).
1.29 avankest 348:
349: <p>The term browsing context is defined by the <cite>Window Object
1.39 avankest 350: 1.0</cite> specification. [<cite><a href="#ref-window">Window</a></cite>]</p>
1.29 avankest 351: <!-- XXX if the document object changes in the browsing context you get an
1.35 avankest 352: exception in some implementations. -->
1.2 avankest 353:
1.25 avankest 354: <h3 id=xmlhttprequest-members><span class=secno>2.1. </span>Members of the
1.33 avankest 355: <code title="">XMLHttpRequest</code> Object</h3>
1.11 avankest 356:
1.27 avankest 357: <pre class=idl>interface <dfn id=xmlhttprequest0>XMLHttpRequest</dfn> {
1.25 avankest 358: attribute EventListener <a href="#dfn-onreadystatechange">onreadystatechange</a>;
359: readonly attribute unsigned short <a href="#dfn-readystate">readyState</a>;
360: void <a href="#dfn-open">open</a>(in DOMString <var>method</var>, in DOMString <var>url</var>);
361: void <a href="#dfn-open">open</a>(in DOMString <var>method</var>, in DOMString <var>url</var>, in boolean <var>async</var>);
362: void <a href="#dfn-open">open</a>(in DOMString <var>method</var>, in DOMString <var>url</var>, in boolean <var>async</var>, in DOMString <var>user</var>);
363: void <a href="#dfn-open">open</a>(in DOMString <var>method</var>, in DOMString <var>url</var>, in boolean <var>async</var>, in DOMString <var>user</var>, in DOMString <var>password</var>);
364: void <a href="#dfn-setrequestheader">setRequestHeader</a>(in DOMString <var>header</var>, in DOMString <var>value</var>);
365: void <a href="#dfn-send">send</a>();
366: void <a href="#dfn-send">send</a>(in DOMString <var>data</var>);
367: void <a href="#dfn-send">send</a>(in Document <var>data</var>);
368: void <a href="#dfn-abort">abort</a>();
369: DOMString <a href="#dfn-getallresponseheaders">getAllResponseHeaders</a>();
370: DOMString <a href="#dfn-getresponseheader">getResponseHeader</a>(in DOMString <var>header</var>);
371: readonly attribute DOMString <a href="#dfn-responsetext">responseText</a>;
372: readonly attribute Document <a href="#dfn-responsexml">responseXML</a>;
373: readonly attribute unsigned short <a href="#dfn-status">status</a>;
374: readonly attribute DOMString <a href="#dfn-statustext">statusText</a>;
1.5 avankest 375: };</pre>
1.2 avankest 376:
1.6 avankest 377: <dl>
1.25 avankest 378: <dt><dfn id=dfn-onreadystatechange><code>onreadystatechange</code></dfn>
1.2 avankest 379: of type <code>EventListener</code>
380:
381: <dd>
382: <p>An attribute that takes an <code>EventListener</code> as value that
1.25 avankest 383: <em class=ct>must</em> be invoked when <code><a
1.2 avankest 384: href="#dfn-readystatechange">readystatechange</a></code> is dispatched
385: on the object implementing the <code><a
1.27 avankest 386: href="#xmlhttprequest0">XMLHttpRequest</a></code> interface. Its initial
1.25 avankest 387: value <em class=ct>must</em> be <code>null</code>.</p>
1.2 avankest 388:
1.25 avankest 389: <dt><dfn id=dfn-readystate><code>readyState</code></dfn> of type
1.2 avankest 390: <code>unsigned short</code>, readonly
391:
392: <dd>
1.25 avankest 393: <p>The state of the object. The attribute <em class=ct>must</em> be one
1.2 avankest 394: of the following values:</p>
395:
396: <dl>
1.27 avankest 397: <dt><dfn id=uninitialized title="uninitialized state">0
398: Uninitialized</dfn>
1.2 avankest 399:
400: <dd>The initial value.
401:
1.27 avankest 402: <dt><dfn id=open title="open state">1 Open</dfn>
1.2 avankest 403:
404: <dd>The <code><a href="#dfn-open">open()</a></code> method has been
405: successfully called.
406:
1.27 avankest 407: <dt><dfn id=sent title="sent state">2 Sent</dfn>
1.2 avankest 408:
1.19 avankest 409: <dd>The user agent successfully acknowledged the request.
1.2 avankest 410:
1.27 avankest 411: <dt><dfn id=receiving title="receiving state">3 Receiving</dfn>
1.2 avankest 412:
413: <dd>Immediately before receiving the message body (if any). All HTTP
414: headers have been received.
415:
1.27 avankest 416: <dt><dfn id=loaded title="loaded state">4 Loaded</dfn>
1.2 avankest 417:
418: <dd>The data transfer has been completed.
419: </dl>
420:
1.25 avankest 421: <p class=note>When <code><a href="#dfn-readystate">readyState</a></code>
422: changes value a <code><a
1.24 avankest 423: href="#dfn-readystatechange">readystatechange</a></code> event is to be
424: dispatched on the <code><a
1.27 avankest 425: href="#xmlhttprequest0">XMLHttpRequest</a></code> object.</p>
1.24 avankest 426:
1.25 avankest 427: <dt><dfn id=dfn-open title=open><code>open(<var>method</var>,
1.18 avankest 428: <var>url</var>, <var>async</var>, <var>user</var>,
429: <var>password</var>)</code></dfn>, method
1.2 avankest 430:
431: <dd>
1.28 avankest 432: <p>Invoking this method <em class=ct>must</em> initialize the object by
433: remembering the <var>method</var>, <var>url</var>, <var>async</var>
434: (defaulting to <code>true</code> if omitted), <var>user</var>
435: (defaulting to <code>null</code> if omitted), and <var>password</var>
436: (defaulting to <code>null</code> if omitted) arguments, setting the
437: state to <a href="#open" title="open state">open</a>, resetting the
438: <code><a href="#dfn-responsetext">responseText</a></code>, <code><a
1.2 avankest 439: href="#dfn-responsexml">responseXML</a></code>, <code><a
440: href="#dfn-status">status</a></code>, and <code><a
441: href="#dfn-statustext">statusText</a></code> attributes to their initial
442: values, and resetting the list of request headers.</p>
1.20 avankest 443:
1.28 avankest 444: <p>In addition, when the state is not <a href="#uninitialized"
1.29 avankest 445: title="uninitialized state">uninitialized</a>, all members of the object
446: with the exception of <code>onreadystate</code> <em class=ct>must</em>
447: be set to their initial values and user agents <em class=ct>must</em>
448: behave as if <code><a href="#dfn-abort">abort()</a></code> was invoked.</p>
1.28 avankest 449:
1.17 avankest 450: <p>If the <var>method</var> argument doesn't match the <dfn
1.39 avankest 451: id=method>method production</dfn> defined in section 5.1.1 of RFC 2616 a
452: <code>SYNTAX_ERR</code> <em class=ct>must</em> be raised by the user
453: agent. If the user agent doesn't support the given method for security
454: reasons a <code>SECURITY_ERR</code> <em class=ct>should</em> be raised.
455: [<cite><a href="#RFC2616">RFC2616</a></cite>]</p>
1.17 avankest 456:
1.25 avankest 457: <p>User agents <em class=ct>must</em> at least support the following list
458: of methods (see [<cite><a href="#RFC2616">RFC2616</a></cite>]):</p>
1.17 avankest 459:
1.24 avankest 460: <ul>
1.17 avankest 461: <li><code>GET</code>
462:
463: <li><code>POST</code>
464:
465: <li><code>HEAD</code>
466:
467: <li><code>PUT</code>
468:
1.24 avankest 469: <li><code>DELETE</code>
470: </ul>
1.22 avankest 471:
1.25 avankest 472: <p>User agents <em class=ct>should</em> support any <var>method</var>
473: argument that matches the <a href="#method">method production</a>.</p>
1.17 avankest 474:
475: <p>When <var>method</var> case-insensitively matches <code>GET</code>,
1.13 avankest 476: <code>POST</code>, <code>HEAD</code>, <code>PUT</code> or
1.27 avankest 477: <code>DELETE</code> user agents <em class=ct>must</em> use the uppercase
478: equivalent instead.</p>
1.17 avankest 479:
1.25 avankest 480: <p>When <var>url</var> is a relative reference, it <em class=ct>must</em>
1.27 avankest 481: be resolved using the current value of the <code>baseURI</code>
482: attribute of the <code>Document</code> object currently associated with
483: the <a href="#window-pointer"><code>Window</code> pointer</a> and the
484: fragment identifier component, if any, <em class=ct>must</em> be
485: dropped. If it can't be resolved user agents <em class=ct>must</em>
486: throw a <code>SYNTAX_ERR</code>. When a non same-origin <var>url</var>
487: argument is given user agents <em class=ct>should</em> throw a
1.24 avankest 488: <code>SECURITY_ERR</code> exception.</p>
489:
1.25 avankest 490: <p class=note>A future version or extension of this specification will
1.35 avankest 491: most likely define a way of doing cross-site requests.</p>
1.26 avankest 492:
1.39 avankest 493: <p>User agents <em class=ct>should not</em> support the
494: <code>"user:password"</code> format in the <code>userinfo</code>
495: production defined in section 3.2.1 of RFC 3986 and <em
1.25 avankest 496: class=ct>must</em> throw a <code>SYNTAX_ERR</code> when doing so (not
1.20 avankest 497: supporting it). When they do support it, or in case of people using the
1.25 avankest 498: format "user", user agents <em class=ct>must</em> use them if the
1.20 avankest 499: <var>user</var> and <var>password</var> arguments are omitted. If the
500: arguments are not omitted, they take precedence, even if they are
1.39 avankest 501: <code>null</code>. [<cite><a href="#ref-rfc3986">RFC3986</a></cite>]</p>
1.20 avankest 502:
1.40 ! avankest 503: <p>The syntax for the <var>user</var> or <var>password</var> arguments
! 504: depends on the scheme being used. If the syntax for either is incorrect
! 505: user agents <em class=ct>must</em> throw a <code>SYNTAX_ERR</code>
! 506: exception.</p>
! 507:
! 508: <p class=note>The relevant specification for the scheme will provide the
! 509: exact production for <var>user</var> and <var>password</var> to match.</p>
! 510: <!-- RFC2617 does in fact not do this for "password" ... -->
1.36 avankest 511: <p>When <code>null</code> is passed for either <var>user</var> or
512: <var>password</var> user agents <em class=ct>must</em> act as if the
513: relevant data (the user name or password) is not provided.</p>
514:
515: <p class=note>The empty string value is not to be treated as the
516: <code>null</code> value. If it's disallowed by the syntax for either
517: <var>user</var> or <var>password</var> a <code>SYNTAX_ERR</code> has to
518: be thrown as indicated above.</p>
1.17 avankest 519:
1.25 avankest 520: <dt><dfn id=dfn-setrequestheader
521: title=setrequestheader><code>setRequestHeader(<var>header</var>,
1.18 avankest 522: <var>value</var>)</code></dfn>, method
1.6 avankest 523:
524: <dd>
525: <p>The nominated request header (<var>header</var>) field value <em
1.25 avankest 526: class=ct>must</em> be set to <var>value</var>, with the following
1.6 avankest 527: exceptions:</p>
528:
529: <ul>
1.27 avankest 530: <li>If the state is not <a href="#open" title="open state">open</a> or
531: the <a href="#send-flag"><code>send()</code> flag</a> is set an
1.25 avankest 532: <code>INVALID_STATE_ERR</code> exception <em class=ct>must</em> be
1.17 avankest 533: raised;
1.6 avankest 534:
1.17 avankest 535: <li>If the <var>header</var> argument doesn't match the <dfn
1.25 avankest 536: id=field-name><code>field-name</code> production</dfn> as defined by
1.17 avankest 537: section 4.2 of [<cite><a href="#RFC2616">RFC2616</a></cite>] a
1.25 avankest 538: <code>SYNTAX_ERR</code> <em class=ct>must</em> be raised;
1.17 avankest 539:
540: <li>If the <var>value</var> argument doesn't match the <dfn
1.25 avankest 541: id=field-value><code>field-value</code> production</dfn> as defined by
542: section 4.2 of [<cite><a href="#RFC2616">RFC2616</a></cite>] a
543: <code>SYNTAX_ERR</code> <em class=ct>must</em> be raised;
1.6 avankest 544:
1.34 avankest 545: <li>
1.37 avankest 546: <p>For security reasons the invocation <em class=ct>should</em> be
547: ignored if the <var>header</var> argument matches one of the following
548: headers case-insensitively:</p>
1.34 avankest 549:
550: <ul>
551: <li><code>Accept-Charset</code>
552:
553: <li><code>Accept-Encoding</code>
554:
555: <li><code>Content-Length</code>
556:
557: <li><code>Expect</code>
558:
559: <li><code>Date</code>
560:
561: <li><code>Host</code>
562:
563: <li><code>Keep-Alive</code>
564:
565: <li><code>Referer</code>
566:
567: <li><code>TE</code>
568:
569: <li><code>Trailer</code>
570:
571: <li><code>Transfer-Encoding</code>
572:
573: <li><code>Upgrade</code>
574: </ul>
575: <!-- XXX or should this throw an exception? -->
1.6 avankest 576: </ul>
1.34 avankest 577: <!-- Add "Expect" back in below if we remove it above. -->
578: <p>Implementations <em class=ct>must</em> replace any existing value if
579: the nominated request header field value is one of:</p>
580:
581: <ul>
582: <li><code>Authorization</code>
583:
584: <li><code>Content-Base</code>
585:
586: <li><code>Content-Location</code>
587:
588: <li><code>Content-MD5</code>
1.6 avankest 589:
1.34 avankest 590: <li><code>Content-Range</code>
591:
592: <li><code>Content-Type</code>
593:
594: <li><code>Content-Version</code>
595:
596: <li><code>Delta-Base</code>
597:
598: <li><code>Depth</code>
599:
600: <li><code>Destination</code>
601:
602: <li><code>ETag</code>
603:
604: <li><code>From</code>
605:
606: <li><code>If-Modified-Since</code>
607:
608: <li><code>If-Range</code>
609:
610: <li><code>If-Unmodified-Since</code>
611:
612: <li><code>Max-Forwards</code>
613:
614: <li><code>MIME-Version</code>
615:
616: <li><code>Overwrite</code>
617:
618: <li><code>Proxy-Authorization</code>
619:
620: <li><code>SOAPAction</code>
621:
622: <li><code>Timeout</code>
623: </ul>
1.6 avankest 624:
625: <p>Otherwise, if the nominated request header field already has a value,
1.25 avankest 626: the new value <em class=ct>must</em> be combined with the existing value
627: (section 4.2, [<cite><a href="#RFC2616">RFC2616</a></cite>]). See also
628: the <code><a href="#dfn-send">send()</a></code> method regarding user
629: agent header handling for caching, authentication, proxies, and cookies.</p>
1.18 avankest 630:
1.25 avankest 631: <div class=example>
1.18 avankest 632: <pre>// The following script:
633: var client = new XMLHttpRequest();
634: client.open('GET', 'demo.cgi');
635: client.setRequestHeader('X-Test', 'one');
636: client.setRequestHeader('X-Test', 'two');
637: client.send();
638:
639: // ...would result in the following header being sent:
640: ...
641: X-Test: one, two
642: ...</pre>
643: </div>
1.6 avankest 644:
1.25 avankest 645: <p>The list of request headers <em class=ct>must</em> be reset when the
1.17 avankest 646: <code><a href="#dfn-open">open()</a></code> method is invoked.</p>
1.14 avankest 647:
1.25 avankest 648: <dt><dfn id=dfn-send title=send><code>send(<var>data</var>)</code></dfn>,
649: method
1.2 avankest 650:
651: <dd>
1.27 avankest 652: <p>If the state is not <a href="#open" title="open state">open</a> or the
653: <span><code><a href="#dfn-send">send()</a></code> flag is set an
1.25 avankest 654: <code>INVALID_STATE_ERR</code> exception <em class=ct>must</em> be
655: raised. Otherwise user agents <em class=ct>must</em> make a request to
1.23 avankest 656: <var>url</var> using method <var>method</var> and set the <dfn
1.25 avankest 657: id=send-flag><code>send()</code> flag</dfn>. If the <var>async</var>
658: flag is set to <code>false</code>, then the method <em class=ct>must
1.24 avankest 659: not</em> return until the request has completed. Otherwise, it <em
1.25 avankest 660: class=ct>must</em> return immediately. (See: <code><a
1.24 avankest 661: href="#dfn-open">open()</a></code>.)</span></p>
1.23 avankest 662:
1.27 avankest 663: <p class=note>Even when <var>async</var> is set to <code>false</code> the
664: <code><a href="#dfn-readystatechange">readystatechange</a></code> event
665: will still be dispatched.</p>
666:
1.25 avankest 667: <p class=note>The <a href="#send-flag"><code>send()</code> flag</a> is
1.27 avankest 668: only relevant when the state is <a href="#open" title="open
669: state">open</a>.</p>
1.2 avankest 670:
1.16 avankest 671: <p>If <var>data</var> is passed to the <code><a
1.25 avankest 672: href="#dfn-send">send()</a></code> method it <em class=ct>must</em> be
1.29 avankest 673: used for the <dfn id=dfn-entity-body>entity body</dfn> as defined by
674: section 7.2.1 of [<cite><a href="#RFC2616">RFC2616</a></cite>]). The
675: following rules apply:</p>
1.2 avankest 676:
1.29 avankest 677: <dl>
678: <dt><var>data</var> is a <code>DOMString</code>
679:
680: <dd><var>data</var> <em class=ct>must</em> be encoded as UTF-8 for
681: transmission.
682:
683: <dt><var>data</var> is a <code>Document</code>
1.2 avankest 684:
1.29 avankest 685: <dd><var>data</var> <em class=ct>must</em> be serialized into a
686: namespace well-formed XML document and encoded using the encoding given
687: by <code><var>data</var>.xmlEncoding</code> (the XML declaration), if
688: specified, or UTF-8 otherwise. The serialization <em class=ct>must</em>
689: include an XML declaration when the final encoding is not UTF-8 or
690: UTF-16.
691:
692: <dt><var>data</var> is not a <code>DOMString</code> or
693: <code>Document</code>
694:
695: <dd>The stringification mechanisms of the host language <em
696: class=ct>must</em> be used on <var>data</var> and the result <em
697: class=ct>must</em> be treated as if <var>data</var> is a
1.25 avankest 698: <code>DOMString</code>.
1.29 avankest 699: </dl>
1.2 avankest 700:
1.20 avankest 701: <p>Invoking <code><a href="#dfn-send">send()</a></code> without the
1.25 avankest 702: <var>data</var> argument <em class=ct>must</em> give the same result as
703: if it was invoked with <code>null</code> as argument.</p>
1.16 avankest 704:
1.25 avankest 705: <p>Authors <em class=ct>should</em> specify the <code>Content-Type</code>
706: header via <code><a
1.16 avankest 707: href="#dfn-setrequestheader">setRequestHeader</a></code> before invoking
708: <code><a href="#dfn-send">send()</a></code> with an argument. If the
709: argument to <code><a href="#dfn-send">send()</a></code> is a
710: <code>Document</code> and no <code>Content-Type</code> header has been
1.25 avankest 711: set user agents <em class=ct>must</em> set it to
1.17 avankest 712: <code>application/xml</code> for XML documents and to the most
713: appropriate media type for other documents (using intrinsic knowledge
714: about the document).</p>
1.2 avankest 715:
1.18 avankest 716: <p>If the response is an HTTP redirect (status code <code>301</code>,
717: <code>302</code>, <code>303</code> or <code>307</code>), then it <em
1.25 avankest 718: class=ct>must</em> be transparently followed (unless it violates
1.18 avankest 719: security, infinite loop precautions or the scheme isn't supported). Note
720: that HTTP ([<cite><a href="#RFC2616">RFC2616</a></cite>]) places
1.16 avankest 721: requirements on user agents regarding the preservation of the request
722: method during redirects, and also requires users to be notified of
723: certain kinds of automatic redirections.</p>
1.19 avankest 724:
1.27 avankest 725: <p>Once the request has been successfully acknowledged the state <em
726: class=ct>must</em> be set to <a href="#sent" title="sent
727: state">sent</a>. Immediately before receiving the message body (if any),
728: the state <em class=ct>must</em> be set to to <a href="#receiving"
729: title="receiving state">receiving</a>. When the request has completed
730: loading, the state <em class=ct>must</em> be set to <a href="#loaded"
731: title="loaded state">loaded</a>.</p>
732:
733: <p class=note>This means that in case of a <code>HEAD</code> request the
734: state is set to <a href="#loaded" title="loaded state">loaded</a>
735: immediately after having being set to <a href="#receiving"
736: title="receiving state">receiving</a>.</p>
737:
738: <p>If something goes wrong (infinite loop, network errors) the state <em
739: class=ct>must</em> be set to <a href="#loaded" title="loaded
1.29 avankest 740: state">loaded</a> and all members (excluding <code><a
741: href="#dfn-readystate">readyState</a></code>) of the object <em
1.33 avankest 742: class=ct>must</em> be set to their initial value. Also, if
743: <code>async</code> is set to <code>false</code>, a <code><a
744: href="#network-err">NETWORK_ERR</a></code> exception <em
1.29 avankest 745: class=ct>must</em> be raised. In addition, all registered event
746: listeners <em class=ct>must</em> be removed.</p>
1.33 avankest 747:
1.25 avankest 748: <p class=note>In future versions of this specification user agents will
1.19 avankest 749: be required to dispatch an <code>error</code> event if the above occurs.</p>
750:
1.13 avankest 751: <p>If the user agent allows the specification of a proxy it <em
1.25 avankest 752: class=ct>should</em> modify the request appropriately; <abbr title="in
1.2 avankest 753: other words">i.e.</abbr>, connect to the proxy host instead of the
754: origin server, modify the <code>Request-Line</code> and send
755: <code>Proxy-Authorization</code> headers as specified.</p>
756:
1.18 avankest 757: <p>If the user agent supports <cite>HTTP Authentication</cite> ([<cite><a
1.25 avankest 758: href="#ref-rfc2617">RFC2617</a></cite>]) it <em class=ct>should</em>
1.18 avankest 759: consider requests originating from this object to be part of the
760: protection space that includes the accessed URIs and send
1.19 avankest 761: <code>Authorization</code> headers and handle <code>401
762: Unauthorised</code> requests appropriately. if authentication fails,
1.25 avankest 763: user agents <em class=ct>should</em> prompt the users for credentials.</p>
1.19 avankest 764:
1.18 avankest 765: <p>If the user agent supports <cite>HTTP State Mangement</cite>
766: ([<cite><a href="#ref-rfc2109">RFC2109</a></cite>], [<cite><a
1.25 avankest 767: href="#ref-rfc2965">RFC2965</a></cite>]) it <em class=ct>should</em>
1.18 avankest 768: persist, discard and send cookies (as received in the
769: <code>Set-Cookie</code> and <code>Set-Cookie2</code> response headers,
770: and sent in the <code>Cookie</code> header) as applicable.</p>
771:
772: <p>If the user agent implements a HTTP cache ([<cite><a
1.25 avankest 773: href="#RFC2616">RFC2616</a></cite>]) it <em class=ct>should</em> respect
774: <code>Cache-Control</code> request headers set by the author (<abbr
775: title="for example">e.g.</abbr>, <code>Cache-Control: no-cache</code>
776: bypasses the cache). It <em class=ct>must not</em> send
777: <code>Cache-Control</code> or <code>Pragma</code> request headers
1.2 avankest 778: automatically unless the user explicitly requests such behaviour (e.g.,
1.16 avankest 779: by (force-)reloading the page). <code>304 Not Modified</code> responses
780: that are a result of a user agent generated conditional request <em
1.25 avankest 781: class=ct>must</em> be presented as <code>200 OK</code> responses with
782: the appropriate content. Such user agents <em class=ct>must</em> allow
1.16 avankest 783: authors to override automatic cache validation by setting request
784: headers (e.g., <code>If-None-Match</code>,
785: <code>If-Modified-Since</code>), in which case <code>304 Not
1.25 avankest 786: Modified</code> responses <em class=ct>must</em> be passed through.</p>
1.2 avankest 787:
1.18 avankest 788: <p>If the user agent implements server-driven content-negotiation
789: ([<cite><a href="#RFC2616">RFC2616</a></cite>]) it <em
1.25 avankest 790: class=ct>should</em> set <code>Accept-Language</code>,
1.18 avankest 791: <code>Accept-Encoding</code> and <code>Accept-Charset</code> headers as
1.25 avankest 792: appropriate; it <em class=ct>must not</em> automatically set the
1.18 avankest 793: <code>Accept</code> header. Responses to such requests <em
1.25 avankest 794: class=ct>must</em> have content-codings automatically removed.</p>
1.18 avankest 795:
796: <p>If the user agent supports Expect/Continue for request bodies
797: ([<cite><a href="#RFC2616">RFC2616</a></cite>]) it <em
1.25 avankest 798: class=ct>should</em> insert <code>Expect</code> headers and handle
1.18 avankest 799: <code>100 Continue</code> responses appropriately.</p>
1.2 avankest 800:
1.25 avankest 801: <dt><dfn id=dfn-abort><code>abort()</code></dfn>, method
1.6 avankest 802:
803: <dd>
1.25 avankest 804: <p>When invoked, this method <em class=ct>must</em> cancel any network
1.11 avankest 805: activity for which the object is responsible and set all the members of
1.29 avankest 806: the object to their initial values as well as removing all event
807: listeners.</p>
1.6 avankest 808:
1.26 avankest 809: <p class=note>This means that the object <em>can</em> be used for another
810: request in which case this method will work again to cancel it.</p>
811:
1.6 avankest 812: <dt><dfn
1.25 avankest 813: id=dfn-getallresponseheaders><code>getAllResponseHeaders()</code></dfn>,
1.13 avankest 814: method
1.2 avankest 815:
816: <dd>
1.27 avankest 817: <p>If the state is not <a href="#receiving" title="receiving
818: state">receiving</a> or <a href="#loaded" title="loaded
819: state">loaded</a>, user agents <em class=ct>must</em> raise an
820: <code>INVALID_STATE_ERR</code> exception. Otherwise, it <em
821: class=ct>must</em> return all the HTTP headers, as a single string, with
822: each header line separated by a CR (U+000D) LF (U+000A) pair. The status
823: line <em class=ct>must not</em> be included.</p>
1.6 avankest 824:
1.25 avankest 825: <div class=example>
1.6 avankest 826: <pre>// The following script:
827: var client = new XMLHttpRequest();
1.18 avankest 828: client.open("GET", "test.txt", true);
1.6 avankest 829: client.send();
1.16 avankest 830: client.onreadystatechange = function() {
1.17 avankest 831: if(this.readyState == 3) {
1.16 avankest 832: print(this.getAllResponseHeaders());
833: }
834: }
1.6 avankest 835:
836: // ...should output something similar to the following text:
837: Date: Sun, 24 Oct 2004 04:58:38 GMT
838: Server: Apache/1.3.31 (Unix)
839: Keep-Alive: timeout=15, max=99
840: Connection: Keep-Alive
841: Transfer-Encoding: chunked
842: Content-Type: text/plain; charset=utf-8</pre>
843: </div>
844:
1.25 avankest 845: <dt><dfn id=dfn-getresponseheader
846: title=getresponseheader><code>getResponseHeader(<var>header</var>)</code></dfn>,
1.13 avankest 847: method
1.2 avankest 848:
1.6 avankest 849: <dd>
1.25 avankest 850: <p>If the <var>header</var> argument doesn't match the <a
851: href="#field-name"><code>field-name</code> production</a> a
852: <code>SYNTAX_ERR</code> <em class=ct>must</em> be raised. Otherwise this
853: method works as described below.</p>
1.17 avankest 854:
1.27 avankest 855: <p>If the state is not <a href="#receiving" title="receiving
856: state">receiving</a> or <a href="#loaded" title="loaded
857: state">loaded</a>, the user agent <em class=ct>must</em> raise an
858: <code>INVALID_STATE_ERR</code> exception. Otherwise, it <em
859: class=ct>must</em> represent the value of the given HTTP header
860: (<var>header</var>) in the data received so far for the last request
861: sent, as a single string. If more than one header of the given name was
862: received, then the values <em class=ct>must</em> be concatenated,
863: separated from each other by an U+002C COMMA followed by an U+0020
864: SPACE. If no headers of that name were received, then it <em
1.25 avankest 865: class=ct>must</em> return <code>null</code>. Header names <em
866: class=ct>must</em> be compared case-insensitively to the method its
1.6 avankest 867: argument (<var>header</var>).</p>
1.17 avankest 868:
1.25 avankest 869: <div class=example>
1.2 avankest 870: <pre>// The following script:
1.1 avankest 871: var client = new XMLHttpRequest();
1.18 avankest 872: client.open("GET", "test.txt", true);
1.6 avankest 873: client.send();
1.16 avankest 874: client.onreadystatechange = function() {
1.17 avankest 875: if(this.readyState == 3) {
1.18 avankest 876: print(client.getResponseHeader("Content-Type"));
1.16 avankest 877: }
878: }
1.1 avankest 879:
1.6 avankest 880: // ...should output something similar to the following text:
881: Content-Type: text/plain; charset=utf-8</pre>
1.2 avankest 882: </div>
883:
1.25 avankest 884: <dt><dfn id=dfn-responsetext><code>responseText</code></dfn> of type
1.9 avankest 885: <code>DOMString</code>, readonly
1.6 avankest 886:
887: <dd>
1.27 avankest 888: <p>If the state is not <a href="#receiving" title="receiving
889: state">receiving</a> or <a href="#loaded" title="loaded
890: state">loaded</a>, the user agent <em class=ct>must</em> raise an
891: <code>INVALID_STATE_ERR</code> exception. Otherwise, it <em
892: class=ct>must</em> be the fragment of the <a
893: href="#dfn-entity-body">entity body</a> received so far (when the state
894: is <a href="#receiving" title="receiving state">receiving</a>) or the
895: complete <a href="#dfn-entity-body">entity body</a> (when the state is
896: <a href="#loaded" title="loaded state">loaded</a>), interpreted as a
897: stream of characters.</p>
1.6 avankest 898:
899: <p>If the response includes a <code>Content-Type</code> understood by the
1.16 avankest 900: user agent the characters are encoded following the relevant media type
1.6 avankest 901: specification, with the exception that the rule in the final paragraph
1.18 avankest 902: of section 3.7.1 of [<cite><a href="#RFC2616">RFC2616</a></cite>], and
903: the rules in section 4.1.2 of [<cite><a
1.25 avankest 904: href="#ref-rfc2046">RFC2046</a></cite>] <em class=ct>must</em> be
1.18 avankest 905: treated as if they specified the default character encoding as being
1.25 avankest 906: UTF-8. Invalid bytes <em class=ct>must</em> be converted to U+FFFD
1.18 avankest 907: REPLACEMENT CHARACTER. If the user agent can't derive a character stream
908: in accord with the media type specification, <code>reponseText</code>
1.25 avankest 909: <em class=ct>must</em> be <code>null</code>.</p>
1.6 avankest 910:
1.25 avankest 911: <p>Its initial value <em class=ct>must</em> be the <code>null</code>.</p>
1.12 avankest 912:
1.26 avankest 913: <p class=note>For <code>HEAD</code> requests this attribute will always
914: be <code>null</code> (it remains unchanged). Similar to the <code><a
915: href="#dfn-responsexml">responseXML</a></code> attribute.</p>
1.23 avankest 916:
1.25 avankest 917: <dt><dfn id=dfn-responsexml><code>responseXML</code></dfn> of type
1.9 avankest 918: <code>Document</code>, readonly
1.6 avankest 919:
920: <dd>
1.27 avankest 921: <p>If the state is not <a href="#loaded" title="loaded state">loaded</a>,
922: user agents <em class=ct>must</em> raise an
923: <code>INVALID_STATE_ERR</code> exception. Otherwise, if the
1.18 avankest 924: <code>Content-Type</code> header contains a media type (ignoring any
925: parameters) that is either <code>text/xml</code>,
926: <code>application/xml</code>, or ends in <code>+xml</code>, it <em
1.25 avankest 927: class=ct>must</em> be an object that implements the
1.18 avankest 928: <code>Document</code> interface representing the parsed document. If
929: <code>Content-Type</code> did not contain such a media type, or if the
930: document could not be parsed (due to an XML well-formedness error or
1.25 avankest 931: unsupported character encoding, for instance), it <em class=ct>must</em>
932: be <code>null</code>.</p>
1.6 avankest 933:
1.25 avankest 934: <p>Its initial value <em class=ct>must</em> be <code>null</code>.</p>
1.12 avankest 935:
1.25 avankest 936: <dt><dfn id=dfn-status><code>status</code></dfn> of type <code>unsigned
1.9 avankest 937: short</code>, readonly
1.6 avankest 938:
939: <dd>
940: <p>If the <code><a href="#dfn-status">status</a></code> attribute is not
941: available an <code>INVALID_STATE_ERR</code> exception <em
1.25 avankest 942: class=ct>must</em> be raised. It <em class=ct>must</em> be available
1.27 avankest 943: when the state is <a href="#receiving" title="receiving
944: state">receiving</a> or <a href="#loaded" title="loaded
945: state">loaded</a>. When available, it <em class=ct>must</em> represent
946: the HTTP status code (typically <code>200</code> for a successful
947: connection).</p>
1.2 avankest 948:
1.25 avankest 949: <p>Its initial value <em class=ct>must</em> be <code>0</code>.</p>
1.12 avankest 950:
1.25 avankest 951: <dt><dfn id=dfn-statustext><code>statusText</code></dfn> of type
1.9 avankest 952: <code>DOMString</code>, readonly
1.2 avankest 953:
1.6 avankest 954: <dd>
955: <p>If the <code><a href="#dfn-statustext">statusText</a></code> attribute
956: is not available an <code>INVALID_STATE_ERR</code> exception <em
1.25 avankest 957: class=ct>must</em> be raised. It <em class=ct>must</em> be available
1.27 avankest 958: when the state is <a href="#receiving" title="receiving
959: state">receiving</a> or <a href="#loaded" title="loaded
960: state">loaded</a>). When available, it <em class=ct>must</em> represent
961: the HTTP status text sent by the server (appears after the status code).</p>
1.12 avankest 962:
1.25 avankest 963: <p>Its initial value <em class=ct>must</em> be the empty string.</p>
1.2 avankest 964: </dl>
965:
966: <p>HTTP requests sent from multiple different <code><a
1.27 avankest 967: href="#xmlhttprequest0">XMLHttpRequest</a></code> objects in succession
1.25 avankest 968: <em class=ct>should</em> be pipelined into shared HTTP connections.
1.2 avankest 969:
1.33 avankest 970: <h3 id=events><span class=secno>2.2. </span>Events for the <code
971: title="">XMLHttpRequest</code> Object</h3>
1.2 avankest 972:
1.1 avankest 973: <p>These sections describe the various events that can be dispatched on the
1.2 avankest 974: object implementing the <code><a
1.27 avankest 975: href="#xmlhttprequest0">XMLHttpRequest</a></code> interface. For this
1.2 avankest 976: version of the specification only one event is defined.
977:
1.1 avankest 978: <dl>
1.25 avankest 979: <dt><dfn id=dfn-readystatechange><code>readystatechange</code></dfn>
1.2 avankest 980:
981: <dd>The <code><a href="#dfn-readystatechange">readystatechange</a></code>
1.25 avankest 982: event <em class=ct>must</em> be dispatched when <code><a
1.2 avankest 983: href="#dfn-readystate">readyState</a></code> changes value. It <em
1.25 avankest 984: class=ct>must not</em> bubble, <em class=ct>must not</em> be cancelable
985: and <em class=ct>must</em> implement the <code>Event</code> interface
986: [<cite><a href="#DOM3EV">DOM3Events</a></cite>]. The event has no
987: namespace (<code>Event.namespaceURI</code> is <code>null</code>).
1.1 avankest 988: </dl>
1.2 avankest 989:
1.33 avankest 990: <h3 id=exceptions><span class=secno>2.3. </span>Exceptions for the <code
991: title="">XMLHttpRequest</code> Object</h3>
992:
1.34 avankest 993: <pre
994: class=idl>exception <dfn id=xmlhttprequestexception>XMLHttpRequestException</dfn> {
1.33 avankest 995: unsigned short code;
996: };
997: const unsigned short <a href="#network-err">NETWORK_ERR</a> = 101;</pre>
998:
1.35 avankest 999: <p>The <dfn id=network-err><code>NETWORK_ERR</code></dfn> exception is
1000: thrown when a network error occurs in synchronous requests. See the
1001: section on <code><a href="#dfn-send">send()</a></code> for more details.</p>
1.33 avankest 1002: <!-- Other specifications should probably be able to reuse this... -->
1003:
1.31 avankest 1004: <h2 class=no-num id=notcovered>Not in this Specification</h2>
1005:
1006: <p><em>This section is non normative.</em>
1007:
1008: <p>This specification does not include the following features that may or
1009: may not be implemented by user agents:
1010:
1011: <ul>
1012: <li><code>load</code> event and <code>onload</code> attribute;
1013:
1014: <li><code>error</code> event and <code>onerror</code> attribute;
1015:
1016: <li><code>progress</code> event and <code>onprogress</code> attribute;
1017:
1018: <li><code title="">abort</code> event and <code>onabort</code> attribute;
1019:
1020: <li>Timers have been suggested, perhaps an <code>ontimeout</code>
1021: attribute;
1022:
1023: <li>Property to disable following redirects;
1024:
1.32 avankest 1025: <li><code title="">responseXML</code> for <code>text/html</code>
1026: documents;
1.31 avankest 1027:
1.32 avankest 1028: <li>Cross-site <code title="">XMLHttpRequest</code>.
1.31 avankest 1029: </ul>
1030:
1.25 avankest 1031: <h2 class=no-num id=bibref>References</h2>
1.2 avankest 1032:
1.7 avankest 1033: <dl>
1.39 avankest 1034: <dt>[<dfn id=DOM3>DOM3Core</dfn>]
1.2 avankest 1035:
1.15 avankest 1036: <dd><cite><a href="http://www.w3.org/TR/DOM-Level-3-Core">Document Object
1037: Model (DOM) Level 3 Core Specification</a></cite>, A. Le Hors, P. Le
1038: Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors.
1039: World Wide Web Consortium, April 2004.
1.2 avankest 1040:
1.39 avankest 1041: <dt>[<dfn id=DOM3EV>DOM3Events</dfn>]
1.2 avankest 1042:
1043: <dd><cite><a href="http://www.w3.org/TR/DOM-Level-3-Events/">Document
1.15 avankest 1044: Object Model (DOM) Level 3 Events Specification</a></cite>, Björn
1045: Höhrmann, editor. World Wide Web Consortium, April 2006.
1046:
1.39 avankest 1047: <dt>[<dfn id=ref-ecmascript>ECMAScript</dfn>]
1.18 avankest 1048:
1049: <dd><cite><a
1050: href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript
1051: Language Specification</a></cite>, Third Edition. ECMA, December 1999.
1052:
1.39 avankest 1053: <dt>[<dfn id=ref-rfc2046>RFC2046</dfn>]
1.18 avankest 1054:
1.22 avankest 1055: <dd><cite><a href="http://ietf.org/rfc/rfc2046">Multipurpose Internet Mail
1056: Extensions (MIME) Part Two: Media Types</a></cite>, N. Freed, N.
1057: Borenstein, editors. IETF, November 1996.
1.18 avankest 1058:
1.39 avankest 1059: <dt>[<dfn id=ref-rfc2109>RFC2109</dfn>]
1.15 avankest 1060:
1061: <dd><cite><a href="http://ietf.org/rfc/rfc2109">HTTP State Management
1062: Mechanism</a></cite>, D. Kristol, L. Montulli, editors. IETF, February
1063: 1997.
1064:
1.39 avankest 1065: <dt>[<dfn id=RFC2119>RFC2119</dfn>]
1.15 avankest 1066:
1067: <dd><cite><a href="http://ietf.org/rfc/rfc2119">RFC 2119: Key words for
1068: use in RFCs to Indicate Requirement Levels</a></cite>, S. Bradner. IETF,
1069: March 1997.
1070:
1.39 avankest 1071: <dt>[<dfn id=RFC2616>RFC2616</dfn>]
1.15 avankest 1072:
1073: <dd><cite><a href="http://ietf.org/rfc/rfc2616">Hypertext Transfer
1074: Protocol -- HTTP/1.1</a></cite>, R. Fielding, J. Gettys, J. Mogul, H.
1075: Frystyk, L. Masinter, P. Leach, T. Berners-Lee, editors. IETF, June 1999
1076:
1.39 avankest 1077: <dt>[<dfn id=ref-rfc2617>RFC2617</dfn>]
1.15 avankest 1078:
1079: <dd><cite><a href="http://ietf.org/rfc/rfc2617">HTTP Authentication: Basic
1.18 avankest 1080: and Digest Access Authentication</a></cite>, ...
1.2 avankest 1081:
1.39 avankest 1082: <dt>[<dfn id=ref-rfc2965>RFC2965</dfn>]
1.2 avankest 1083:
1.22 avankest 1084: <dd><cite><a href="http://ietf.org/rfc/rfc2965">HTTP State Management
1085: Mechanism</a></cite>, D. Kristol, L. Montulli, editors. IETF, October
1086: 2000.
1087:
1.39 avankest 1088: <dt>[<dfn id=ref-rfc3986>RFC3986</dfn>]
1.2 avankest 1089:
1.15 avankest 1090: <dd><cite><a href="http://ietf.org/rfc/rfc3986">Uniform Resource
1091: Identifier (URI): Generic Syntax</a></cite>, T. Berners-Lee, R. Fielding,
1092: L. Masinter, editors. IETF, January 2005.
1.30 avankest 1093:
1.39 avankest 1094: <dt>[<dfn id=ref-window>Window</dfn>]
1.30 avankest 1095:
1096: <dd><cite><a href="http://www.w3.org/TR/Window/">Window Object
1097: 1.0</a></cite>, I. Davis, M. Stachowiak, editors. W3C, April 2006.
1.2 avankest 1098: </dl>
1099:
1.25 avankest 1100: <h2 class=no-num id=acknowledgements>Acknowledgements</h2>
1.2 avankest 1101:
1102: <p><em>This section is non-normative</em>
1103:
1.9 avankest 1104: <p>The editor would like to thank to the following people who have
1.35 avankest 1105: contributed to this specification (ordered by first name):
1.2 avankest 1106:
1.1 avankest 1107: <ul>
1.25 avankest 1108: <li>Alex Hopmann
1109:
1.9 avankest 1110: <li>Alex Vincent
1111:
1.19 avankest 1112: <li>Alexey Proskuryakov
1113:
1.2 avankest 1114: <li>Asbjørn Ulsberg
1115:
1116: <li>Boris Zbarsky
1117:
1118: <li>Björn Höhrmann
1119:
1120: <li>Cameron McCormack
1121:
1122: <li>Christophe Jolif
1123:
1124: <li>Charles McCathieNevile
1125:
1126: <li>Dean Jackson
1127:
1128: <li>Doug Schepers
1129:
1130: <li>Douglas Livingstone
1131:
1132: <li>Gorm Haug Eriksen
1133:
1134: <li>Hallvord R. M. Steen
1135:
1136: <li>Håkon Wium Lie
1137:
1138: <li>Ian Davis
1139:
1140: <li>Ian Hickson
1141:
1142: <li>Ivan Herman
1143:
1144: <li>Jens Lindström
1145:
1146: <li>Jim Deegan
1147:
1148: <li>Jim Ley
1149:
1150: <li>Jonas Sicking
1151:
1152: <li>Julian Reschke
1153:
1154: <li>Karl Dubost
1155:
1156: <li>Maciej Stachowiak
1157:
1.9 avankest 1158: <li>Magnus Kristiansen
1159:
1.2 avankest 1160: <li>Marc Hadley
1161:
1162: <li>Mark Nottingham
1163:
1164: <li>Pawel Glowacki
1165:
1.26 avankest 1166: <li>Q42
1167:
1.2 avankest 1168: <li>Robin Berjon
1169:
1170: <li>Ruud Steltenpool
1.35 avankest 1171:
1172: <li>Simon Pieters
1.1 avankest 1173: </ul>
1.2 avankest 1174:
1175: <p>Special thanks to the Microsoft employees who first implemented the
1.27 avankest 1176: <code><a href="#xmlhttprequest0">XMLHttpRequest</a></code> interface,
1.2 avankest 1177: which was first widely deployed by the Windows Internet Explorer browser.
1178:
1.1 avankest 1179: <p>Special thanks also to the WHATWG for drafing a first version of this
1.2 avankest 1180: specification in their Web Applications 1.0 document.
1181:
1182: <p>Thanks also to all those who have helped to improve this specification
1183: by sending suggestions and corrections. (Please, keep bugging us with your
1184: issues!)
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to Overview.html CVS log ![[TXT]](/https/dev.w3.org/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/https/dev.w3.org/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / 2006 / webapi / XMLHttpRequest