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