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