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