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