Annotation of 2006/webapi/XMLHttpRequest/Overview.html, revision 1.212
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>
1.209 avankest 5: <title>XMLHttpRequest</title>
1.2 avankest 6:
1.20 avankest 7: <style type="text/css">
1.118 avankest 8: pre.idl { border:solid thin; background:#eee; color:#000; padding:0.5em }
1.20 avankest 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 }
1.90 avankest 12: .note { margin-left:2em; font-weight:bold; font-style:italic; color:#008000 }
1.20 avankest 13: p.note::before { content:"Note: " }
1.205 avankest 14: .XXX { padding:.5em; border:solid #f00 }
15: p.XXX::before { content:"Issue: " }
1.120 avankest 16: dl.switch { padding-left:2em }
17: dl.switch dt { text-indent:-1.5em }
18: dl.switch dt:before { content:'\21AA'; padding:0 0.5em 0 0; display:inline-block; width:1em; text-align:right; line-height:0.5em }
1.20 avankest 19: em.ct { text-transform:lowercase; font-variant:small-caps; font-style:normal }
20: dfn { font-weight:bold; font-style:normal }
21: code { color:orangered }
22: code :link, code :visited { color:inherit }
1.205 avankest 23: hr:not(.top) { display:block; background:none; border:none; padding:0; margin:2em 0; height:auto }
24: table { border-collapse:collapse; border-style:hidden hidden none hidden }
25: table thead { border-bottom:solid }
26: table tbody th:first-child { border-left:solid }
27: table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
1.20 avankest 28: </style>
1.174 avankest 29: <link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel=stylesheet>
1.2 avankest 30:
1.1 avankest 31: <body>
1.25 avankest 32: <div class=head>
33: <p><a href="http://www.w3.org/"><img alt=W3C height=48
34: src="http://www.w3.org/Icons/w3c_home" width=72></a></p>
1.2 avankest 35:
1.209 avankest 36: <h1 class=head id=the-xmlhttprequest-object><code
37: title="">XMLHttpRequest</code></h1>
1.2 avankest 38:
1.210 avankest 39: <h2 class="no-num no-toc" id=w3c-doctype>Editor's Draft 9 June 2009</h2>
1.2 avankest 40:
1.1 avankest 41: <dl>
1.154 avankest 42: <dt>This Version:
1.2 avankest 43:
44: <dd><a
1.210 avankest 45: href="http://www.w3.org/TR/2009/ED-XMLHttpRequest-20090609/">http://www.w3.org/TR/2009/ED-XMLHttpRequest-20090609/</a>
1.2 avankest 46:
1.14 avankest 47: <dt>Latest Version:
1.2 avankest 48:
49: <dd><a
50: href="http://www.w3.org/TR/XMLHttpRequest/">http://www.w3.org/TR/XMLHttpRequest/</a>
51:
1.190 avankest 52: <dt>Latest Editor Version:
53:
54: <dd><a
55: href="http://dev.w3.org/2006/webapi/XMLHttpRequest/">http://dev.w3.org/2006/webapi/XMLHttpRequest/</a>
56:
1.14 avankest 57: <dt>Previous Versions:
1.2 avankest 58:
59: <dd><a
1.174 avankest 60: href="http://www.w3.org/TR/2008/WD-XMLHttpRequest-20080415/">http://www.w3.org/TR/2008/WD-XMLHttpRequest-20080415/</a>
61:
62: <dd><a
1.155 avankest 63: href="http://www.w3.org/TR/2007/WD-XMLHttpRequest-20071026/">http://www.w3.org/TR/2007/WD-XMLHttpRequest-20071026/</a>
64:
65: <dd><a
1.134 avankest 66: href="http://www.w3.org/TR/2007/WD-XMLHttpRequest-20070618/">http://www.w3.org/TR/2007/WD-XMLHttpRequest-20070618/</a>
67:
68: <dd><a
1.60 avankest 69: href="http://www.w3.org/TR/2007/WD-XMLHttpRequest-20070227/">http://www.w3.org/TR/2007/WD-XMLHttpRequest-20070227/</a>
70:
71: <dd><a
1.25 avankest 72: href="http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060927/">http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060927/</a>
73:
74: <dd><a
1.2 avankest 75: href="http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060619/">http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060619/</a>
76:
77: <dd><a
78: href="http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060405/">http://www.w3.org/TR/2006/WD-XMLHttpRequest-20060405/</a>
79:
80: <dt>Editor:
81:
82: <dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a> (<a
83: href="http://www.opera.com/">Opera Software ASA</a>) <<a
84: href="mailto:annevk@opera.com">annevk@opera.com</a>>
1.1 avankest 85: </dl>
1.2 avankest 86:
1.25 avankest 87: <p class=copyright><a
1.2 avankest 88: href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
1.53 avankest 89: © 2007 <a href="http://www.w3.org/"><acronym title="World Wide Web
90: Consortium">W3C</acronym></a><sup>®</sup> (<a
91: href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute
92: of Technology">MIT</acronym></a>, <a
93: href="http://www.ercim.org/"><acronym title="European Research Consortium
94: for Informatics and Mathematics">ERCIM</acronym></a>, <a
1.2 avankest 95: href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
96: href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
97: <a
98: href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
99: and <a
100: href="http://www.w3.org/Consortium/Legal/copyright-documents">document
101: use</a> rules apply.</p>
1.1 avankest 102: </div>
1.2 avankest 103:
104: <hr>
105:
1.25 avankest 106: <h2 class="no-num no-toc" id=specabstract>Abstract</h2>
1.2 avankest 107:
1.209 avankest 108: <p>The <code title="">XMLHttpRequest</code> specification defines an API
109: that provides scripted client functionality for transferring data between
110: a client and a server.
1.25 avankest 111:
112: <h2 class="no-num no-toc" id=sotd>Status of this Document</h2>
1.2 avankest 113:
114: <p><em>This section describes the status of this document at the time of
115: its publication. Other documents may supersede this document. A list of
116: current W3C publications and the latest revision of this technical report
117: can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
1.173 avankest 118: index</a> at http://www.w3.org/TR/.</em>
1.2 avankest 119:
1.210 avankest 120: <p>This is the 9 June 2009 Editor's Draft of the <code
1.209 avankest 121: title="">XMLHttpRequest</code> specification. Please send comments to <a
122: href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a
123: href="http://lists.w3.org/Archives/Public/public-webapps/">archived</a>)
1.49 avankest 124: with either <samp>[XHR]</samp> or <samp title="">[XMLHttpRequest]</samp>
1.209 avankest 125: at the start of the subject line<!-- before befor 2 June 2008-->.
1.49 avankest 126:
127: <p>This document is produced by the <a
1.209 avankest 128: href="http://www.w3.org/2008/webapps/">Web Applications</a> (WebApps)
129: Working Group, part of the <a
130: href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients Activity</a>
131: in the W3C <a href="http://www.w3.org/Interaction/">Interaction
132: Domain</a>. Changes made to this document can be found in the <a
1.49 avankest 133: href="http://dev.w3.org/cvsweb/2006/webapi/XMLHttpRequest/Overview.html">W3C
134: public CVS server</a>.
1.2 avankest 135:
136: <p>Publication as a Working Draft does not imply endorsement by the W3C
137: Membership. This is a draft document and may be updated, replaced or
138: obsoleted by other documents at any time. It is inappropriate to cite this
139: document as other than work in progress.
140:
141: <p>This document was produced by a group operating under the <a
142: href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
1.54 avankest 143: 2004 W3C Patent Policy</a>. W3C maintains a <a
1.209 avankest 144: href="http://www.w3.org/2004/01/pp-impl/42538/status"
1.25 avankest 145: rel=disclosure>public list of any patent disclosures</a> made in
1.2 avankest 146: connection with the deliverables of the group; that page also includes
147: instructions for disclosing a patent. An individual who has actual
148: knowledge of a patent which the individual believes contains <a
149: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
150: Claim(s)</a> must disclose the information in accordance with <a
151: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
152: 6 of the W3C Patent Policy</a>.
153:
1.25 avankest 154: <h2 class="no-num no-toc" id=toc>Table of Contents</h2>
1.2 avankest 155: <!--begin-toc-->
156:
1.25 avankest 157: <ul class=toc>
1.204 avankest 158: <li><a href="#introduction"><span class=secno>1 </span>Introduction</a>
1.154 avankest 159:
1.204 avankest 160: <li><a href="#conformance"><span class=secno>2 </span>Conformance</a>
1.25 avankest 161: <ul class=toc>
1.168 avankest 162: <li><a href="#dependencies"><span class=secno>2.1
1.154 avankest 163: </span>Dependencies</a>
1.2 avankest 164:
1.168 avankest 165: <li><a href="#terminology"><span class=secno>2.2 </span>Terminology</a>
1.81 avankest 166:
1.168 avankest 167: <li><a href="#extensibility"><span class=secno>2.3
1.154 avankest 168: </span>Extensibility</a>
169: </ul>
1.81 avankest 170:
1.204 avankest 171: <li><a href="#security"><span class=secno>3 </span>Security
1.154 avankest 172: Considerations</a>
1.2 avankest 173:
1.204 avankest 174: <li><a href="#xmlhttprequest"><span class=secno>4 </span>The <code
1.16 avankest 175: title="">XMLHttpRequest</code> Object</a>
1.25 avankest 176: <ul class=toc>
1.205 avankest 177: <li><a href="#origin-and-base-url"><span class=secno>4.1 </span>Origin
178: and Base URL</a>
1.33 avankest 179:
1.205 avankest 180: <li><a href="#task-sources"><span class=secno>4.2 </span>Task
181: Sources</a>
182:
183: <li><a href="#constructor"><span class=secno>4.3 </span>Constructor</a>
184:
1.207 avankest 185: <li><a href="#event-handler-attributes"><span class=secno>4.4
186: </span>Event Handler Attributes</a>
1.205 avankest 187:
1.207 avankest 188: <li><a href="#states"><span class=secno>4.5 </span>States</a>
1.205 avankest 189:
190: <li><a href="#request"><span class=secno>4.6 </span>Request</a>
191: <ul class=toc>
192: <li><a href="#the-open-method"><span class=secno>4.6.1 </span>The
193: <code title="">open()</code> method</a>
194:
195: <li><a href="#the-setrequestheader-method"><span class=secno>4.6.2
196: </span>The <code title="">setRequestHeader()</code> method</a>
197:
198: <li><a href="#the-send-method"><span class=secno>4.6.3 </span>The
199: <code title="">send()</code> method</a>
200:
201: <li><a href="#the-abort-method"><span class=secno>4.6.4 </span>The
202: <code title="">abort()</code> method</a>
203: </ul>
204:
205: <li><a href="#response"><span class=secno>4.7 </span>Response</a>
206: <ul class=toc>
207: <li><a href="#the-status-attribute"><span class=secno>4.7.1 </span>The
208: <code title="">status</code> attribute</a>
209:
210: <li><a href="#the-statustext-attribute"><span class=secno>4.7.2
211: </span>The <code title="">statusText</code> attribute</a>
212:
213: <li><a href="#the-getresponseheader-method"><span class=secno>4.7.3
214: </span>The <code title="">getResponseHeader()</code> method</a>
215:
216: <li><a href="#the-getallresponseheaders-method"><span
217: class=secno>4.7.4 </span>The <code
218: title="">getAllResponseHeaders()</code> method</a>
219:
220: <li><a href="#response-entity-body0"><span class=secno>4.7.5
221: </span>Response Entity Body</a>
222:
223: <li><a href="#the-responsetext-attribute"><span class=secno>4.7.6
224: </span>The <code title="">responseText</code> attribute</a>
225:
226: <li><a href="#the-responsexml-attribute"><span class=secno>4.7.7
227: </span>The <code title="">responseXML</code> attribute</a>
228: </ul>
229:
230: <li><a href="#exceptions"><span class=secno>4.8 </span>Exceptions</a>
1.11 avankest 231: </ul>
1.2 avankest 232:
1.31 avankest 233: <li class=no-num><a href="#notcovered">Not in this Specification</a>
234:
1.25 avankest 235: <li class=no-num><a href="#bibref">References</a>
1.2 avankest 236:
1.131 avankest 237: <li class=no-num><a href="#acknowledgments">Acknowledgments</a>
1.2 avankest 238: </ul>
239: <!--end-toc-->
240:
1.204 avankest 241: <h2 id=introduction><span class=secno>1 </span>Introduction</h2>
1.2 avankest 242:
243: <p><em>This section is non-normative.</em>
244:
1.60 avankest 245: <p>The <code><a href="#xmlhttprequest-object">XMLHttpRequest</a></code>
246: object implements an interface exposed by a scripting engine that allows
247: scripts to perform HTTP client functionality, such as submitting form data
1.184 avankest 248: or loading data from a server. It is the ECMAScript HTTP API.
1.2 avankest 249:
250: <p>The name of the object is <code><a
1.60 avankest 251: href="#xmlhttprequest-object">XMLHttpRequest</a></code> for compatibility
1.128 avankest 252: with the Web, though each component of this name is potentially
1.60 avankest 253: misleading. First, the object supports any text based format, including
254: XML. Second, it can be used to make requests over both HTTP and HTTPS
255: (some implementations support protocols in addition to HTTP and HTTPS, but
256: that functionality is not covered by this specification). Finally, it
257: supports "requests" in a broad sense of the term as it pertains to HTTP;
258: namely all activity involved with HTTP requests or responses for the
259: defined HTTP methods.
1.2 avankest 260:
1.25 avankest 261: <div class=example>
1.18 avankest 262: <p>Some simple code to do something with data from an XML document fetched
263: over the network:</p>
264:
1.60 avankest 265: <pre><code>function test(data) {
1.18 avankest 266: // taking care of data
267: }
268:
269: function handler() {
1.118 avankest 270: if(this.readyState == 4 && this.status == 200) {
1.18 avankest 271: // so far so good
1.118 avankest 272: if(this.responseXML != null && this.responseXML.getElementById('test').firstChild.data)
273: // success!
1.18 avankest 274: test(this.responseXML.getElementById('test').firstChild.data);
275: else
276: test(null);
1.118 avankest 277: } else if (this.readyState == 4 && this.status != 200) {
1.18 avankest 278: // fetched the wrong page or network error...
279: test(null);
280: }
281: }
282:
283: var client = new XMLHttpRequest();
284: client.onreadystatechange = handler;
285: client.open("GET", "test.xml");
1.60 avankest 286: client.send();</code></pre>
1.18 avankest 287:
1.58 avankest 288: <p>If you just want to log a message to the server:</p>
1.18 avankest 289:
1.60 avankest 290: <pre><code>function log(message) {
1.18 avankest 291: var client = new XMLHttpRequest();
1.58 avankest 292: client.open("POST", "/log");
1.59 avankest 293: client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
1.18 avankest 294: client.send(message);
1.60 avankest 295: }</code></pre>
1.18 avankest 296:
297: <p>Or if you want to check the status of a document on the server:</p>
298:
1.60 avankest 299: <pre><code>function fetchStatus(address) {
1.18 avankest 300: var client = new XMLHttpRequest();
301: client.onreadystatechange = function() {
302: // in case of network errors this might not give reliable results
303: if(this.readyState == 4)
304: returnStatus(this.status);
305: }
306: client.open("HEAD", address);
307: client.send();
1.60 avankest 308: }</code></pre>
1.18 avankest 309: </div>
1.2 avankest 310:
1.204 avankest 311: <h2 id=conformance><span class=secno>2 </span>Conformance</h2>
1.2 avankest 312:
1.29 avankest 313: <p>Everything in this specification is normative except for diagrams,
1.2 avankest 314: examples, notes and sections marked non-normative.
315:
1.25 avankest 316: <p>The key words <em class=ct>must</em>, <em class=ct>must not</em>, <em
1.75 avankest 317: class=ct>should</em> and <em class=ct>may</em> in this document are to be
318: interpreted as described in RFC 2119. [<cite><a
1.146 avankest 319: href="#ref-rfc2119">RFC2119</a></cite>]
1.2 avankest 320:
321: <p>This specification defines the following classes of products:
322:
323: <dl>
1.75 avankest 324: <dt><dfn id=conforming-user-agent>Conforming user agent</dfn>
1.2 avankest 325:
1.75 avankest 326: <dd>
327: <p>A user agent <em class=ct>must</em> behave as described in this
1.107 avankest 328: specification in order to be considered conformant.</p>
1.75 avankest 329:
1.141 avankest 330: <p>If the user agent is not a conforming XML user agent the <a
331: href="#xml-response-entity-body">XML response entity body</a> <em
332: class=ct>must</em> (always) be <code>null</code>.</p>
333:
334: <p>User agents <em class=ct>may</em> implement algorithms given in this
335: specification in any way desired, so long as the end result is
336: indistinguishable from the result that would be obtained by the
337: specification's algorithms.</p>
1.2 avankest 338:
1.96 avankest 339: <p class=note>This specification uses both the terms "conforming user
340: agent(s)" and "user agent(s)" to refer to this product class.</p>
341:
1.95 avankest 342: <dt><dfn id=conforming-xml-user-agent>Conforming XML user agent</dfn>
343:
344: <dd>
1.164 avankest 345: <p>An XML user agent <em class=ct>must</em> be a <a
346: href="#conforming-user-agent">conforming user agent</a> and <em
347: class=ct>must</em> be a conforming XML processor that reports violations
348: of namespace well-formedness. [<cite><a href="#ref-xml">XML</a></cite>]
1.2 avankest 349: </dl>
350:
1.168 avankest 351: <h3 id=dependencies><span class=secno>2.1 </span>Dependencies</h3>
1.2 avankest 352:
1.31 avankest 353: <p>This specification relies on several underlying specifications.
1.2 avankest 354:
1.31 avankest 355: <dl>
356: <dt>DOM
1.2 avankest 357:
1.31 avankest 358: <dd>
1.127 avankest 359: <p>A <a href="#conforming-user-agent" title="conforming user
1.177 avankest 360: agent">conforming user agent</a> <em class=ct>must</em> support at least
361: the subset of the functionality defined in DOM Events and DOM Core that
1.183 avankest 362: this specification relies upon, such as various exceptions and
363: <code>EventTarget</code>. [<cite><a
1.156 avankest 364: href="#ref-dom2events">DOM2Events</a></cite>] [<cite><a
365: href="#ref-dom3core">DOM3Core</a></cite>]
1.2 avankest 366:
1.162 avankest 367: <dt>HTML 5
368:
369: <dd>
1.183 avankest 370: <p>A <a href="#conforming-user-agent">conforming user agent</a> <em
1.190 avankest 371: class=ct>must</em> support at least the subset of the functionality
372: defined in HTML 5 that this specification relies upon, such as the
1.198 avankest 373: basics of the <code>Window</code> object and serializing a
374: <code>Document</code> object. [<cite><a
375: href="#ref-html5">HTML5</a></cite>]</p>
1.190 avankest 376:
1.162 avankest 377: <p class=note>The <a
378: href="http://www.w3.org/TR/2006/WD-Window-20060407/">Window Object
379: 1.0</a> draft is not referenced normatively as it appears to be no
380: longer maintained and HTML 5 defines the <code>Window</code> object
381: in more detail. This specification already depends on HTML 5 for
382: other reasons so there is not much additional overhead because of this.</p>
383:
1.31 avankest 384: <dt>HTTP
1.11 avankest 385:
1.31 avankest 386: <dd>
1.156 avankest 387: <p>A <a href="#conforming-user-agent">conforming user agent</a> <em
388: class=ct>must</em> support some version of the HTTP protocol. It <em
389: class=ct>should</em> support any HTTP method that matches the <a
1.212 ! avankest 390: href="#method-token">Method token</a> production and <em
! 391: class=ct>must</em> at least support the following methods:</p>
1.81 avankest 392:
1.60 avankest 393: <ul>
394: <li><code>GET</code>
395:
396: <li><code>POST</code>
397:
398: <li><code>HEAD</code>
399:
400: <li><code>PUT</code>
401:
402: <li><code>DELETE</code>
403:
404: <li><code>OPTIONS</code>
405: </ul>
406:
407: <p>Other requirements regarding HTTP are made throughout the
1.146 avankest 408: specification. [<cite><a href="#ref-rfc2616">RFC2616</a></cite>]</p>
1.182 avankest 409:
410: <dt>Web IDL
411:
412: <dd>A <a href="#conforming-user-agent">conforming user agent</a> <em
413: class=ct>must</em> also be a conforming implementation of the IDL
414: fragment in this specification, as described in the Web IDL
1.205 avankest 415: specification. [<cite><a href="#ref-webidl">WebIDL</a></cite>]
1.31 avankest 416: </dl>
1.2 avankest 417:
1.168 avankest 418: <h3 id=terminology><span class=secno>2.2 </span>Terminology</h3>
1.211 avankest 419:
420: <p>Comparing two strings in a <dfn id=case-sensitive>case-sensitive</dfn>
421: manner means comparing them exactly, codepoint for codepoint.
422:
423: <p>Comparing two strings in an <dfn id=ascii-case-insensitive>ASCII
424: case-insensitive</dfn> manner means comparing them exactly, codepoint for
425: codepoint, except that the characters in the range U+0041 .. U+005A (i.e.
426: LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding
427: characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to
428: LATIN SMALL LETTER Z) are considered to also match.
429:
430: <p><dfn id=converted-to-ascii-upercase title="converted to ASCII
431: uppercase">Converting a string to ASCII uppercase</dfn> means replacing
432: all characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to
433: LATIN SMALL LETTER Z) with the corresponding characters in the range
434: U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).
1.81 avankest 435:
1.201 avankest 436: <p>The terms and algorithms <dfn id=url-fragment><fragment></dfn>, <dfn
1.211 avankest 437: id=url-scheme><scheme></dfn>, <dfn id=document-base-url>document base
1.207 avankest 438: URL</dfn>, <dfn id=event-handler-attributes-0>event handler
1.205 avankest 439: attributes</dfn>, <dfn id=event-handler-event-type>event handler event
440: type</dfn>, <dfn id=fully-active>fully active</dfn>, <dfn
1.208 avankest 441: id=function><code>Function</code></dfn>, <dfn id=origin>origin</dfn>, <dfn
442: id=resolve-a-url>resolve a URL</dfn>, <dfn id=same-origin>same
443: origin</dfn>, <dfn id=storage-mutex>storage mutex</dfn>, <dfn
444: id=task>task</dfn>, <dfn id=task-source>task source</dfn>, <dfn
445: id=url>URL</dfn>, <dfn id=url-character-encoding>URL character
1.210 avankest 446: encoding</dfn>, <dfn id=queue-a-task>queue a task</dfn>, and <dfn
447: id=xml-fragment-serialization-algorithm>XML fragment serialization
448: algorithm</dfn> are defined by the HTML 5 specification. [<cite><a
1.205 avankest 449: href="#ref-html5">HTML5</a></cite>]</p>
1.212 ! avankest 450: <!-- XXX Things might be splitted out of HTML5 -->
1.205 avankest 451:
452: <p>The term <dfn id=entity-body>entity body</dfn> is used as described in
453: RFC 2616. <dfn id=method-token>Method token</dfn> is used as described in
454: section 5.1.1 of RFC 2616. <dfn
455: id=field-name><code>field-name</code></dfn> and <dfn
456: id=field-value><code>field-value</code></dfn> are used as described in
457: section 4.2 of RFC 2616. [<cite><a href="#ref-rfc2616">RFC2616</a></cite>]
458:
459: <p><dfn id=userinfo><code>userinfo</code></dfn> is used as described in
460: section 3.2.1 of RFC 3986. [<cite><a
461: href="#ref-rfc3986">RFC3986</a></cite>]
462:
463: <p>To <dfn id=dispatch-readystatechange-event>dispatch a
464: <code>readystatechange</code> event</dfn> means that an event with the
465: name <code>readystatechange</code>, with no namespace, which does not
466: bubble and is not cancelable, and which uses the <code>Event</code>
467: interface, <em class=ct>must</em> be dispatched at the <code><a
468: href="#xmlhttprequest-object">XMLHttpRequest</a></code> object.
1.156 avankest 469:
1.168 avankest 470: <h3 id=extensibility><span class=secno>2.3 </span>Extensibility</h3>
1.2 avankest 471:
1.82 avankest 472: <p>Extensions of the API defined by this specification are <em>strongly
1.31 avankest 473: discouraged</em>. User agents, Working Groups and other interested parties
1.35 avankest 474: should discuss extensions on a relevant public forum, preferably <a
1.31 avankest 475: href="mailto:public-webapi@w3.org">public-webapi@w3.org</a>.
1.2 avankest 476:
1.204 avankest 477: <h2 id=security><span class=secno>3 </span>Security Considerations</h2>
1.154 avankest 478:
1.205 avankest 479: <p>Security related requirements are made throughout this specification.
1.154 avankest 480:
1.204 avankest 481: <h2 id=xmlhttprequest><span class=secno>4 </span>The <code
1.16 avankest 482: title="">XMLHttpRequest</code> Object</h2>
1.2 avankest 483:
1.60 avankest 484: <p>The <code><a href="#xmlhttprequest-object">XMLHttpRequest</a></code>
485: object can be used by scripts to programmatically connect to their
486: originating server via HTTP.
1.2 avankest 487:
1.60 avankest 488: <pre
1.205 avankest 489: class=idl>[<a href="#xmlhttprequest-constructor" title="XMLHttpRequest constructor">Constructor</a>,
490: Implements=EventTarget]
491: interface <dfn id=xmlhttprequest-object>XMLHttpRequest</dfn> {
1.208 avankest 492: // <a href="#event-handler-attributes">event handler attributes</a>
493: attribute <a href="#function">Function</a> <a href="#onreadystatechange">onreadystatechange</a>;
1.60 avankest 494:
1.208 avankest 495: // <a href="#states">states</a>
1.135 avankest 496: const unsigned short <a href="#unsent-state" title="UNSENT state">UNSENT</a> = 0;
497: const unsigned short <a href="#opened-state" title="OPENED state">OPENED</a> = 1;
1.132 avankest 498: const unsigned short <a href="#headers-received-state" title="HEADERS_RECEIVED state">HEADERS_RECEIVED</a> = 2;
499: const unsigned short <a href="#loading-state" title="LOADING state">LOADING</a> = 3;
500: const unsigned short <a href="#done-state" title="DONE state">DONE</a> = 4;
501: readonly attribute unsigned short <a href="#readystate">readyState</a>;
1.60 avankest 502:
1.207 avankest 503: // <a href="#request">request</a>
1.205 avankest 504: void <a href="#open">open</a>(in DOMString <var>method</var>, in DOMString <var title="">url</var>);
505: void <a href="#open">open</a>(in DOMString <var>method</var>, in DOMString <var title="">url</var>, in boolean <var>async</var>);
506: void <a href="#open">open</a>(in DOMString <var>method</var>, in DOMString <var title="">url</var>, in boolean <var>async</var>, [Null=Null, Undefined=Null] in DOMString <var>user</var>);
507: void <a href="#open">open</a>(in DOMString <var>method</var>, in DOMString <var title="">url</var>, in boolean <var>async</var>, [Null=Null, Undefined=Null] in DOMString <var>user</var>, [Null=Null, Undefined=Null] in DOMString <var>password</var>);
1.132 avankest 508: void <a href="#setrequestheader">setRequestHeader</a>(in DOMString <var>header</var>, in DOMString <var>value</var>);
509: void <a href="#send">send</a>();
1.182 avankest 510: void <a href="#send">send</a>([Null=Null, Undefined=Null] in DOMString <var>data</var>);
1.132 avankest 511: void <a href="#send">send</a>(in Document <var>data</var>);
512: void <a href="#abort">abort</a>();
1.60 avankest 513:
1.207 avankest 514: // <a href="#response">response</a>
1.205 avankest 515: readonly attribute unsigned short <a href="#status">status</a>;
516: readonly attribute DOMString <a href="#statustext">statusText</a>;
517: DOMString <a href="#getresponseheader">getResponseHeader</a>(in DOMString <var>header</var>);
1.132 avankest 518: DOMString <a href="#getallresponseheaders">getAllResponseHeaders</a>();
519: readonly attribute DOMString <a href="#responsetext">responseText</a>;
520: readonly attribute Document <a href="#responsexml">responseXML</a>;
1.5 avankest 521: };</pre>
1.2 avankest 522:
1.205 avankest 523: <h3 id=origin-and-base-url><span class=secno>4.1 </span>Origin and Base URL</h3>
524:
525: <p>Each <code><a href="#xmlhttprequest-object">XMLHttpRequest</a></code>
526: object has an associated <dfn
527: id=xmlhttprequest-origin><code>XMLHttpRequest</code> origin</dfn> and an
528: <dfn id=xmlhttprequest-base-url><code>XMLHttpRequest</code> base
529: URL</dfn>.
530:
531: <p>This specification defines their values when the global object is
532: represented by the <code>Window</code> object. When the <code><a
533: href="#xmlhttprequest-object">XMLHttpRequest</a></code> object used in
534: other contexts their values will have to be defined as appropriate for
535: that context. That is considered to be out of scope for this
536: specification.
537:
538: <hr>
539:
540: <p>In environments where the global object is represented by the
541: <code>Window</code> object the <code><a
542: href="#xmlhttprequest-object">XMLHttpRequest</a></code> object has an
543: associated <dfn id=xmlhttprequest-document><code>XMLHttpRequest</code>
544: <code>Document</code></dfn> which is the <code>Document</code> object
545: associated with the <code>Window</code> object for which the <code><a
546: href="#xmlhttprequest-object">XMLHttpRequest</a></code> interface object
547: was created.
548:
549: <p class=note>The <a
550: href="#xmlhttprequest-document"><code>XMLHttpRequest</code>
551: <code>Document</code></a> is used to determine the <a
552: href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> and
553: <a href="#xmlhttprequest-base-url"><code>XMLHttpRequest</code> base
554: URL</a> at a later stage.</p>
555: <!-- XXX what happens if the document is not fully active?
556: e.g. should the constructor throw?
557: -->
558:
559: <h3 id=task-sources><span class=secno>4.2 </span>Task Sources</h3>
560:
561: <p>The following <a href="#task-source" title="task source">task
562: sources</a> are used by this specification:
563:
564: <dl>
565: <dt>The <dfn
566: id=xmlhttprequest-event-task-source><code>XMLHttpRequest</code> event
567: task source</dfn>
568:
569: <dd>This <a href="#task-source">task source</a> is used for events that
570: are to be asynchronously dispatched.
571:
572: <dt>The <dfn
573: id=xmlhttprequest-networking-task-source><code>XMLHttpRequest</code>
574: networking task source</dfn>
575:
576: <dd>This <a href="#task-source">task source</a> is used for network
577: activity.
578: </dl>
579:
580: <p>Unless otherwise stated the <a href="#task-source">task source</a> used
581: for all tasks <a href="#queue-a-task" title="queue a task">queued</a> in
582: this specification is the <a
583: href="#xmlhttprequest-event-task-source"><code>XMLHttpRequest</code> event
584: task source</a>.
585:
586: <h3 id=constructor><span class=secno>4.3 </span>Constructor</h3>
587:
588: <p>When the <dfn id=xmlhttprequest-constructor title="XMLHttpRequest
589: constructor"><code title="">XMLHttpRequest()</code></dfn> constructor is
590: invoked, the user agent <em class=ct>must</em> return a new <code><a
591: href="#xmlhttprequest-object">XMLHttpRequest</a></code> object.
592:
1.207 avankest 593: <h3 id=event-handler-attributes><span class=secno>4.4 </span>Event Handler
594: Attributes</h3>
595:
596: <p>The following is the <a href="#event-handler-attributes-0" title="event
597: handler attributes">event handler attribute</a> (and its corresponding <a
598: href="#event-handler-event-type">event handler event type</a>) that <em
599: class=ct>must</em> be supported as DOM attribute by the <code><a
600: href="#xmlhttprequest-object">XMLHttpRequest</a></code> object:
601:
602: <table>
603: <thead>
604: <tr>
605: <th><a href="#event-handler-attributes-0" title="event handler
606: attributes">event handler attribute</a>
607:
608: <th><a href="#event-handler-event-type">event handler event type</a>
609:
610: <tbody>
611: <tr>
612: <td><dfn id=onreadystatechange><code>onreadystatechange</code></dfn>
613:
614: <td><code>readystatechange</code>
615: </table>
616:
617: <h3 id=states><span class=secno>4.5 </span>States</h3>
1.205 avankest 618:
1.60 avankest 619: <p>The <code><a href="#xmlhttprequest-object">XMLHttpRequest</a></code>
1.205 avankest 620: object can be in several states. The <dfn
621: id=readystate><code>readyState</code></dfn> attribute, on getting, <em
622: class=ct>must</em> return the current state, which <em class=ct>must</em>
623: be one of the following values:
624:
625: <dl>
626: <dt><dfn id=unsent-state title="UNSENT state"><code>UNSENT</code></dfn>
627: (numeric value 0)
1.125 avankest 628:
1.205 avankest 629: <dd>
630: <p>The object has been constructed.
631:
632: <dt><dfn id=opened-state title="OPENED state"><code>OPENED</code></dfn>
633: (numeric value 1)
634:
635: <dd>
636: <p>The <code><a href="#open">open()</a></code> method has been
637: successfully invoked. During this state request headers can be set using
638: <code><a href="#setrequestheader">setRequestHeader()</a></code> and the
639: request can be made using the <code><a href="#send">send()</a></code>
640: method.
1.89 avankest 641:
1.205 avankest 642: <dt><dfn id=headers-received-state title="HEADERS_RECEIVED
643: state"><code>HEADERS_RECEIVED</code></dfn> (numeric value 2)
1.89 avankest 644:
1.205 avankest 645: <dd>
646: <p>All HTTP headers have been received. Several response members of the
647: object are now available.
1.91 avankest 648:
1.205 avankest 649: <dt><dfn id=loading-state title="LOADING state"><code>LOADING</code></dfn>
650: (numeric value 3)
1.112 avankest 651:
1.205 avankest 652: <dd>
653: <p>The <a href="#response-entity-body">response entity body</a> is being
654: received.
1.91 avankest 655:
1.205 avankest 656: <dt><dfn id=done-state title="DONE state"><code>DONE</code></dfn> (numeric
657: value 4)
1.119 avankest 658:
1.205 avankest 659: <dd>
660: <p>The data transfer has been completed or something went wrong during
661: the transfer (e.g. infinite redirects).
662: </dl>
1.116 avankest 663:
1.205 avankest 664: <p>The <a href="#opened-state" title="OPENED state">OPENED</a> state has an
665: associated <dfn id=send-flag><code>send()</code> flag</dfn> that indicates
666: whether the <code><a href="#send">send()</a></code> method has been
667: invoked. It can be either true or false and has an initial value of false.
668:
669: <p>The <a href="#done-state" title="DONE state">DONE</a> state has an
670: associated <dfn id=error-flag>error flag</dfn> that indicates some type of
671: network error or abortion. It can be either true or false and has an
672: initial value of false.
673:
674: <h3 id=request><span class=secno>4.6 </span>Request</h3>
1.112 avankest 675:
1.205 avankest 676: <p>The <code><a href="#xmlhttprequest-object">XMLHttpRequest</a></code>
677: object holds the following request metadata variables:
1.112 avankest 678:
1.206 avankest 679: <dl>
680: <dt>The <dfn id=asynchronous-flag>asynchronous flag</dfn>
681:
682: <dd>A flag that is either true or false that indicates whether the request
683: is done asynchronously.
684:
685: <dt>The <dfn id=request-method>request method</dfn>
686:
687: <dd>The method used in the request.
688:
689: <dt>The <dfn id=request-url>request URL</dfn>
690:
691: <dd>The <a href="#url">URL</a> used in the request.
692:
693: <dt>The <dfn id=request-username>request username</dfn>
694:
695: <dd>The username used in the request or null if there is no username.
696:
697: <dt>The <dfn id=request-password>request password</dfn>
698:
699: <dd>The password used in the request or null if there is no password.
1.112 avankest 700:
1.206 avankest 701: <dt>The <dfn id=author-request-headers>author request headers</dfn>
1.112 avankest 702:
1.206 avankest 703: <dd>A list consisting of HTTP header name/value pairs to be used in the
704: request.
1.112 avankest 705:
1.206 avankest 706: <dt>The <dfn id=request-entity-body>request entity body</dfn>
1.112 avankest 707:
1.206 avankest 708: <dd>The <a href="#entity-body">entity body</a> used in the request.
709: </dl>
1.205 avankest 710:
711: <h4 id=the-open-method><span class=secno>4.6.1 </span>The <code
712: title="">open()</code> method</h4>
713:
714: <p>When the <dfn id=open title=open><code>open(<var>method</var>, <var
715: title="">url</var>, <var>async</var>, <var>user</var>,
716: <var>password</var>)</code></dfn> method is invoked, the user agent <em
717: class=ct>must</em> run the following steps (unless otherwise indicated):
1.112 avankest 718:
1.205 avankest 719: <ol>
720: <li>
721: <p>If the <code><a
722: href="#xmlhttprequest-object">XMLHttpRequest</a></code> object has an
723: associated <a
724: href="#xmlhttprequest-document"><code>XMLHttpRequest</code>
725: <code>Document</code></a> run these substeps:</p>
1.112 avankest 726:
1.205 avankest 727: <ol>
728: <li>
729: <p>If the <a
730: href="#xmlhttprequest-document"><code>XMLHttpRequest</code>
731: <code>Document</code></a> is not <a href="#fully-active">fully
732: active</a> raise an <code>INVALID_STATE_ERR</code> exception and
733: terminate the overall set of steps.
734:
735: <li>
736: <p>Let <a href="#xmlhttprequest-base-url"><code>XMLHttpRequest</code>
737: base URL</a> be the <a href="#document-base-url">document base URL</a>
738: of the <a href="#xmlhttprequest-document"><code>XMLHttpRequest</code>
739: <code>Document</code></a>.
740:
741: <li>
742: <p>Let <a href="#xmlhttprequest-origin"><code>XMLHttpRequest</code>
743: origin</a> be the <a href="#origin">origin</a> of the <a
744: href="#xmlhttprequest-document"><code>XMLHttpRequest</code>
745: <code>Document</code></a>.
746: </ol>
1.112 avankest 747:
748: <li>
1.205 avankest 749: <p>If <var>method</var> does not match the <a href="#method-token">Method
1.212 ! avankest 750: token</a> production raise a <code>SYNTAX_ERR</code> exception and
! 751: terminate these steps.
1.91 avankest 752:
753: <li>
1.205 avankest 754: <p>If <var>method</var> is an <a href="#ascii-case-insensitive">ASCII
755: case-insensitive</a> match for <code>CONNECT</code>,
756: <code>DELETE</code>, <code>GET</code>, <code>HEAD</code>,
757: <code>OPTIONS</code>, <code>POST</code>, <code>PUT</code>,
1.211 avankest 758: <code>TRACE</code>, or <code>TRACK</code> <a
759: href="#converted-to-ascii-upercase" title="converted to ASCII
760: uppercase">convert <var>method</var> to ASCII uppercase</a>.</p>
1.205 avankest 761:
762: <p class=note>If it does not match any of the above, it is passed through
763: <em>literally</em>, including in the final request.</p>
764: </li>
765: <!-- WebKit (and supposedly Gecko) also uppercase: COPY, INDEX, LOCK,
766: M-POST, MKCOL, MOVE, PROPFIND, PROPPATCH, and UNLOCK. -->
1.89 avankest 767:
1.205 avankest 768: <li>
1.211 avankest 769: <p>If <var>method</var> is a <a href="#case-sensitive">case-sensitive</a>
770: match for <code>CONNECT</code>, <code>TRACE</code>, or
771: <code>TRACK</code> the user agent <em class=ct>should</em> raise a
772: <code><a href="#security-err">SECURITY_ERR</a></code> exception and
773: terminate these steps.</p>
1.164 avankest 774:
1.205 avankest 775: <p class=note>Allowing these methods poses a security risk. [<cite><a
776: href="#ref-httpverbsec">HTTPVERBSEC</a></cite>]</p>
1.89 avankest 777:
1.91 avankest 778: <li>
1.205 avankest 779: <p>Let <var title="">url</var> be a <a href="#url">URL</a>.
1.89 avankest 780:
781: <li>
1.205 avankest 782: <p>Let <a href="#url-character-encoding">URL character encoding</a> of
783: <var title="">url</var> be UTF-8.
1.89 avankest 784:
785: <li>
1.205 avankest 786: <p><a href="#resolve-a-url" title="Resolve a URL">Resolve <var
787: title="">url</var></a> relative to the <a
788: href="#xmlhttprequest-base-url"><code>XMLHttpRequest</code> base
789: URL</a>. If the algorithm returns an error raise a
790: <code>SYNTAX_ERR</code> exception and terminate these steps.
791: </li>
792: <!-- Presto and Gecko override the encoding. WebKit does not. Trident
793: does not support non-ASCII URLs. This matters for the <query> component,
794: see HTML5. -->
1.129 avankest 795:
1.205 avankest 796: <li>
797: <p>Drop <code><a href="#url-fragment"><fragment></a></code> from <var
798: title="">url</var>.
1.89 avankest 799:
800: <li>
1.205 avankest 801: <p>If <var title="">url</var> contains an unsupported <code><a
802: href="#url-scheme"><scheme></a></code> raise a
803: <code>NOT_SUPPORTED_ERR</code> and terminate these steps.
1.89 avankest 804:
1.205 avankest 805: <li>
806: <p>If the <code>"user:password"</code> format in the <code><a
807: href="#userinfo">userinfo</a></code> production is not supported for the
808: relevant scheme and <var title="">url</var> contains this format raise a
809: <code>SYNTAX_ERR</code> and terminate these steps.
1.2 avankest 810:
1.205 avankest 811: <li>
812: <p>If <var title="">url</var> contains the <code>"user:password"</code>
813: format let <var>temp user</var> be the user part and <var>temp
814: password</var> be the password part.
1.2 avankest 815:
1.205 avankest 816: <li>
817: <p>If <var title="">url</var> just contains the <code>"user"</code>
818: format let <var>temp user</var> be the user part.
1.2 avankest 819:
1.205 avankest 820: <li>
821: <p>If the <a href="#origin">origin</a> of <var title="">url</var> is not
822: <a href="#same-origin">same origin</a> with the <a
823: href="#xmlhttprequest-origin"><code>XMLHttpRequest</code> origin</a> the
824: user agent <em class=ct>should</em> raise a <code><a
825: href="#security-err">SECURITY_ERR</a></code> exception and terminate
826: these steps.
1.2 avankest 827:
1.205 avankest 828: <li>
829: <p>Let <var>async</var> be the value of the <var>async</var> argument or
830: <code>true</code> if it was omitted.
1.2 avankest 831:
1.205 avankest 832: <li>
833: <p>If the <var>user</var> argument was not omitted follow these sub
834: steps:</p>
1.2 avankest 835:
1.60 avankest 836: <ol>
837: <li>
1.205 avankest 838: <p>If the syntax of <var>user</var> does not match the syntax specified
839: by the relevant authentication scheme, raise a <code>SYNTAX_ERR</code>
840: exception and terminate the overall set of steps.
1.157 avankest 841:
842: <li>
1.205 avankest 843: <p>If <var>user</var> is <code>null</code> let <var>temp user</var> be
844: null.
1.2 avankest 845:
1.60 avankest 846: <li>
1.205 avankest 847: <p>Otherwise let <var>temp user</var> be <var>user</var>.
848: </ol>
1.184 avankest 849:
1.205 avankest 850: <p class=note>These steps override anything that may have been set by the
851: <var title="">url</var> argument.</p>
1.157 avankest 852:
1.205 avankest 853: <li>
854: <p>If the <var>password</var> argument was not omitted follow these sub
855: steps:</p>
1.2 avankest 856:
1.205 avankest 857: <ol>
1.60 avankest 858: <li>
1.205 avankest 859: <p>If the syntax of <var>password</var> does not match the syntax
860: specified by the relevant authentication scheme, raise a
861: <code>SYNTAX_ERR</code> exception and terminate the overall set of
862: steps.
1.192 avankest 863:
864: <li>
1.205 avankest 865: <p>If <var>password</var> is <code>null</code> let <var>temp
866: password</var> be null.
1.2 avankest 867:
1.60 avankest 868: <li>
1.205 avankest 869: <p>Otherwise let <var>temp password</var> be <var>password</var>.
870: </ol>
1.102 avankest 871:
1.205 avankest 872: <p class=note>These steps override anything that may have been set by the
873: <var title="">url</var> argument.</p>
1.2 avankest 874:
1.205 avankest 875: <li>
876: <p><a href="#abort-send-algorithm" title="abort send()">Abort the
877: <code>send()</code> algorithm</a>.
1.2 avankest 878:
1.205 avankest 879: <li>
880: <p>The user agent <em class=ct>should</em> cancel any network activity
881: for which the object is responsible.
882: </li>
883: <!-- we can hardly require it... -->
1.24 avankest 884:
1.205 avankest 885: <li>
886: <p>Set variables associated with the object as follows:</p>
1.70 avankest 887:
1.205 avankest 888: <ul>
1.60 avankest 889: <li>
1.205 avankest 890: <p>Set the <a href="#send-flag"><code>send()</code> flag</a> to false.
1.60 avankest 891:
892: <li>
1.205 avankest 893: <p>Set <a href="#response-entity-body">response entity body</a> to
894: null.
1.60 avankest 895:
896: <li>
1.205 avankest 897: <p>Empty the list of <a href="#author-request-headers">author request
898: headers</a>.</p>
1.17 avankest 899:
1.60 avankest 900: <li>
1.205 avankest 901: <p>Set the <a href="#request-method">request method</a> to
902: <var>method</var>.
1.17 avankest 903:
1.60 avankest 904: <li>
1.205 avankest 905: <p>Set the <a href="#request-url">request URL</a> to <var
906: title="">url</var>.
1.17 avankest 907:
1.60 avankest 908: <li>
1.205 avankest 909: <p>Set the <a href="#request-username">request username</a> to
910: <var>temp user</var>.
1.17 avankest 911:
1.60 avankest 912: <li>
1.205 avankest 913: <p>Set the <a href="#request-password">request password</a> to
914: <var>temp password</var>.
1.17 avankest 915:
1.60 avankest 916: <li>
1.205 avankest 917: <p>Set the <a href="#asynchronous-flag">asynchronous flag</a> to true
918: if <var>async</var> is <code>true</code>. Otherwise set it to false.
919: </ul>
1.44 avankest 920:
1.205 avankest 921: <li>
922: <p>Switch the the state to <a href="#opened-state" title="OPENED
923: state">OPENED</a>.
1.176 avankest 924:
1.205 avankest 925: <li>
926: <p><a href="#dispatch-readystatechange-event">Dispatch a
927: <code>readystatechange</code> event</a>.
928: </ol>
1.22 avankest 929:
1.205 avankest 930: <p class=note>A future version or extension of this specification will
931: define a way of doing cross-origin requests.
1.24 avankest 932:
1.205 avankest 933: <h4 id=the-setrequestheader-method><span class=secno>4.6.2 </span>The <code
934: title="">setRequestHeader()</code> method</h4>
935: <!-- XXX authors
936: The <code>setRequestHeader()</code> method can be used to set new request
937: headers and append to request headers already in the list.</p>
938: -->
939:
940: <p>As indicated in the algorithm below certain headers cannot be set and
941: are left up to the user agent. In addition there are certain other headers
942: the user agent will take control of if they are not set by the author as
943: indicated at the end of the <code><a href="#send">send()</a></code> method
944: section.
945:
946: <p class=note>The <code><a
947: href="#setrequestheader">setRequestHeader()</a></code> method appends a
948: value if the HTTP header given as argument is already part of the <a
949: href="#author-request-headers">author request headers</a> list.
950:
951: <p>When the <dfn id=setrequestheader
952: title=setrequestheader><code>setRequestHeader(<var>header</var>,
953: <var>value</var>)</code></dfn> method is invoked, the user agent <em
954: class=ct>must</em> run the following steps (unless otherwise indicated):
1.6 avankest 955:
1.205 avankest 956: <ol>
957: <li>
958: <p>If the state is not <a href="#opened-state" title="OPENED
959: state">OPENED</a> raise an <code>INVALID_STATE_ERR</code> exception and
960: terminate these steps.
1.47 avankest 961:
1.205 avankest 962: <li>
963: <p>If the <a href="#send-flag"><code>send()</code> flag</a> is true raise
964: an <code>INVALID_STATE_ERR</code> exception and terminate these steps.
1.60 avankest 965:
1.205 avankest 966: <li>
967: <p>If <var>header</var> does not match the <code><a
968: href="#field-name">field-name</a></code> production raise a
969: <code>SYNTAX_ERR</code> exception and terminate these steps.
1.6 avankest 970:
1.205 avankest 971: <li>
972: <p>If the <var>value</var> argument does not match the <code><a
973: href="#field-value">field-value</a></code> production raise a
974: <code>SYNTAX_ERR</code> and terminate these steps.</p>
1.60 avankest 975:
1.205 avankest 976: <p class=note>The empty string is legal and represents the empty header
977: value.</p>
1.71 avankest 978:
1.205 avankest 979: <li>
980: <p>For security reasons, these steps <em class=ct>should</em> be
981: terminated if <var>header</var> is an <a
982: href="#ascii-case-insensitive">ASCII case-insensitive</a> match for one
983: of the following headers:</p>
1.179 avankest 984:
1.205 avankest 985: <ul>
986: <li><code>Accept-Charset</code>
1.60 avankest 987:
1.205 avankest 988: <li><code>Accept-Encoding</code>
1.34 avankest 989:
1.205 avankest 990: <li><code>Authorization</code>
1.34 avankest 991:
1.205 avankest 992: <li><code>Connection</code>
1.34 avankest 993:
1.205 avankest 994: <li><code>Content-Length</code>
1.177 avankest 995:
1.205 avankest 996: <li><code>Cookie</code>
1.69 avankest 997:
1.205 avankest 998: <li><code>Cookie2</code>
1.34 avankest 999:
1.205 avankest 1000: <li><code>Content-Transfer-Encoding</code>
1.177 avankest 1001:
1.205 avankest 1002: <li><code>Date</code>
1.177 avankest 1003:
1.205 avankest 1004: <li><code>Expect</code>
1.69 avankest 1005:
1.205 avankest 1006: <li><code>Host</code>
1.69 avankest 1007:
1.205 avankest 1008: <li><code>Keep-Alive</code>
1.34 avankest 1009:
1.205 avankest 1010: <li><code>Referer</code>
1.34 avankest 1011:
1.205 avankest 1012: <li><code>TE</code>
1.34 avankest 1013:
1.205 avankest 1014: <li><code>Trailer</code>
1.34 avankest 1015:
1.205 avankest 1016: <li><code>Transfer-Encoding</code>
1.34 avankest 1017:
1.205 avankest 1018: <li><code>Upgrade</code>
1.34 avankest 1019:
1.205 avankest 1020: <li><code>User-Agent</code>
1.34 avankest 1021:
1.205 avankest 1022: <li><code>Via</code>
1023: </ul>
1.69 avankest 1024:
1.205 avankest 1025: <p>… or if the start of <var>header</var> is an <a
1026: href="#ascii-case-insensitive">ASCII case-insensitive</a> match for
1027: <code>Proxy-</code> or <code>Sec-</code> (including when
1028: <var>header</var> is just <code>Proxy-</code> or <code>Sec-</code>).</p>
1029:
1030: <p class=note>The above headers are not allowed to be set as they are
1031: better controlled by the user agent as it knows best what value they
1032: should have. Header names starting with <code>Sec-</code> are not
1033: allowed to be set to allow new headers to be minted in the future that
1034: are guaranteed not to come from <code><a
1035: href="#xmlhttprequest-object">XMLHttpRequest</a></code>. (Older clients
1036: would however still be vulnerable as they allow such headers to be set.)</p>
1.185 avankest 1037:
1.205 avankest 1038: <li>
1039: <p>If <var>header</var> is not in the <a
1040: href="#author-request-headers">author request headers</a> list append
1041: <var>header</var> with its associated <var>value</var> to the list and
1042: terminate these steps.
1.6 avankest 1043:
1.205 avankest 1044: <li>
1045: <p>If <var>header</var> is in the <a
1046: href="#author-request-headers">author request headers</a> list either
1047: use multiple headers, combine the values or use a combination of those
1048: (section 4.2, RFC 2616). [<cite><a
1049: href="#ref-rfc2616">RFC2616</a></cite>]
1050: </li>
1051: <!-- XXX it seems UAs always combine the values -->
1052: </ol>
1.18 avankest 1053:
1.205 avankest 1054: <p class=note>See also the <code><a href="#send">send()</a></code> method
1055: regarding user agent header handling for caching, authentication, proxies,
1056: and cookies.
1.47 avankest 1057:
1.205 avankest 1058: <div class=example>
1059: <pre><code>// The following script:
1.18 avankest 1060: var client = new XMLHttpRequest();
1061: client.open('GET', 'demo.cgi');
1062: client.setRequestHeader('X-Test', 'one');
1063: client.setRequestHeader('X-Test', 'two');
1064: client.send();
1065:
1066: // ...would result in the following header being sent:
1067: ...
1068: X-Test: one, two
1.60 avankest 1069: ...</code></pre>
1.205 avankest 1070: </div>
1.6 avankest 1071:
1.205 avankest 1072: <h4 id=the-send-method><span class=secno>4.6.3 </span>The <code
1073: title="">send()</code> method</h4>
1.2 avankest 1074:
1.205 avankest 1075: <p>The <code><a href="#send">send()</a></code> method initiates the request
1.206 avankest 1076: and its optional argument provides the <a
1077: href="#request-entity-body">request entity body</a>.
1.205 avankest 1078:
1079: <p class=note>Authors are encouraged to ensure that they have specified the
1080: <code>Content-Type</code> header via <code><a
1081: href="#setrequestheader">setRequestHeader()</a></code> before invoking
1082: <code><a href="#send">send()</a></code> with a non-<code>null</code>
1083: <var>data</var> argument.
1084:
1085: <p>When the <dfn id=send
1086: title=send><code>send(<var>data</var>)</code></dfn> method is invoked, the
1087: user agent <em class=ct>must</em> run the following steps (unless
1088: otherwise noted). This algorithm gets aborted when the <code><a
1089: href="#open">open()</a></code> or <code><a
1090: href="#abort">abort()</a></code> method is invoked. When the <dfn
1091: id=abort-send-algorithm title="abort send()"><code>send()</code> algorithm
1092: is aborted</dfn> the user agent <em class=ct>must</em> terminate the
1093: algorithm after finishing the step it is on.
1094:
1095: <p class=note>The <code title="">send()</code> algorithm can only be
1096: aborted when the <a href="#asynchronous-flag">asynchronous flag</a> is
1097: true and only after the method call has returned.
1.60 avankest 1098:
1.205 avankest 1099: <ol>
1100: <li>
1101: <p>If the state is not <a href="#opened-state" title="OPENED
1102: state">OPENED</a> raise an <code>INVALID_STATE_ERR</code> exception and
1103: terminate these steps.
1.60 avankest 1104:
1.205 avankest 1105: <li>
1106: <p>If the <a href="#send-flag"><code>send()</code> flag</a> is true raise
1107: an <code>INVALID_STATE_ERR</code> exception and terminate these steps.
1.60 avankest 1108:
1.205 avankest 1109: <li>
1110: <p>If the <span>request method is <code>GET</code> or <code>HEAD</code>
1111: act as if <var>data</var> is <code>null</code>.</span></p>
1.203 avankest 1112:
1.205 avankest 1113: <p>If the <var>data</var> argument has not been omitted and is not
1.206 avankest 1114: <code>null</code> use it for the <a href="#request-entity-body">request
1115: entity body</a> observing the following rules:</p>
1.205 avankest 1116:
1117: <dl class=switch>
1118: <dt><var>data</var> is a <code>DOMString</code>
1119:
1120: <dd>
1121: <p>Encode <var>data</var> using UTF-8 for transmission.</p>
1122:
1123: <p>If a <code>Content-Type</code> header is set using <code><a
1124: href="#setrequestheader">setRequestHeader()</a></code> and its value
1125: is not malformed, set the <code>charset</code> parameter of that
1126: header, by either changing the <code>charset</code> parameter (if one
1127: is present) or appending one, to <code>UTF-8</code>.</p>
1128:
1129: <p>If no <code>Content-Type</code> header has been set using <code><a
1130: href="#setrequestheader">setRequestHeader()</a></code> set a
1131: <code>Content-Type</code> request header with a value of
1132: <code>text/plain;charset=UTF-8</code>.</p>
1.210 avankest 1133: <!-- XXX not all UAs modify Content-Type -->
1.205 avankest 1134:
1135: <dt><var>data</var> is a <code>Document</code>
1136:
1137: <dd>
1.210 avankest 1138: <p>Let <var>tempdata</var> be the result of following the <a
1139: href="#xml-fragment-serialization-algorithm">XML fragment
1140: serialization algorithm</a> for a <code>Document</code> on
1141: <var>data</var> and encode it using
1.205 avankest 1142: <code><var>data</var>.inputEncoding</code> or UTF-8 if
1143: <code><var>data</var>.inputEncoding</code> is <code>null</code>.
1.210 avankest 1144: Re-raise any exception this algorithm raises.</p>
1145:
1146: <p>Let <var>data</var> be <var>tempdata</var>.</p>
1147:
1.205 avankest 1148: <p class=note>If the document cannot be serialized the
1149: <code>document.innerHTML</code> algorithm raises an
1150: <code>INVALID_STATE_ERR</code> exception.</p>
1151:
1152: <p>If a <code>Content-Type</code> header is set using <code><a
1153: href="#setrequestheader">setRequestHeader()</a></code> and its value
1154: is not malformed, set the <code>charset</code> parameter of that
1155: header, by either changing the <code>charset</code> parameter (if one
1.210 avankest 1156: is present) or appending one, to the encoding used to encode
1157: <var>data</var>.</p>
1.205 avankest 1158:
1159: <p>If no <code>Content-Type</code> header has been set using <code><a
1160: href="#setrequestheader">setRequestHeader()</a></code> set a
1161: <code>Content-Type</code> request header with a value of
1162: <code>application/xml;charset=<var>charset</var></code> where
1.210 avankest 1163: <var>charset</var> is the encoding used to encode <var>data</var>.</p>
1.205 avankest 1164:
1165: <p class=note>Subsequent changes to the <code>Document</code> have no
1166: effect on what is submitted.</p>
1.210 avankest 1167: <!-- XXX not all UAs modify Content-Type
1168: different algorithm for HTML? -->
1169:
1.205 avankest 1170:
1171: <dt><var>data</var> is not a <code>DOMString</code> or
1172: <code>Document</code>
1173:
1174: <dd>
1175: <p>Use the stringification mechanisms of the host language on
1176: <var>data</var> and treat the result as if <var>data</var> is a
1.210 avankest 1177: <code>DOMString</code>. Re-raise any exceptions the stringification
1178: mechanism raises.
1.205 avankest 1179: </dd>
1.210 avankest 1180: <!-- XXX do we need to state this? -->
1.205 avankest 1181: </dl>
1.103 avankest 1182:
1.205 avankest 1183: <p>If the <var>data</var> argument has been omitted, or is
1.206 avankest 1184: <code>null</code>, no <a href="#request-entity-body">request entity
1185: body</a> is used in the request.</p>
1.167 avankest 1186:
1.205 avankest 1187: <li>
1188: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is false
1189: release the <a href="#storage-mutex">storage mutex</a>.
1.60 avankest 1190:
1.205 avankest 1191: <li>
1192: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is true set
1193: the <a href="#send-flag"><code>send()</code> flag</a> to true.
1.60 avankest 1194:
1.205 avankest 1195: <li>
1196: <p>Set the <a href="#error-flag">error flag</a> to false.
1.164 avankest 1197:
1.205 avankest 1198: <li>
1199: <dl>
1200: <dt>If the <a href="#asynchronous-flag">asynchronous flag</a> is false
1.195 avankest 1201:
1.205 avankest 1202: <dd>
1203: <ol>
1204: <li>
1205: <p>Make a request to <a href="#request-url">request URL</a>, using
1206: HTTP method <a href="#request-method">request method</a>, user <a
1207: href="#request-username">request username</a> (if non-null) and
1208: password <a href="#request-password">request password</a> (if
1.206 avankest 1209: non-null), taking into account the <a
1210: href="#request-entity-body">request entity body</a>, list of <a
1.205 avankest 1211: href="#author-request-headers">author request headers</a> and the
1212: rules listed at the end of this section.</p>
1.60 avankest 1213:
1.205 avankest 1214: <p>If there are cookies to be set, run these substeps:</p>
1.119 avankest 1215:
1216: <ol>
1217: <li>
1.205 avankest 1218: <p>Wait until ownership of the <a href="#storage-mutex">storage
1219: mutex</a> can be taken.
1.119 avankest 1220:
1221: <li>
1.205 avankest 1222: <p>Take ownership of the <a href="#storage-mutex">storage
1223: mutex</a>.
1.119 avankest 1224:
1225: <li>
1.205 avankest 1226: <p>Update the cookies. [<cite><a
1227: href="#ref-cookies=">COOKIES</a></cite>]
1.119 avankest 1228:
1229: <li>
1.205 avankest 1230: <p>Release the <a href="#storage-mutex">storage mutex</a> so that
1231: it is once again free.
1.119 avankest 1232: </ol>
1233:
1.205 avankest 1234: <p>While making the request also follow the <a
1235: href="#request-event-rules">request event rules</a>.</p>
1.119 avankest 1236:
1.205 avankest 1237: <p>When the request is completed and has not been terminated by the
1238: <a href="#request-event-rules">request event rules</a> go to the
1239: next step.</p>
1240: </li>
1241: <!--
1242: This cannot involve any task queue whatsoever because that would
1243: mean other tasks on the task queue might get processed as well which
1244: is counter to the whole idea of doing things synchronous.
1245: -->
1246:
1247: <li>
1248: <p>If the overall algorithm has not been terminated at this stage the
1249: request was successful. Run these substeps:</p>
1.119 avankest 1250:
1251: <ol>
1252: <li>
1.205 avankest 1253: <p>Switch the state to <a href="#done-state" title="DONE
1254: state">DONE</a>.
1.119 avankest 1255:
1256: <li>
1.205 avankest 1257: <p><a href="#dispatch-readystatechange-event">Dispatch a
1258: <code>readystatechange</code> event</a>.
1.119 avankest 1259: </ol>
1260:
1.205 avankest 1261: <p class=note>The <code><a href="#send">send()</a></code> method call
1262: will now be returned by virtue of this algorithm ending.</p>
1263: </ol>
1264:
1265: <dt>If the <a href="#asynchronous-flag">asynchronous flag</a> is true
1266:
1267: <dd>
1268: <ol>
1269: <li>
1270: <p><a href="#dispatch-readystatechange-event">Dispatch a
1271: <code>readystatechange</code> event</a>.</p>
1272:
1273: <p class=note>The state does not change. The event is dispatched for
1274: historical reasons.</p>
1275:
1276: <li>
1277: <p>Return the <code><a href="#send">send()</a></code> method call,
1278: but continue running the steps in this algorithm.
1279:
1280: <li>
1281: <p>Make a request to <a href="#request-url">request URL</a>, using
1282: HTTP method <a href="#request-method">request method</a>, user <a
1283: href="#request-username">request username</a> (if non-null) and
1284: password <a href="#request-password">request password</a> (if
1.206 avankest 1285: non-null), taking into account the <a
1286: href="#request-entity-body">request entity body</a>, list of <a
1.205 avankest 1287: href="#author-request-headers">author request headers</a> and the
1288: rules listed at the end of this section.</p>
1.187 avankest 1289:
1.205 avankest 1290: <p>If there are cookies to be set, run these substeps:</p>
1.119 avankest 1291:
1292: <ol>
1293: <li>
1.205 avankest 1294: <p>Wait until ownership of the <a href="#storage-mutex">storage
1295: mutex</a> can be taken.
1.119 avankest 1296:
1297: <li>
1.205 avankest 1298: <p>Take ownership of the <a href="#storage-mutex">storage
1299: mutex</a>.
1.119 avankest 1300:
1301: <li>
1.205 avankest 1302: <p>Update the cookies. [<cite><a
1303: href="#ref-cookies=">COOKIES</a></cite>]
1.119 avankest 1304:
1305: <li>
1.205 avankest 1306: <p>Release the <a href="#storage-mutex">storage mutex</a> so that
1307: it is once again free.
1.119 avankest 1308: </ol>
1309:
1.205 avankest 1310: <p>While processing the request <a href="#queue-a-task" title="queue
1311: a task">queue tasks</a>, as data becomes available and when the user
1312: interferes with the request, to follow the <a
1313: href="#request-event-rules">request event rules</a> using the <a
1314: href="#xmlhttprequest-networking-task-source"><code>XMLHttpRequest</code>
1315: networking task source</a> as <a href="#task-source">task
1316: source</a>.</p>
1317:
1318: <p>The <a href="#task">task</a> that is <a href="#queue-a-task"
1319: title="queue a task">queued</a> by the <a
1320: href="#xmlhttprequest-networking-task-source"><code>XMLHttpRequest</code>
1321: networking task source</a> once the request is completed (i.e. no
1322: network errors or aborting of the algorithm occurred) is to <a
1323: href="#queue-a-task">queue a task</a> to run these substeps rather
1324: than following the <a href="#request-event-rules">request event
1325: rules</a>:</p>
1.60 avankest 1326:
1.119 avankest 1327: <ol>
1328: <li>
1.205 avankest 1329: <p>Switch the state to <a href="#done-state" title="DONE
1330: state">DONE</a>.
1.119 avankest 1331:
1332: <li>
1.205 avankest 1333: <p><a href="#dispatch-readystatechange-event">Dispatch a
1334: <code>readystatechange</code> event</a>.
1.124 avankest 1335: </ol>
1336:
1.205 avankest 1337: <p class=note>The <a href="#task">task</a> for these substeps is <a
1338: href="#queue-a-task" title="queue a task">queued</a> on the <a
1339: href="#xmlhttprequest-event-task-source"><code>XMLHttpRequest</code>
1340: event task source</a>.</p>
1341: </ol>
1342: </dl>
1343: </ol>
1.124 avankest 1344:
1.205 avankest 1345: <hr>
1346:
1347: <p>While executing the request certain events can influence the behavior of
1348: the <code><a href="#xmlhttprequest-object">XMLHttpRequest</a></code>
1349: object. These are called the <dfn id=request-event-rules>request event
1350: rules</dfn>:
1351:
1352: <dl class=switch>
1353: <dt>If the response is an HTTP redirect
1354:
1355: <dd>
1356: <p>If the redirect does not violate security (it is <a
1357: href="#same-origin">same origin</a> for instance), infinite loop
1358: precautions, and the scheme is supported, transparently follow the
1359: redirect while observing the <a href="#request-event-rules">request
1360: event rules</a>.</p>
1361:
1362: <p class=note>HTTP places requirements on the user agent regarding the
1.206 avankest 1363: preservation of the <a href="#request-method">request method</a> and <a
1364: href="#request-entity-body">request entity body</a> during redirects,
1365: and also requires users to be notified of certain kinds of automatic
1.205 avankest 1366: redirections.</p>
1367: <!-- XXX HTTP needs fixing here -->
1368: <p>Otherwise, run these steps:</p>
1369:
1370: <ol>
1371: <li>
1372: <p>Set the <a href="#response-entity-body">response entity body</a> to
1373: null.
1374:
1375: <li>
1376: <p>Set the the <a href="#error-flag">error flag</a> to true.
1.119 avankest 1377:
1.205 avankest 1378: <li>
1379: <p>Empty the list of <a href="#author-request-headers">author request
1380: headers</a>.
1381:
1382: <li>
1383: <p>Switch the state to <a href="#done-state" title="DONE
1384: state">DONE</a>.
1.119 avankest 1385:
1.205 avankest 1386: <li>
1387: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is false
1388: raise a <code><a href="#network-err">NETWORK_ERR</a></code> exception
1389: and terminate the overall set of steps.
1.60 avankest 1390:
1.205 avankest 1391: <li>
1392: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is true <a
1393: href="#queue-a-task">queue a task</a> to <a
1394: href="#dispatch-readystatechange-event">dispatch a
1395: <code>readystatechange</code> event</a>.
1.60 avankest 1396:
1397: <li>
1.205 avankest 1398: <p>Terminate the overall set of steps.
1.60 avankest 1399: </ol>
1.19 avankest 1400:
1.205 avankest 1401: <p class=note>It is likely that a future version of this specification
1402: will dispatch an <code>error</code> event here as well.</p>
1.185 avankest 1403:
1.205 avankest 1404: <dt>If the user cancels the download
1.6 avankest 1405:
1406: <dd>
1.205 avankest 1407: <p>Run these steps:</p>
1.6 avankest 1408:
1.62 avankest 1409: <ol>
1410: <li>
1.205 avankest 1411: <p>Set the <a href="#response-entity-body">response entity body</a> to
1412: null.
1.62 avankest 1413:
1414: <li>
1.205 avankest 1415: <p>Set the the <a href="#error-flag">error flag</a> to true.
1.62 avankest 1416:
1.80 avankest 1417: <li>
1.205 avankest 1418: <p>Empty the list of <a href="#author-request-headers">author request
1419: headers</a>.
1.84 avankest 1420:
1.205 avankest 1421: <li>
1422: <p>Switch the state to <a href="#done-state" title="DONE
1423: state">DONE</a>.
1424:
1425: <li>
1426: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is false
1427: raise a <code><a href="#abort-err">ABORT_ERR</a></code> exception and
1428: terminate the overall set of steps.
1.68 avankest 1429:
1.62 avankest 1430: <li>
1.205 avankest 1431: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is true <a
1432: href="#queue-a-task">queue a task</a> to <a
1433: href="#dispatch-readystatechange-event">dispatch a
1434: <code>readystatechange</code> event</a>.
1.62 avankest 1435:
1.205 avankest 1436: <li>
1437: <p>Terminate the overall set of steps.
1.62 avankest 1438: </ol>
1.26 avankest 1439:
1.205 avankest 1440: <p class=note>It is likely that a future version of this specification
1441: will dispatch an <code><a href="#abort">abort</a></code> event here as
1442: well.</p>
1443:
1444: <dt>In case of network errors
1.2 avankest 1445:
1446: <dd>
1.205 avankest 1447: <p>In case of DNS errors, timeout, TLS negotiation failure, or other type
1448: of network errors, do not request user interaction and run these steps:</p>
1449:
1450: <p class=note>This does not include HTTP responses that indicate some
1451: type of error, such as HTTP status code 410.</p>
1.60 avankest 1452:
1453: <ol>
1.77 avankest 1454: <li>
1.205 avankest 1455: <p>Set the <a href="#response-entity-body">response entity body</a> to
1456: null.
1457:
1458: <li>
1459: <p>Set the the <a href="#error-flag">error flag</a> to true.
1460:
1461: <li>
1462: <p>Empty the list of <a href="#author-request-headers">author request
1463: headers</a>.
1464:
1465: <li>
1466: <p>Switch the state to <a href="#done-state" title="DONE
1467: state">DONE</a>.
1468:
1469: <li>
1470: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is false
1471: raise a <code><a href="#network-err">NETWORK_ERR</a></code> exception
1472: and terminate the overall set of steps.
1473:
1474: <li>
1475: <p>If the <a href="#asynchronous-flag">asynchronous flag</a> is true <a
1476: href="#queue-a-task">queue a task</a> to <a
1477: href="#dispatch-readystatechange-event">dispatch a
1478: <code>readystatechange</code> event</a>.
1479:
1480: <li>
1481: <p>Terminate the overall set of steps.
1.60 avankest 1482: </ol>
1.6 avankest 1483:
1.205 avankest 1484: <p class=note>It is likely that a future version of this specification
1485: will dispatch an <code>error</code> event here as well.</p>
1.6 avankest 1486:
1.205 avankest 1487: <dt>Once all HTTP headers have been received and the <a
1488: href="#asynchronous-flag">asynchronous flag</a> is true
1.2 avankest 1489:
1.6 avankest 1490: <dd>
1.205 avankest 1491: <p>If all HTTP headers have been received, while receiving the message
1492: body (if any), run these steps:</p>
1.60 avankest 1493:
1494: <ol>
1.77 avankest 1495: <li>
1.205 avankest 1496: <p>Switch the state to <a href="#headers-received-state"
1497: title="HEADERS_RECEIVED state">HEADERS_RECEIVED</a>.
1.125 avankest 1498:
1499: <li>
1.205 avankest 1500: <p><a href="#queue-a-task">Queue a task</a> to <a
1501: href="#dispatch-readystatechange-event">dispatch a
1502: <code>readystatechange</code> event</a>.
1503: </ol>
1504:
1505: <dt>Once the first byte (or more) of the response entity body has been
1506: received and the <a href="#asynchronous-flag">asynchronous flag</a> is
1507: true
1.150 avankest 1508:
1.205 avankest 1509: <dt>If there is no response entity body and the <a
1510: href="#asynchronous-flag">asynchronous flag</a> is true
1511:
1512: <dd>
1513: <ol>
1.150 avankest 1514: <li>
1.205 avankest 1515: <p>Switch the state to <a href="#loading-state" title="LOADING
1516: state">LOADING</a>.
1.17 avankest 1517:
1.77 avankest 1518: <li>
1.205 avankest 1519: <p><a href="#queue-a-task">Queue a task</a> to <a
1520: href="#dispatch-readystatechange-event">dispatch a
1521: <code>readystatechange</code> event</a>.
1522: </ol>
1523: </dl>
1524:
1525: <hr>
1526:
1527: <p>If the user agent allows the user to configure a proxy it <em
1528: class=ct>should</em> modify the request appropriately; i.e. connect to the
1529: proxy host instead of the origin server, modify the
1530: <code>Request-Line</code> and send <code>Proxy-Authorization</code>
1531: headers as specified.
1532:
1533: <p>If the user agent supports HTTP Authentication it <em
1534: class=ct>should</em> consider requests originating from this object to be
1535: part of the protection space that includes the accessed URIs and send
1536: <code>Authorization</code> headers and handle <code>401
1537: Unauthorized</code> requests appropriately. If authentication fails, and
1538: <var>stored user</var> and <var>stored password</var> are not provided,
1539: user agents <em class=ct>should</em> prompt the user for credentials. If
1540: authentication fails, and <var>stored user</var> and <var>stored
1541: password</var> are provided, user agents <em class=ct>must not</em> prompt
1542: the user for credentials. [<cite><a
1543: href="#ref-rfc2617">RFC2617</a></cite>]
1544:
1545: <p class=note>Users are not prompted if credentials are provided through
1546: the <code><a href="#open">open()</a></code> API so that authors can
1547: implement their own user interface.
1548:
1549: <p>If the user agent supports HTTP State Management it <em
1550: class=ct>should</em> persist, discard and send cookies (as received in the
1551: <code>Set-Cookie</code> and <code>Set-Cookie2</code> response headers, and
1552: sent in the <code>Cookie</code> header) as applicable. [<cite><a
1553: href="#ref-cookies=">COOKIES</a></cite>]
1554:
1555: <p>If the user agent implements a HTTP cache it <em class=ct>should</em>
1556: respect <code>Cache-Control</code> request headers set by <code><a
1557: href="#setrequestheader">setRequestHeader()</a></code> (e.g.,
1558: <code>Cache-Control: no-cache</code> bypasses the cache). It <em
1559: class=ct>must not</em> send <code>Cache-Control</code> or
1560: <code>Pragma</code> request headers automatically unless the user
1561: explicitly requests such behavior (e.g. by (force-)reloading the page).
1562:
1563: <p>For <code>304 Not Modified</code> responses that are a result of a user
1564: agent generated conditional request the user agent <em class=ct>must</em>
1565: act as if the server gave a <code>200 OK</code> response with the
1566: appropriate content. The user agent <em class=ct>must</em> allow <code><a
1567: href="#setrequestheader">setRequestHeader()</a></code> to override
1568: automatic cache validation by setting request headers (e.g.,
1569: <code>If-None-Match</code>, <code>If-Modified-Since</code>), in which case
1570: <code>304 Not Modified</code> responses <em class=ct>must</em> be passed
1571: through. [<cite><a href="#ref-rfc2616">RFC2616</a></cite>]
1572:
1573: <p>If the user agent implements server-driven content-negotiation it <em
1574: class=ct>should</em> set <code>Accept-Encoding</code> and
1575: <code>Accept-Charset</code> headers as appropriate. Unless set through
1576: <code><a href="#setrequestheader">setRequestHeader()</a></code> user
1577: agents <em class=ct>should</em> set the <code>Accept</code> and
1578: <code>Accept-Language</code> headers as well. If <code>Accept</code> is
1579: set by the user agent it <em class=ct>must</em> have the value
1580: <code>*/*</code>. Responses <em class=ct>must</em> have the
1581: content-encodings automatically decoded. [<cite><a
1582: href="#ref-rfc2616">RFC2616</a></cite>]
1583:
1584: <p>Besides the <a href="#author-request-headers">author request headers</a>
1585: user agents <em class=ct>should not</em> include additional request
1586: headers other than those mentioned above or other than those authors are
1587: not allowed to set using <code><a
1588: href="#setrequestheader">setRequestHeader()</a></code>. This ensures that
1589: authors have a reasonably predictable API.
1590:
1591: <h4 id=the-abort-method><span class=secno>4.6.4 </span>The <code
1592: title="">abort()</code> method</h4>
1593:
1594: <p>When the <dfn id=abort><code>abort()</code></dfn> method is invoked, the
1595: user agent <em class=ct>must</em> run the following steps (unless
1596: otherwise noted):
1597:
1598: <ol>
1599: <li>
1600: <p><a href="#abort-send-algorithm" title="abort send()">Abort the
1601: <code>send()</code> algorithm</a>.
1.202 avankest 1602:
1.205 avankest 1603: <li>
1604: <p>The user agent <em class=ct>should</em> cancel any network activity
1605: for which the object is responsible.
1606:
1607: <li>
1608: <p>Set the <a href="#response-entity-body">response entity body</a> to
1609: null.
1610:
1611: <li>
1612: <p>Set the <a href="#error-flag">error flag</a> to true.
1613:
1614: <li>
1615: <p>Empty the list of <a href="#author-request-headers">author request
1616: headers</a>.
1617:
1618: <li>
1619: <p>If the state is <a href="#unsent-state" title="UNSENT
1620: state">UNSENT</a>, <a href="#opened-state" title="OPENED
1621: state">OPENED</a> with the <a href="#send-flag"><code>send()</code>
1622: flag</a> being false, or <a href="#done-state" title="DONE
1623: state">DONE</a> go to the next step.</p>
1624:
1625: <p>Otherwise run these substeps:</p>
1626:
1627: <ol>
1.202 avankest 1628: <li>
1.205 avankest 1629: <p>Switch the state to <a href="#done-state" title="DONE
1630: state">DONE</a>.
1.77 avankest 1631:
1632: <li>
1.205 avankest 1633: <p>Set the <a href="#send-flag"><code>send()</code> flag</a> to false.
1.77 avankest 1634:
1635: <li>
1.205 avankest 1636: <p><a href="#dispatch-readystatechange-event">Dispatch a
1637: <code>readystatechange</code> event</a>.
1.60 avankest 1638: </ol>
1.17 avankest 1639:
1.205 avankest 1640: <li>
1641: <p>Switch the state to <a href="#unsent-state" title="UNSENT
1642: state">UNSENT</a>.</p>
1643:
1644: <p class=note>No <code>readystatechange</code> event is dispatched.</p>
1645:
1646: <p class=note>It is likely that a future version of this specification
1647: will dispatch an <code title="">abort</code> event here.</p>
1648: </ol>
1649:
1650: <h3 id=response><span class=secno>4.7 </span>Response</h3>
1651:
1652: <h4 id=the-status-attribute><span class=secno>4.7.1 </span>The <code
1653: title="">status</code> attribute</h4>
1654:
1655: <p>The <dfn id=status><code>status</code></dfn> attribute <em
1656: class=ct>must</em> return the HTTP status code sent by the server
1657: (typically <code>200</code> for a successful request). Otherwise, if not
1658: available, the user agent <em class=ct>must</em> raise an
1659: <code>INVALID_STATE_ERR</code> exception.</p>
1660: <!-- XXX define in terms of states -->
1661:
1662: <h4 id=the-statustext-attribute><span class=secno>4.7.2 </span>The <code
1663: title="">statusText</code> attribute</h4>
1664:
1665: <p>The <dfn id=statustext><code>statusText</code></dfn> attribute <em
1666: class=ct>must</em> return the HTTP status text sent by the server (appears
1667: after the status code). Otherwise, if not available (request is not
1668: initiated for instance), the user agent <em class=ct>must</em> raise an
1669: <code>INVALID_STATE_ERR</code> exception.</p>
1670: <!-- XXX define in terms of states -->
1671:
1672: <h4 id=the-getresponseheader-method><span class=secno>4.7.3 </span>The
1673: <code title="">getResponseHeader()</code> method</h4>
1674:
1675: <p>When the <dfn id=getresponseheader
1676: title=getresponseheader><code>getResponseHeader(<var>header</var>)</code></dfn>
1677: is invoked, the user agent <em class=ct>must</em> run the following steps:
1678:
1679: <ol>
1680: <li>
1681: <p>If the state is <a href="#unsent-state" title="UNSENT
1682: state">UNSENT</a> or <a href="#opened-state" title="OPENED
1683: state">OPENED</a> raise an <code>INVALID_STATE_ERR</code> exception and
1684: terminate these steps.
1685:
1686: <li>
1687: <p>If <var>header</var> does not match the <code><a
1688: href="#field-name">field-name</a></code> production return
1689: <code>null</code> and terminate these steps.
1690:
1691: <li>
1692: <p>If the <a href="#error-flag">error flag</a> is true return
1693: <code>null</code> and terminate these steps.
1694:
1695: <li>
1696: <p>If <var>header</var> is an <a href="#ascii-case-insensitive">ASCII
1697: case-insensitive</a> match for <code>Set-Cookie</code> or
1698: <code>Set-Cookie2</code> return <code>null</code> and terminate these
1699: steps.
1700:
1701: <li>
1702: <p>If <var>header</var> is an <a href="#ascii-case-insensitive">ASCII
1703: case-insensitive</a> match for multiple HTTP response headers, return
1704: the values of these headers as a single concatenated string separated
1705: from each other by a U+002C COMMA U+0020 SPACE character pair and
1706: terminate these steps.
1707:
1708: <li>
1709: <p>If <var>header</var> is an <a href="#ascii-case-insensitive">ASCII
1710: case-insensitive</a> match for a single HTTP response header, return the
1711: value of that header and terminate these steps.
1712:
1713: <li>
1714: <p>Return <code>null</code>.
1715: </ol>
1716:
1717: <div class=example>
1718: <pre><code>// The following script:
1.1 avankest 1719: var client = new XMLHttpRequest();
1.18 avankest 1720: client.open("GET", "test.txt", true);
1.6 avankest 1721: client.send();
1.16 avankest 1722: client.onreadystatechange = function() {
1.180 avankest 1723: if(this.readyState == 2) {
1.18 avankest 1724: print(client.getResponseHeader("Content-Type"));
1.16 avankest 1725: }
1726: }
1.1 avankest 1727:
1.6 avankest 1728: // ...should output something similar to the following text:
1.205 avankest 1729: Content-Type: text/plain; charset=utf-8</code></pre>
1730: </div>
1731:
1732: <h4 id=the-getallresponseheaders-method><span class=secno>4.7.4 </span>The
1733: <code title="">getAllResponseHeaders()</code> method</h4>
1.2 avankest 1734:
1.205 avankest 1735: <p>When the <dfn
1736: id=getallresponseheaders><code>getAllResponseHeaders()</code></dfn> method
1737: is invoked, the user agent <em class=ct>must</em> run the following steps:
1.6 avankest 1738:
1.205 avankest 1739: <ol>
1740: <li>
1741: <p>If the state is <a href="#unsent-state" title="UNSENT
1742: state">UNSENT</a> or <a href="#opened-state" title="OPENED
1743: state">OPENED</a> raise an <code>INVALID_STATE_ERR</code> exception and
1744: terminate these steps.
1745:
1746: <li>
1747: <p>If the <a href="#error-flag">error flag</a> is true return the empty
1748: string and terminate these steps.
1749:
1750: <li>
1751: <p>Return all the HTTP headers, excluding headers that are an <a
1752: href="#ascii-case-insensitive">ASCII case-insensitive</a> match for
1753: <code>Set-Cookie</code> or <code>Set-Cookie2</code>, as a single string,
1754: with each header line separated by a U+000D CR U+000A LF pair excluding
1755: the status line, and with each header name and header value separated by
1756: a U+003A COLON U+0020 SPACE pair.
1757: </ol>
1758:
1759: <div class=example>
1760: <pre><code>// The following script:
1761: var client = new XMLHttpRequest();
1762: client.open("GET", "test.txt", true);
1763: client.send();
1764: client.onreadystatechange = function() {
1765: if(this.readyState == 2) {
1766: print(this.getAllResponseHeaders());
1767: }
1768: }
1769:
1770: // ...should output something similar to the following text:
1771: Date: Sun, 24 Oct 2004 04:58:38 GMT
1772: Server: Apache/1.3.31 (Unix)
1773: Keep-Alive: timeout=15, max=99
1774: Connection: Keep-Alive
1775: Transfer-Encoding: chunked
1776: Content-Type: text/plain; charset=utf-8</code></pre>
1777: </div>
1778:
1779: <h4 id=response-entity-body0><span class=secno>4.7.5 </span>Response Entity
1780: Body</h4>
1781:
1782: <p>The <dfn id=response-entity-body>response entity body</dfn> is the
1783: fragment of the <a href="#entity-body">entity body</a> received so far (<a
1784: href="#loading-state" title="LOADING state">LOADING</a> state) or the
1785: complete <a href="#entity-body">entity body</a> (<a href="#done-state"
1786: title="DONE state">DONE</a> state). If there is no <a
1787: href="#entity-body">entity body</a> the <a
1788: href="#response-entity-body">response entity body</a> is null.
1789:
1790: <hr>
1791:
1792: <p>The <dfn id=text-response-entity-body>text response entity body</dfn> is
1793: a <code>DOMString</code> representing the <a
1794: href="#response-entity-body">response entity body</a>. The <a
1795: href="#text-response-entity-body">text response entity body</a> is the
1796: return value of the following algorithm:
1797:
1798: <ol>
1799: <li>
1800: <p>If the <a href="#response-entity-body">response entity body</a> is
1801: null return the empty string and terminate these steps.</p>
1802:
1803: <li>
1804: <p>Let <var>charset</var> be null.
1805:
1806: <li>
1807: <p>If there is no <code>Content-Type</code> header or there is a
1808: <code>Content-Type</code> header which contains a MIME type that is
1809: <code>text/xml</code>, <code>application/xml</code> or ends in <code
1810: title="">+xml</code> (ignoring any parameters) use the rules set forth
1811: in the XML specifications to determine the character encoding. Let
1812: <var>charset</var> be the determined character encoding. [<cite><a
1813: href="#ref-xml">XML</a></cite>]
1814:
1815: <li>
1816: <p>If the <code>Content-Type</code> header contains a
1817: <code>text/html</code> MIME type follow the rules set forth in the
1818: HTML 5 specification to determine the character encoding. Let
1819: <var>charset</var> be the determined character encoding. [<cite><a
1820: href="#ref-html5">HTML5</a></cite>]
1821:
1822: <li>
1823: <p>If the MIME type specified by the <code>Content-Type</code> header
1824: contains a <code>charset</code> parameter and <var>charset</var> is null
1825: let <var>charset</var> be the value of that parameter.</p>
1826:
1827: <p class=note>The algorithms described by the XML and HTML specifications
1828: already take <code>Content-Type</code> into account.</p>
1829:
1830: <li> <!-- This stuff is copied from HTML5. Thanks Hixie! -->
1831: <p>If <var>charset</var> is null then, for each of the rows in the
1832: following table, starting with the first one and going down, if the
1833: first bytes of <var>bytes</var> match the bytes given in the first
1834: column, then let <var>charset</var> be the encoding given in the cell in
1835: the second column of that row. If there is no match <var>charset</var>
1836: remains null.</p>
1837:
1838: <table>
1839: <thead>
1840: <tr>
1841: <th>Bytes in Hexadecimal
1842:
1843: <th>Description
1844:
1845: <tbody><!-- UTF-32 is dead
1846: <tr>
1847: <td>00 00 FE FF
1848: <td>UTF-32BE BOM
1849: <tr>
1850: <td>FF FE 00 00
1851: <td>UTF-32LE BOM-->
1852:
1853: <tr>
1854: <td>FE FF
1855:
1856: <td>UTF-16BE BOM
1857:
1858: <tr>
1859: <td>FF FE
1860:
1861: <td>UTF-16LE BOM
1862:
1863: <tr>
1864: <td>EF BB BF
1865:
1866: <td>UTF-8 BOM<!-- nobody uses this
1867: <tr>
1868: <td>DD 73 66 73
1869: <td>UTF-EBCDIC
1870: -->
1871:
1872: </table>
1873:
1874: <li>
1875: <p>If <var>charset</var> is null let <var>charset</var> be UTF-8.
1876:
1877: <li>
1878: <p>Return the result of decoding the response entity body using
1879: <var>charset</var>. Replace bytes or sequences of bytes that are not
1880: valid according to the <var>charset</var> with a single U+FFFD
1881: REPLACEMENT CHARACTER character.
1882: </ol>
1883:
1884: <p class=note>Authors are strongly encouraged to encode their resources
1885: using UTF-8.
1886:
1887: <hr>
1888:
1889: <p>The <dfn id=xml-response-entity-body>XML response entity body</dfn> is
1890: either a <code>Document</code> representing the <a
1891: href="#response-entity-body">response entity body</a> or
1892: <code>null</code>. The <a href="#xml-response-entity-body">XML response
1893: entity body</a> is the return value of the following algorithm:
1.89 avankest 1894:
1.205 avankest 1895: <ol>
1896: <li>
1897: <p>If the <a href="#response-entity-body">response entity body</a> is
1898: null terminate these steps and return <code>null</code>.
1.6 avankest 1899:
1.205 avankest 1900: <li>
1901: <p>If a <code>Content-Type</code> is present and it does not contain a
1902: MIME type (ignoring any parameters) that is <code>text/xml</code>,
1903: <code>application/xml</code> or ends in <code title="">+xml</code>
1904: terminate these steps and return <code>null</code>. (Do not terminate
1905: these steps if there is no <code>Content-Type</code> header at all.)
1.12 avankest 1906:
1.205 avankest 1907: <li>
1908: <p>Parse the <a href="#response-entity-body">response entity body</a>
1909: into a document tree following the rules from the XML specifications.
1910: Let the result be <var>parsed document</var>. If this fails (unsupported
1911: character encoding, namespace well-formedness error, et cetera)
1912: terminate these steps return <code>null</code>. [<cite><a
1913: href="#ref-xml">XML</a></cite>]</p>
1.6 avankest 1914:
1.205 avankest 1915: <p class=note>Scripts in the resulting document tree will not be
1916: executed, resources referenced will not be loaded and no associated XSLT
1917: will be applied.</p>
1.76 avankest 1918:
1.205 avankest 1919: <li>
1920: <p>Return an object implementing the <code>Document</code> interface
1921: representing the <var>parsed document</var>.
1922: </ol>
1.76 avankest 1923:
1.205 avankest 1924: <h4 id=the-responsetext-attribute><span class=secno>4.7.6 </span>The <code
1925: title="">responseText</code> attribute</h4>
1.12 avankest 1926:
1.205 avankest 1927: <p>The <dfn id=responsetext><code>responseText</code></dfn> attribute <em
1928: class=ct>must</em> return the result of running the following steps:
1.6 avankest 1929:
1.205 avankest 1930: <ol>
1931: <li>
1932: <p>If the state is not <a href="#loading-state" title="LOADING
1933: state">LOADING</a> or <a href="#done-state" title="DONE state">DONE</a>
1934: return the empty string and terminate these steps.
1.12 avankest 1935:
1.205 avankest 1936: <li>
1937: <p>Return the <a href="#text-response-entity-body">text response entity
1938: body</a>.
1939: </ol>
1.2 avankest 1940:
1.205 avankest 1941: <h4 id=the-responsexml-attribute><span class=secno>4.7.7 </span>The <code
1942: title="">responseXML</code> attribute</h4>
1.2 avankest 1943:
1.205 avankest 1944: <p>The <dfn id=responsexml><code>responseXML</code></dfn> attribute <em
1945: class=ct>must</em> return the result of running the following steps:
1.2 avankest 1946:
1.205 avankest 1947: <ol>
1948: <li>
1949: <p>If the state is not <a href="#done-state" title="DONE state">DONE</a>
1950: return <code>null</code> and terminate these steps.
1.2 avankest 1951:
1.205 avankest 1952: <li>
1953: <p>Return the <a href="#xml-response-entity-body">XML response entity
1954: body</a>.
1955: </ol>
1.2 avankest 1956:
1.205 avankest 1957: <h3 id=exceptions><span class=secno>4.8 </span>Exceptions</h3>
1958: <!-- XXX HTML5 assumes Web DOM Core will define these -->
1.33 avankest 1959:
1.139 avankest 1960: <p>Several algorithms in this specification may result in an exception
1961: being thrown. These exceptions are all part of the group
1.186 avankest 1962: <code>ExceptionCode</code> and use the <code>DOMException</code> object,
1.139 avankest 1963: which is defined in DOM Level 3 Core. In addition this specification
1964: extends the <code>ExceptionCode</code> group with several new constants as
1.146 avankest 1965: indicated below. [<cite><a href="#ref-dom3core">DOM3Core</a></cite>]
1.139 avankest 1966:
1.194 avankest 1967: <p class=note>Thus, exceptions used by this specification and not defined
1968: in this section are defined by DOM Level 3 Core.
1969:
1.34 avankest 1970: <pre
1.139 avankest 1971: class=idl>const unsigned short <a href="#security-err">SECURITY_ERR</a> = 18;
1.200 avankest 1972: const unsigned short <a href="#network-err">NETWORK_ERR</a> = 19;
1973: const unsigned short <a href="#abort-err">ABORT_ERR</a> = 20;</pre>
1.33 avankest 1974:
1.139 avankest 1975: <p>The <dfn id=security-err><code>SECURITY_ERR</code></dfn> exception is
1976: raised if an attempt is made to perform an operation or access some data
1977: in a way that would be a security risk or a violation of the user agent's
1978: security policy.</p>
1979: <!-- http://lists.w3.org/Archives/Public/public-webapi/2006May/0027.html -->
1980:
1.35 avankest 1981: <p>The <dfn id=network-err><code>NETWORK_ERR</code></dfn> exception is
1.139 avankest 1982: raised when a network error occurs in synchronous requests.
1.122 avankest 1983:
1.139 avankest 1984: <p>The <dfn id=abort-err><code>ABORT_ERR</code></dfn> exception is raised
1.122 avankest 1985: when the user aborts a request in synchronous requests.
1986:
1.200 avankest 1987: <p class=note>These exceptions might be folded into an update of DOM Level
1988: 3 Core in due course, as they are appropriate for other API specifications
1989: as well.
1990:
1.31 avankest 1991: <h2 class=no-num id=notcovered>Not in this Specification</h2>
1992:
1.144 avankest 1993: <p><em>This section is non-normative.</em>
1.31 avankest 1994:
1.73 avankest 1995: <p>This specification does not include the following features which are
1996: being considered for a future version of this specification:
1.31 avankest 1997:
1998: <ul>
1999: <li><code>load</code> event and <code>onload</code> attribute;
2000:
2001: <li><code>error</code> event and <code>onerror</code> attribute;
2002:
2003: <li><code>progress</code> event and <code>onprogress</code> attribute;
2004:
2005: <li><code title="">abort</code> event and <code>onabort</code> attribute;
2006:
2007: <li>Timers have been suggested, perhaps an <code>ontimeout</code>
2008: attribute;
2009:
2010: <li>Property to disable following redirects;
2011:
1.32 avankest 2012: <li><code title="">responseXML</code> for <code>text/html</code>
2013: documents;
1.31 avankest 2014:
1.205 avankest 2015: <li>Cross-origin <code title="">XMLHttpRequest</code>;
1.42 avankest 2016:
1.88 avankest 2017: <li><code>responseBody</code> to deal with byte streams;
1.42 avankest 2018:
1.115 avankest 2019: <li><code>overrideMimeType</code> to fix up MIME types;
2020:
1.88 avankest 2021: <li><code>getRequestHeader()</code> and
2022: <code>removeRequestHeader()</code>.
1.31 avankest 2023: </ul>
2024:
1.25 avankest 2025: <h2 class=no-num id=bibref>References</h2>
1.2 avankest 2026:
1.178 avankest 2027: <p>Unless marked "Non-normative" these references are normative.
2028:
1.7 avankest 2029: <dl>
1.205 avankest 2030: <dt>[<dfn id="ref-cookies=">COOKIES</dfn>]
2031:
2032: <dd><cite><a href="http://ietf.org/rfc/rfc2109">HTTP State Management
2033: Mechanism</a></cite>, D. Kristol, L. Montulli, editors. IETF, February
2034: 1997.
2035:
2036: <dd><cite><a href="http://ietf.org/rfc/rfc2965">HTTP State Management
2037: Mechanism</a></cite>, D. Kristol, L. Montulli, editors. IETF, October
2038: 2000.</dd>
2039: <!-- XXX These specs do not match reality. Also, the latter obsoletes the
2040: former -->
2041:
1.156 avankest 2042: <dt>[<dfn id=ref-dom2events>DOM2Events</dfn>]
2043:
2044: <dd><cite><a href="http://www.w3.org/TR/DOM-Level-2-Events/">Document
1.161 avankest 2045: Object Model (DOM) Level 2 Events Specification</a></cite>, T. Pixley,
2046: editor. W3C, November 2000.
1.156 avankest 2047:
1.146 avankest 2048: <dt>[<dfn id=ref-dom3core>DOM3Core</dfn>]
1.2 avankest 2049:
1.15 avankest 2050: <dd><cite><a href="http://www.w3.org/TR/DOM-Level-3-Core">Document Object
2051: Model (DOM) Level 3 Core Specification</a></cite>, A. Le Hors, P. Le
1.140 avankest 2052: Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne,
2053: editors. W3C, April 2004.
1.2 avankest 2054:
1.39 avankest 2055: <dt>[<dfn id=ref-ecmascript>ECMAScript</dfn>]
1.18 avankest 2056:
2057: <dd><cite><a
2058: href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript
2059: Language Specification</a></cite>, Third Edition. ECMA, December 1999.
2060:
1.146 avankest 2061: <dt>[<dfn id=ref-html5>HTML5</dfn>]
1.143 avankest 2062:
2063: <dd><cite><a
1.172 avankest 2064: href="http://www.w3.org/html/wg/html5/">HTML 5</a></cite> (work in
2065: progress), I. Hickson, D. Hyatt, editors. W3C, 2008.
2066:
2067: <dd><cite><a
1.143 avankest 2068: href="http://www.whatwg.org/specs/web-apps/current-work/">HTML 5</a></cite>
1.172 avankest 2069: (work in progress), I. Hickson, editor. WHATWG, 2008.
1.18 avankest 2070:
1.199 avankest 2071: <dt>[<dfn id=ref-httpverbsec>HTTPVERBSEC</dfn>]
2072:
2073: <dd>(Non-normative) <cite><a
2074: href="http://www.kb.cert.org/vuls/id/867593">Multiple vendors' web
2075: servers enable HTTP TRACE method by default</a></cite>, US-CERT.
2076:
2077: <dd>(Non-normative) <cite><a
2078: href="http://www.kb.cert.org/vuls/id/288308">Microsoft Internet
2079: Information Server (IIS) vulnerable to cross-site scripting via HTTP
2080: TRACK method</a></cite>, US-CERT.
2081:
2082: <dd>(Non-normative) <cite><a
2083: href="http://www.kb.cert.org/vuls/id/150227">HTTP proxy default
2084: configurations allow arbitrary TCP connections</a></cite>, US-CERT.
2085:
1.146 avankest 2086: <dt>[<dfn id=ref-rfc2119>RFC2119</dfn>]
1.15 avankest 2087:
1.118 avankest 2088: <dd><cite><a href="http://ietf.org/rfc/rfc2119">Key words for use in RFCs
2089: to Indicate Requirement Levels</a></cite>, S. Bradner. IETF, March 1997.
1.15 avankest 2090:
1.146 avankest 2091: <dt>[<dfn id=ref-rfc2616>RFC2616</dfn>]
1.15 avankest 2092:
2093: <dd><cite><a href="http://ietf.org/rfc/rfc2616">Hypertext Transfer
2094: Protocol -- HTTP/1.1</a></cite>, R. Fielding, J. Gettys, J. Mogul, H.
1.93 avankest 2095: Frystyk, L. Masinter, P. Leach, T. Berners-Lee, editors. IETF, June 1999.
1.15 avankest 2096:
1.39 avankest 2097: <dt>[<dfn id=ref-rfc2617>RFC2617</dfn>]
1.15 avankest 2098:
2099: <dd><cite><a href="http://ietf.org/rfc/rfc2617">HTTP Authentication: Basic
1.93 avankest 2100: and Digest Access Authentication</a></cite>, P. Hallam-Baker, J.
2101: Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart, editors. IETF,
2102: June 1999.
1.2 avankest 2103:
1.39 avankest 2104: <dt>[<dfn id=ref-rfc3986>RFC3986</dfn>]
1.2 avankest 2105:
1.15 avankest 2106: <dd><cite><a href="http://ietf.org/rfc/rfc3986">Uniform Resource
2107: Identifier (URI): Generic Syntax</a></cite>, T. Berners-Lee, R. Fielding,
1.188 avankest 2108: L. Masinter, editors. IETF, January 2005.
2109:
1.205 avankest 2110: <dt>[<dfn id=ref-webidl>WebIDL</dfn>]
1.182 avankest 2111:
1.201 avankest 2112: <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web
1.205 avankest 2113: IDL</a></cite> (work in progress), C. McCormack, editor. W3C, 2009.
1.182 avankest 2114:
1.43 avankest 2115: <dt>[<dfn id=ref-xml>XML</dfn>]
2116:
2117: <dd><cite><a href="http://www.w3.org/TR/xml/">Extensible Markup Language
1.205 avankest 2118: (XML) 1.0 (Fifth Edition)</a></cite>, T. Bray, J. Paoli, C.
2119: Sperberg-McQueen, E. Maler, F. Yergeau, editors. W3C, November 2008.
1.43 avankest 2120:
2121: <dd><cite><a href="http://www.w3.org/TR/xml-names/">Namespaces in XML
1.118 avankest 2122: (Second Edition)</a></cite>, T. Bray, D. Hollander, A. Layman, R. Tobin,
2123: editors. W3C, August 2006.
1.2 avankest 2124: </dl>
2125:
1.131 avankest 2126: <h2 class=no-num id=acknowledgments>Acknowledgments</h2>
1.2 avankest 2127:
1.164 avankest 2128: <p>The editor would like to thank Addison Phillips, Ahmed Kamel, Alex
2129: Hopmann, Alex Vincent, Alexey Proskuryakov, Asbjørn Ulsberg, Boris
2130: Zbarsky, Björn Höhrmann, Cameron McCormack, Christophe Jolif,
2131: Charles McCathieNevile, Dan Winship, David Håsäther, Dean
2132: Jackson, Denis Sureau, Doug Schepers, Douglas Livingstone, Elliotte
1.197 avankest 2133: Harold, Eric Lawrence, Erik Dahlström, Geoffrey Sneddon, Gideon Cohn,
2134: Gorm Haug Eriksen, Hallvord R. M. Steen, Håkon Wium Lie, Ian Davis,
2135: Ian Hickson, Ivan Herman, Jeff Walden, Jens Lindström, Jim Deegan,
2136: Jim Ley, Joe Farro, Jonas Sicking, Julian Reschke, Karl Dubost, Lachlan
2137: Hunt, Maciej Stachowiak, Magnus Kristiansen, Marc Hadley, Marcos Caceres,
1.205 avankest 2138: Mark Baker, Mark Birbeck, Mark Nottingham, Mohamed Zergaoui, Pawel
2139: Glowacki, Robin Berjon, Ruud Steltenpool, Simon Pieters, Stewart Brodie,
2140: Sunava Dutta, Thomas Roessler, Tom Magliery, and Zhenbin Xu for their
2141: contributions to this specification.
1.2 avankest 2142:
2143: <p>Special thanks to the Microsoft employees who first implemented the
1.144 avankest 2144: <code title="">XMLHttpRequest</code> interface, which was first widely
2145: deployed by the Windows Internet Explorer browser.
1.2 avankest 2146:
1.56 avankest 2147: <p>Special thanks also to the WHATWG for drafting an initial version of
1.131 avankest 2148: this specification in their Web Applications 1.0 document (now renamed to
1.146 avankest 2149: HTML 5). [<cite><a href="#ref-html5">HTML5</a></cite>]
1.2 avankest 2150:
2151: <p>Thanks also to all those who have helped to improve this specification
2152: by sending suggestions and corrections. (Please, keep bugging us with your
2153: 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