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