/
Overview.html
2437 lines (1912 loc) · 135 KB
/
Overview.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html><html lang="en-US"><meta charset="utf-8">
<title>XMLHttpRequest Standard</title>
<link href="http://www.whatwg.org/style/specification" rel="stylesheet">
<link href="http://resources.whatwg.org/logo-xhr.svg" rel="icon">
<div class="head">
<p><a class="logo" href="//www.whatwg.org/"><img alt="WHATWG" height="100" src="//resources.whatwg.org/logo-xhr.svg" width="100"></a>
<h1 class="head" id="xmlhttprequest-ls">XMLHttpRequest</h1>
<h2 class="no-num no-toc" id="living-standard-—-last-updated-11-november-2013">Living Standard — Last Updated 11 November 2013</h2>
<dl>
<dt>This Version:
<dd><a href="http://xhr.spec.whatwg.org/">http://xhr.spec.whatwg.org/</a>
<dt>Participate:
<dd>Send feedback to
<a href="mailto:public-webapps@w3.org?subject==%5Bxhr%5D%20">public-webapps@w3.org</a>
(<a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>) or
<a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=WebAppsWG&component=XHR">file a bug</a>
(<a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=WebAppsWG&component=XHR&resolution=---">open bugs</a>)
<dd><a href="http://wiki.whatwg.org/wiki/IRC">IRC: #whatwg on Freenode</a>
<dt>Version History:
<dd><a href="https://github.com/whatwg/xhr/commits">https://github.com/whatwg/xhr/commits</a>
<dt>Editor:
<dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a>
(<a href="http://www.mozilla.org/">Mozilla</a>)
<<a href="mailto:annevk@annevk.nl">annevk@annevk.nl</a>>
</dl>
<script async="" src="//resources.whatwg.org/file-bug.js"></script>
<p class="copyright"><a href="http://creativecommons.org/publicdomain/zero/1.0/" rel="license"><img alt="CC0" src="http://i.creativecommons.org/p/zero/1.0/80x15.png"></a>
To the extent possible under law, the editor has waived all copyright and
related or neighboring rights to this work. In addition, as of
11 November 2013, the editor has made this specification available
under the
<a href="http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0" rel="license">Open Web Foundation Agreement Version 1.0</a>,
which is available at
http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.
</div>
<h2 class="no-num no-toc" id="specabstract">Abstract</h2>
<p>XMLHttpRequest defines an API that provides scripted client functionality for
transferring data between a client and a server.
<h2 class="no-num no-toc" id="toc">Table of Contents</h2>
<!--begin-toc-->
<ol class="toc">
<li><a href="#introduction"><span class="secno">1 </span>Introduction</a>
<ol class="toc">
<li><a href="#specification-history"><span class="secno">1.1 </span>Specification history</a></ol></li>
<li><a href="#conformance"><span class="secno">2 </span>Conformance</a>
<ol class="toc">
<li><a href="#extensibility"><span class="secno">2.1 </span>Extensibility</a></ol></li>
<li><a href="#terminology"><span class="secno">3 </span>Terminology</a></li>
<li><a href="#interface-xmlhttprequest"><span class="secno">4 </span>Interface <code title="">XMLHttpRequest</code></a>
<ol class="toc">
<li><a href="#constructors"><span class="secno">4.1 </span>Constructors</a></li>
<li><a href="#garbage-collection"><span class="secno">4.2 </span>Garbage collection</a></li>
<li><a href="#event-handlers"><span class="secno">4.3 </span>Event handlers</a></li>
<li><a href="#states"><span class="secno">4.4 </span>States</a></li>
<li><a href="#request"><span class="secno">4.5 </span>Request</a>
<ol class="toc">
<li><a href="#the-open()-method"><span class="secno">4.5.1 </span>The <code title="">open()</code> method</a></li>
<li><a href="#the-setrequestheader()-method"><span class="secno">4.5.2 </span>The <code title="">setRequestHeader()</code> method</a></li>
<li><a href="#the-timeout-attribute"><span class="secno">4.5.3 </span>The <code title="">timeout</code> attribute</a></li>
<li><a href="#the-withcredentials-attribute"><span class="secno">4.5.4 </span>The <code title="">withCredentials</code> attribute</a></li>
<li><a href="#the-upload-attribute"><span class="secno">4.5.5 </span>The <code title="">upload</code> attribute</a></li>
<li><a href="#the-send()-method"><span class="secno">4.5.6 </span>The <code title="">send()</code> method</a></li>
<li><a href="#the-abort()-method"><span class="secno">4.5.7 </span>The <code title="">abort()</code> method</a></ol></li>
<li><a href="#response"><span class="secno">4.6 </span>Response</a>
<ol class="toc">
<li><a href="#the-status-attribute"><span class="secno">4.6.1 </span>The <code title="">status</code> attribute</a></li>
<li><a href="#the-statustext-attribute"><span class="secno">4.6.2 </span>The <code title="">statusText</code> attribute</a></li>
<li><a href="#the-getresponseheader()-method"><span class="secno">4.6.3 </span>The <code title="">getResponseHeader()</code> method</a></li>
<li><a href="#the-getallresponseheaders()-method"><span class="secno">4.6.4 </span>The <code title="">getAllResponseHeaders()</code> method</a></li>
<li><a href="#response-entity-body-0"><span class="secno">4.6.5 </span>Response entity body</a></li>
<li><a href="#the-overridemimetype()-method"><span class="secno">4.6.6 </span>The <code title="">overrideMimeType()</code> method</a></li>
<li><a href="#the-responsetype-attribute"><span class="secno">4.6.7 </span>The <code title="">responseType</code> attribute</a></li>
<li><a href="#the-response-attribute"><span class="secno">4.6.8 </span>The <code title="">response</code> attribute</a></li>
<li><a href="#the-responsetext-attribute"><span class="secno">4.6.9 </span>The <code title="">responseText</code> attribute</a></li>
<li><a href="#the-responsexml-attribute"><span class="secno">4.6.10 </span>The <code title="">responseXML</code> attribute</a></ol></li>
<li><a href="#events"><span class="secno">4.7 </span>Events summary</a></ol></li>
<li><a href="#interface-formdata"><span class="secno">5 </span>Interface <code title="">FormData</code></a></li>
<li><a href="#interface-progressevent"><span class="secno">6 </span>Interface <code title="">ProgressEvent</code></a>
<ol class="toc">
<li><a href="#firing-events-using-the-progressevent-interface-for-http"><span class="secno">6.1 </span>Firing events using the <code title="">ProgressEvent</code> interface for HTTP</a></li>
<li><a href="#firing-events-using-the-progressevent-interface-for-other-contexts"><span class="secno">6.2 </span>Firing events using the <code title="">ProgressEvent</code> interface for other contexts</a></li>
<li><a href="#suggested-names-for-events-using-the-progressevent-interface"><span class="secno">6.3 </span>Suggested names for events using the <code title="">ProgressEvent</code> interface</a></li>
<li><a href="#security-considerations"><span class="secno">6.4 </span>Security Considerations</a></li>
<li><a href="#example"><span class="secno">6.5 </span>Example</a></ol></li>
<li><a class="no-num" href="#references">References</a></li>
<li><a class="no-num" href="#acknowledgments">Acknowledgments</a></ol>
<!--end-toc-->
<h2 id="introduction"><span class="secno">1 </span>Introduction</h2>
<p><em>This section is non-normative.</em>
<p>The <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object is an API for
<a class="external" href="http://fetch.spec.whatwg.org/#concept-fetch" title="concept-fetch">fetching</a> resources.
<p>The name <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> is historical and has no baring on its
functionality.
<div class="example">
<p>Some simple code to do something with data from an XML document
fetched over the network:
<pre><code>function processData(data) {
// taking care of data
}
function handler() {
if(this.readyState == this.DONE) {
if(this.status == 200 &&
this.responseXML != null &&
this.responseXML.getElementById('test').textContent) {
// success!
processData(this.responseXML.getElementById('test').textContent);
return;
}
// something went wrong
processData(null);
}
}
var client = new XMLHttpRequest();
client.onreadystatechange = handler;
client.open("GET", "unicorn.xml");
client.send();</code></pre>
<p>If you just want to log a message to the server:
<pre><code>function log(message) {
var client = new XMLHttpRequest();
client.open("POST", "/log");
client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
client.send(message);
}</code></pre>
<p>Or if you want to check the status of a document on the server:
<pre><code>function fetchStatus(address) {
var client = new XMLHttpRequest();
client.onreadystatechange = function() {
// in case of network errors this might not give reliable results
if(this.readyState == this.DONE)
returnStatus(this.status);
}
client.open("HEAD", address);
client.send();
}</code></pre>
</div>
<h3 id="specification-history"><span class="secno">1.1 </span>Specification history</h3>
<p>The <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object was initially defined as part of
the WHATWG's HTML effort. (Long after Microsoft shipped an implementation.)
It moved to the W3C in 2006. Extensions (e.g. progress events and
cross-origin requests) to <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> were developed in a
separate draft (XMLHttpRequest Level 2) until end of 2011, at which point
the two drafts were merged and <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> became a single
entity again from a standards perspective. End of 2012 it moved back to the
WHATWG.
<p>Historical discussion can be found in the following mailing list
archives:
<ul>
<li><a href="http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/">whatwg@whatwg.org</a>
<li><a href="http://lists.w3.org/Archives/Public/public-webapi/">public-webapi@w3.org</a>
<li><a href="http://lists.w3.org/Archives/Public/public-appformats/">public-appformats@w3.org</a>
<li><a href="http://lists.w3.org/Archives/Public/public-webapps/">public-webapps@w3.org</a>
</ul>
<h2 id="conformance"><span class="secno">2 </span>Conformance</h2>
<p>All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.
<p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
NOT",--> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in the normative parts of this specification are to be
interpreted as described in RFC2119. For readability, these words do
not appear in all uppercase letters in this specification.
<a href="#refsRFC2119">[RFC2119]</a>
<h3 id="extensibility"><span class="secno">2.1 </span>Extensibility</h3>
<p>User agents, Working Groups, and other interested parties are
<em>strongly encouraged</em> to discuss new features with the WHATWG
community.
<h2 id="terminology"><span class="secno">3 </span>Terminology</h2>
<p>This specification uses terminology, cross-linked throughout, from DOM,
DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, HTTP, Typed Array, URL,
Web IDL, and XML.
<a href="#refsDOM">[DOM]</a>
<a href="#refsDOMPS">[DOMPS]</a>
<a href="#refsENCODING">[ENCODING]</a>
<a href="#refsFETCH">[FETCH]</a>
<a href="#refsFILEAPI">[FILEAPI]</a>
<a href="#refsHTML">[HTML]</a>
<a href="#refsHTTP">[HTTP]</a>
<a href="#refsTYPEDARRAY">[TYPEDARRAY]</a>
<a href="#refsURL">[URL]</a>
<a href="#refsWEBIDL">[WEBIDL]</a>
<a href="#refsXML">[XML]</a> <a href="#refsXMLNS">[XMLNS]</a>
<p>It uses the typographic conventions from HTML. <a href="#refsHTTP">[HTTP]</a>
<p>The term <dfn id="user-credentials">user credentials</dfn> for the purposes of this
specification means cookies, HTTP authentication, and client-side SSL
certificates. Specifically it does not refer to proxy authentication or the
<code title="http-origin">Origin</code> header.
<a href="#refsCOOKIES">[COOKIES]</a> <!-- XXX ref? -->
<h2 id="interface-xmlhttprequest"><span class="secno">4 </span>Interface <code title="">XMLHttpRequest</code></h2>
<pre class="idl">[NoInterfaceObject]
interface <dfn id="xmlhttprequesteventtarget">XMLHttpRequestEventTarget</dfn> : <a class="external" href="http://dom.spec.whatwg.org/#eventtarget">EventTarget</a> {
// <a href="#event-handlers">event handlers</a>
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onloadstart" title="handler-xhr-onloadstart">onloadstart</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onprogress" title="handler-xhr-onprogress">onprogress</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onabort" title="handler-xhr-onabort">onabort</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onerror" title="handler-xhr-onerror">onerror</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onload" title="handler-xhr-onload">onload</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-ontimeout" title="handler-xhr-ontimeout">ontimeout</a>;
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onloadend" title="handler-xhr-onloadend">onloadend</a>;
};
interface <dfn id="xmlhttprequestupload">XMLHttpRequestUpload</dfn> : <a href="#xmlhttprequesteventtarget">XMLHttpRequestEventTarget</a> {
};
enum <dfn id="xmlhttprequestresponsetype">XMLHttpRequestResponseType</dfn> {
"",
"arraybuffer",
"blob",
"document",
"json",
"text"
};
[<a href="#dom-xmlhttprequest" title="dom-XMLHttpRequest">Constructor</a>]
interface <dfn id="xmlhttprequest">XMLHttpRequest</dfn> : <a href="#xmlhttprequesteventtarget">XMLHttpRequestEventTarget</a> {
// <a href="#event-handlers">event handler</a>
attribute <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> <a href="#handler-xhr-onreadystatechange" title="handler-xhr-onreadystatechange">onreadystatechange</a>;
// <a href="#states">states</a>
const unsigned short <a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> = 0;
const unsigned short <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> = 1;
const unsigned short <a href="#dom-xmlhttprequest-headers_received" title="dom-XMLHttpRequest-HEADERS_RECEIVED">HEADERS_RECEIVED</a> = 2;
const unsigned short <a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a> = 3;
const unsigned short <a href="#dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE">DONE</a> = 4;
readonly attribute unsigned short <a href="#dom-xmlhttprequest-readystate" title="dom-XMLHttpRequest-readyState">readyState</a>;
// <a href="#request">request</a>
void <a href="#dom-xmlhttprequest-open" title="dom-XMLHttpRequest-open">open</a>(ByteString <var>method</var>, [EnsureUTF16] DOMString <var title="">url</var>);
void <a href="#dom-xmlhttprequest-open" title="dom-XMLHttpRequest-open">open</a>(ByteString <var>method</var>, [EnsureUTF16] DOMString <var title="">url</var>, boolean <var>async</var>, optional [EnsureUTF16] DOMString? <var>username</var> = null, optional [EnsureUTF16] DOMString? <var>password</var> = null);
void <a href="#dom-xmlhttprequest-setrequestheader" title="dom-XMLHttpRequest-setRequestHeader">setRequestHeader</a>(ByteString <var>name</var>, ByteString <var>value</var>);
attribute unsigned long <a href="#dom-xmlhttprequest-timeout" title="dom-XMLHttpRequest-timeout">timeout</a>;
attribute boolean <a href="#dom-xmlhttprequest-withcredentials" title="dom-XMLHttpRequest-withCredentials">withCredentials</a>;
readonly attribute <a href="#xmlhttprequestupload">XMLHttpRequestUpload</a> <a href="#dom-xmlhttprequest-upload" title="dom-XMLHttpRequest-upload">upload</a>;
void <a href="#dom-xmlhttprequest-send" title="dom-XMLHttpRequest-send">send</a>(optional (<a class="external" href="http://www.khronos.org/registry/typedarray/specs/latest/#6">ArrayBufferView</a> or <a class="external" href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a> or <a class="external" href="http://dom.spec.whatwg.org/#document">Document</a> or [EnsureUTF16] DOMString or <a href="#formdata">FormData</a> or <a class="external" href="http://url.spec.whatwg.org/#urlsearchparams">URLSearchParams</a>)? <var>data</var> = null);
void <a href="#dom-xmlhttprequest-abort" title="dom-XMLHttpRequest-abort">abort</a>();
// <a href="#response">response</a>
readonly attribute unsigned short <a href="#dom-xmlhttprequest-status" title="dom-XMLHttpRequest-status">status</a>;
readonly attribute ByteString <a href="#dom-xmlhttprequest-statustext" title="dom-XMLHttpRequest-statusText">statusText</a>;
ByteString? <a href="#dom-xmlhttprequest-getresponseheader" title="dom-XMLHttpRequest-getResponseHeader">getResponseHeader</a>(ByteString <var>name</var>);
ByteString <a href="#dom-xmlhttprequest-getallresponseheaders" title="dom-XMLHttpRequest-getAllResponseHeaders">getAllResponseHeaders</a>();
void <a href="#dom-xmlhttprequest-overridemimetype" title="dom-XMLHttpRequest-overrideMimeType">overrideMimeType</a>(DOMString <var>mime</var>);
attribute <a href="#xmlhttprequestresponsetype">XMLHttpRequestResponseType</a> <a href="#dom-xmlhttprequest-responsetype" title="dom-XMLHttpRequest-responseType">responseType</a>;
readonly attribute any <a href="#dom-xmlhttprequest-response" title="dom-XMLHttpRequest-response">response</a>;
readonly attribute DOMString <a href="#dom-xmlhttprequest-responsetext" title="dom-XMLHttpRequest-responseText">responseText</a>;
readonly attribute <a class="external" href="http://dom.spec.whatwg.org/#document">Document</a>? <a href="#dom-xmlhttprequest-responsexml" title="dom-XMLHttpRequest-responseXML">responseXML</a>;
};</pre>
<p>Each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has a unique, associated
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<p>If the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#worker-environment">worker environment</a>, implementations must act as if
<code title="">Document</code> and <code title="">Document?</code> in the above IDL were not
exposed. I.e. <code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> is not overloaded with it
and <code title="dom-XMLHttpRequest-responseXML"><a href="#dom-xmlhttprequest-responsexml">responseXML</a></code> always returns null (as
required by its definition, too).
<h3 id="constructors"><span class="secno">4.1 </span>Constructors</h3>
<p>When the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a>
is a <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a>, the
<code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has an associated
<dfn id="concept-xmlhttprequest-document" title="concept-XMLHttpRequest-document">document</dfn>.
<dl class="domintro">
<dt><code><var title="">client</var> = new <a href="#dom-xmlhttprequest" title="dom-XMLHttpRequest">XMLHttpRequest</a>()</code>
<dd>Returns a new <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object.
</dl>
<p>The
<dfn id="dom-xmlhttprequest" title="dom-XMLHttpRequest"><code>XMLHttpRequest()</code></dfn>
constructor must run these steps:
<ol>
<li><p>Let <var title="">xhr</var> be a new <code><a href="#xmlhttprequest">XMLHttpRequest</a></code>
object.
<li><p>If the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a>, set <var title="">xhr</var>'s
<a href="#concept-xmlhttprequest-document" title="concept-XMLHttpRequest-document">document</a> to the
<a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a>
associated with the global object of <var title="">xhr</var>'s interface
object.
<li><p>Return <var title="">xhr</var>.
</ol>
<h3 id="garbage-collection"><span class="secno">4.2 </span>Garbage collection</h3>
<!-- Based on EventSource and WebSocket. Not sure what I am doing. -->
<p>An <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object must not be garbage collected if
its state is <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> and the
<a href="#send-flag"><code>send()</code> flag</a> is set, its state is
<a href="#dom-xmlhttprequest-headers_received" title="dom-XMLHttpRequest-HEADERS_RECEIVED">HEADERS_RECEIVED</a>, or
its state is <a href="#dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING">LOADING</a>, and
one of the following is true:
<ul>
<li><p>It has one or more
<a class="external" href="http://dom.spec.whatwg.org/#concept-event-listener" title="concept-event-listener">event listeners</a>
registered whose <b>type</b> is
<code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>,
<code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>,
<code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>,
<code title="event-xhr-error"><a href="#event-xhr-error">error</a></code>,
<code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>,
<code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code>, or
<code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>.
<li><p>The <a href="#upload-complete-flag">upload complete flag</a> is unset and the associated
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object has one or more
<a class="external" href="http://dom.spec.whatwg.org/#concept-event-listener" title="concept-event-listener">event listeners</a>
registered whose <b>type</b> is
<code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>,
<code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>,
<code title="event-xhr-error"><a href="#event-xhr-error">error</a></code>,
<code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>,
<code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code>, or
<code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>.
</ul>
<p>If an <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object is garbage collected while its
connection is still open, the user agent must <a href="#terminate-the-request">terminate the request</a>.
<h3 id="event-handlers"><span class="secno">4.3 </span>Event handlers</h3>
<p>The following are the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers">event handlers</a> (and their corresponding
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type" title="event handler event type">event handler event types</a>)
that must be supported on objects implementing an interface that inherits
from <code><a href="#xmlhttprequesteventtarget">XMLHttpRequestEventTarget</a></code> as attributes:
<table>
<thead>
<tr>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers" title="event handlers">event handler</a>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type">event handler event type</a>
<tbody>
<tr>
<td><dfn id="handler-xhr-onloadstart" title="handler-xhr-onloadstart"><code>onloadstart</code></dfn>
<td><code title="event-xhr-loadstart"><a href="#event-xhr-loadstart">loadstart</a></code>
<tr>
<td><dfn id="handler-xhr-onprogress" title="handler-xhr-onprogress"><code>onprogress</code></dfn>
<td><code title="event-xhr-progress"><a href="#event-xhr-progress">progress</a></code>
<tr>
<td><dfn id="handler-xhr-onabort" title="handler-xhr-onabort"><code>onabort</code></dfn>
<td><code title="event-xhr-abort"><a href="#event-xhr-abort">abort</a></code>
<tr>
<td><dfn id="handler-xhr-onerror" title="handler-xhr-onerror"><code>onerror</code></dfn>
<td><code title="event-xhr-error"><a href="#event-xhr-error">error</a></code>
<tr>
<td><dfn id="handler-xhr-onload" title="handler-xhr-onload"><code>onload</code></dfn>
<td><code title="event-xhr-load"><a href="#event-xhr-load">load</a></code>
<tr>
<td><dfn id="handler-xhr-ontimeout" title="handler-xhr-ontimeout"><code>ontimeout</code></dfn>
<td><code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code>
<tr>
<td><dfn id="handler-xhr-onloadend" title="handler-xhr-onloadend"><code>onloadend</code></dfn>
<td><code title="event-xhr-loadend"><a href="#event-xhr-loadend">loadend</a></code>
</table>
<p>The following is the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers" title="event handlers">event handler</a>
(and its corresponding
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type">event handler event type</a>) that must be
supported as attribute solely by the
<code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object:
<table>
<thead>
<tr>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers" title="event handlers">event handler</a>
<th><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type">event handler event type</a>
<tbody>
<tr>
<td><dfn id="handler-xhr-onreadystatechange" title="handler-xhr-onreadystatechange"><code>onreadystatechange</code></dfn>
<td><code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code></td>
</table>
<h3 id="states"><span class="secno">4.4 </span>States</h3>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-readystate" title="dom-XMLHttpRequest-readyState">readyState</a></code>
<dd><p>Returns the current state.
</dl>
<p>The <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object can be in several states. The
<dfn id="dom-xmlhttprequest-readystate" title="dom-XMLHttpRequest-readyState"><code>readyState</code></dfn>
attribute must return the current state, which must be one of the
following values:
<dl>
<dt><dfn id="dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT"><code>UNSENT</code></dfn>
(numeric value 0)</dt>
<dd><p>The object has been constructed.</dd>
<dt><dfn id="dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED"><code>OPENED</code></dfn>
(numeric value 1)</dt>
<dd><p>The <code title="dom-XMLHttpRequest-open"><a href="#dom-xmlhttprequest-open">open()</a></code> method has been successfully invoked.
During this state request headers can be set using
<code title="dom-XMLHttpRequest-setRequestHeader"><a href="#dom-xmlhttprequest-setrequestheader">setRequestHeader()</a></code>
and the request can be made using the
<code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method.</dd>
<dt><dfn id="dom-xmlhttprequest-headers_received" title="dom-XMLHttpRequest-HEADERS_RECEIVED"><code>HEADERS_RECEIVED</code></dfn>
(numeric value 2)</dt>
<dd><p>All redirects (if any) have been followed and all HTTP headers of
the final response have been received. Several response members of the
object are now available.</dd>
<dt><dfn id="dom-xmlhttprequest-loading" title="dom-XMLHttpRequest-LOADING"><code>LOADING</code></dfn>
(numeric value 3)</dt>
<dd><p>The <a href="#response-entity-body">response entity body</a> is being received.</dd>
<dt><dfn id="dom-xmlhttprequest-done" title="dom-XMLHttpRequest-DONE"><code>DONE</code></dfn>
(numeric value 4)</dt>
<dd><p>The data transfer has been completed or something went wrong
during the transfer (e.g. infinite redirects).</dd>
</dl>
<p>The <dfn id="send-flag"><code>send()</code> flag</dfn> indicates
that the <code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method has
been invoked. It is initially unset and is used during the
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> state.
<h3 id="request"><span class="secno">4.5 </span>Request</h3>
<p>Each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object has the following
request-associated concepts:
<dfn id="request-method">request method</dfn>,
<dfn id="request-url">request URL</dfn>,
<dfn id="author-request-headers">author request headers</dfn>,
<dfn id="request-entity-body">request entity body</dfn>,
<dfn id="source-origin">source origin</dfn>,
<dfn id="referrer-source">referrer source</dfn>,
<dfn id="synchronous-flag">synchronous flag</dfn>,
<dfn id="upload-complete-flag">upload complete flag</dfn>, and
<dfn id="upload-events-flag">upload events flag</dfn>.
<p>The <a href="#author-request-headers">author request headers</a> is an initially empty list of
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header" title="concept-header">headers</a>.
<p>The <a href="#request-entity-body">request entity body</a> is initially null.
<p>The <a href="#synchronous-flag">synchronous flag</a>,
<a href="#upload-complete-flag">upload complete flag</a>, and
<a href="#upload-events-flag">upload events flag</a> are initially unset.
<hr>
<p>To <dfn id="terminate-the-request">terminate the request</dfn>,
<a class="external" href="http://fetch.spec.whatwg.org/#concept-fetch-terminate" title="concept-fetch-terminate">terminate</a> the
<a class="external" href="http://fetch.spec.whatwg.org/#concept-fetch" title="concept-fetch">fetch</a> algorithm operated by the
<code><a href="#xmlhttprequest">XMLHttpRequest</a></code> object with reason <i title="">fatal</i>.
<h4 id="the-open()-method"><span class="secno">4.5.1 </span>The <code title="">open()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-open" title="dom-XMLHttpRequest-open">open</a>(<var title="">method</var>, <var title="">url</var> [, <var title="">async</var> = true [, <var title="">username</var> = null [, <var title="">password</var> = null]]])</code>
<dd>
<p>Sets the <a href="#request-method">request method</a>, <a href="#request-url">request URL</a>, and
<a href="#synchronous-flag">synchronous flag</a>.
<p>Throws a "<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception if
either <var title="">method</var> is not a valid HTTP method or
<var title="">url</var> cannot be parsed.
<p>Throws a "<code class="external"><a href="http://dom.spec.whatwg.org/#securityerror">SecurityError</a></code>" exception
if <var title="">method</var> is a case-insensitive match for
`<code title="">CONNECT</code>`, `<code title="">TRACE</code>` or `<code title="">TRACK</code>`.
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>"
exception if <var title="">async</var> is false, the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a>, and either the
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> attribute is not
zero, the
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute is true, or the
<code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code>
attribute is not the empty string.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-open" title="dom-XMLHttpRequest-open"><code>open(<var title="">method</var>, <var title="">url</var>, <var title="">async</var>, <var title="">username</var>, <var title="">password</var>)</code></dfn>
method must run these steps:
<ol>
<li><p>Let <var title="">base</var> be null.
<li>
<p>If the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a>, run these steps:
<ol>
<li><p>If <a href="#concept-xmlhttprequest-document" title="concept-XMLHttpRequest-document">document</a> is not
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#fully-active">fully active</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception.
<li><p>Set <var title="">base</var> to the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#document-base-url">document base URL</a> of
<a href="#concept-xmlhttprequest-document" title="concept-XMLHttpRequest-document">document</a>.
<li><p>Set <a href="#source-origin">source origin</a> to the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#origin">origin</a>
of <a href="#concept-xmlhttprequest-document" title="concept-XMLHttpRequest-document">document</a> otherwise.
<li><p>Set <a href="#referrer-source">referrer source</a> to
<a href="#concept-xmlhttprequest-document" title="concept-XMLHttpRequest-document">document</a>.
</ol>
<li>
<p>If the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#worker-environment">worker environment</a>, run these steps:
<ol>
<li><p>Set <var title="">base</var> to the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-base-url">script's base URL</a>.
<li><p>Set <a href="#source-origin">source origin</a> to the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-script" title="concept-script">script</a>'s
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#origin">origin</a>.
<li><p>Set <a href="#referrer-source">referrer source</a> to the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-referrer-source">script's referrer source</a>.
</ol>
<li><p>If <var>method</var> does not match the <a class="external" href="http://tools.ietf.org/html/rfc2616/#section-5.1.1">Method</a>
token production, <a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception.
<li><p>If <var>method</var> is a
<a class="external" href="http://fetch.spec.whatwg.org/#concept-forbidden-methods" title="concept-forbidden-methods">forbidden method</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#securityerror">SecurityError</a></code>" exception.
<li>
<p>If <var>method</var> is a case-insensitive match for `<code title="">DELETE</code>`,
`<code title="">GET</code>`, `<code title="">HEAD</code>`, `<code title="">OPTIONS</code>`,
`<code title="">POST</code>`, or `<code title="">PUT</code>`, subtract
0x20 from each byte in the range 0x61 (ASCII a) to 0x7A (ASCII z).
<p class="note">If it does not match any of the above, it is passed
through <em>literally</em>, including in the final request.
<!-- WebKit (and supposedly Gecko) also uppercase: COPY, INDEX, LOCK,
M-POST, MKCOL, MOVE, PROPFIND, PROPPATCH, and UNLOCK. -->
<li><p>Let <var title="">parsed URL</var> be the result of
<a class="external" href="http://url.spec.whatwg.org/#concept-url-parser" title="concept-url-parser">parsing</a> <var title="">url</var>
with <var title="">base</var>.
<li><p>If <var title="">parsed URL</var> is failure,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception.
<li>
<p>If the <var>async</var> argument is omitted, set <var>async</var> to true, and set
<var title="">username</var> and <var title="">password</var> to null.
<p class="note">Due to unfortunate legacy constraints, passing
<code title="">undefined</code> for the <var>async</var> argument is treated differently
from <var>async</var> being omitted.
<li>
<p>If <var title="">parsed URL</var>'s <a class="external" href="http://url.spec.whatwg.org/#relative-flag">relative flag</a> is
set, run these substeps:
<ol>
<li><p>If the <var title="">username</var> argument is not null, set
<var title="">parsed URL</var>'s
<a class="external" href="http://url.spec.whatwg.org/#concept-url-username" title="concept-url-username">username</a> to
<var>username</var>.
<li><p>If the <var title="">password</var> argument is not null, set
<var title="">parsed URL</var>'s
<a class="external" href="http://url.spec.whatwg.org/#concept-url-password" title="concept-url-password">password</a> to
<var>password</var>.
</ol>
<li><p>If <var>async</var> is false, the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a>, and either the
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> attribute value is not zero, the
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code> attribute value is
true, or the <code title="dom-XMLHttpRequest-responseType"><a href="#dom-xmlhttprequest-responsetype">responseType</a></code> attribute
value is not the empty string,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception.
<li>
<p><a href="#terminate-the-request">Terminate the request</a>.
<p class="note">After all, a request can be ongoing at this point.
<li>
<p>Set variables associated with the object as follows:
<ul>
<li><p>Set <a href="#request-method">request method</a> to <var>method</var>.
<li><p>Set <a href="#request-url">request URL</a> to <var title="">parsed URL</var>.
<li><p>Set the <a href="#synchronous-flag">synchronous flag</a>, if <var>async</var> is false, and unset
the <a href="#synchronous-flag">synchronous flag</a> otherwise.
<li><p>Set <a href="#author-request-headers">author request headers</a> to the empty list.
<li><p>Unset the <a href="#send-flag"><code>send()</code> flag</a>.
<li><p>Set <a href="#response-0">response</a> to a
<a class="external" href="http://fetch.spec.whatwg.org/#concept-network-error" title="concept-network-error">network error</a>.
<li><p>Set <a href="#arraybuffer-response-entity-body">arraybuffer response entity body</a> to null.
<li><p>Set <a href="#blob-response-entity-body">blob response entity body</a> to null.
<li><p>Set <a href="#document-response-entity-body">document response entity body</a> to null.
<li><p>Set <a href="#json-response-entity-body">JSON response entity body</a> to null.
<li><p>Set <a href="#text-response-entity-body">text response entity body</a> to null.
</ul>
<li>
<p>If the state is not <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>, run these
substeps:
<ol>
<li><p>Change the state to <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>.
<li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-xhr-readystatechange"><a href="#event-xhr-readystatechange">readystatechange</a></code>.
</ol>
</ol>
<h4 id="the-setrequestheader()-method"><span class="secno">4.5.2 </span>The <code title="">setRequestHeader()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-setrequestheader" title="dom-XMLHttpRequest-setRequestHeader">setRequestHeader</a>(<var>name</var>, <var>value</var>)</code>
<dd>
<p>Appends an <a class="external" href="http://fetch.spec.whatwg.org/#concept-header" title="concept-header">header</a> to
<a href="#author-request-headers">author request headers</a>, or if <var>name</var> is already a
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header" title="concept-header">header</a>'s
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header-name" title="concept-header-name">name</a> in
<a href="#author-request-headers">author request headers</a>, appends <var>value</var> to that
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header" title="concept-header">header</a>'s
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header-value" title="concept-header-value">value</a>.
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>"
exception if the state is not
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> or if the
<a href="#send-flag"><code>send()</code> flag</a> is set.
<p>Throws a "<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception if
<var>name</var> is not a valid HTTP header field name or if
<var>value</var> is not a valid HTTP header field value.
</dd>
</dl>
<p class="note">As indicated in the algorithm below certain headers cannot
be set and are left up to the user agent. In addition there are certain
other headers the user agent will take control of if they are not set by
the author as indicated at the end of the
<code title="dom-XMLHttpRequest-send"><a href="#dom-xmlhttprequest-send">send()</a></code> method section.
<p>The
<dfn id="dom-xmlhttprequest-setrequestheader" title="dom-XMLHttpRequest-setRequestHeader"><code>setRequestHeader(<var>name</var>, <var>value</var>)</code></dfn>
method must run these steps:
<ol>
<li><p>If the state is not <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception.
<li><p>If the <a href="#send-flag"><code>send()</code> flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception.
<li><p>If <var>name</var> does not match the
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-4.2">field-name</a> production,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception.
<li>
<p>If <var>value</var> does not match the
<a class="external" href="http://tools.ietf.org/html/rfc2616/#section-4.2">field-value</a> production,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> a
"<code class="external"><a href="http://dom.spec.whatwg.org/#syntaxerror">SyntaxError</a></code>" exception.
<p class="note">An empty string represents an empty header field value.
<li><p>Terminate these steps if <var>name</var> is a
<a class="external" href="http://fetch.spec.whatwg.org/#concept-forbidden-author-header-names" title="concept-forbidden-author-header-names">forbidden author header name</a>.
<li><p>If <var>name</var> is not a
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header-name" title="concept-header-name">name</a> of a
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header" title="concept-header">header</a> in
<a href="#author-request-headers">author request headers</a>, append a
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header" title="concept-header">header</a> whose
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header-name" title="concept-header-name">name</a> is
<var>name</var> and
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header-value" title="concept-header-value">value</a> is
<var>value</var> to <a href="#author-request-headers">author request headers</a>.
<li>
<p>Otherwise, append `<code>,</code>`, followed by 0x20, followed by
<var>value</var>, to the
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header-value" title="concept-header-value">value</a> of the
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header" title="concept-header">header</a> in
<a href="#author-request-headers">author request headers</a> whose
<a class="external" href="http://fetch.spec.whatwg.org/#concept-header-name" title="concept-header-name">name</a> is
<var>name</var>.
<p class="note">The XMLHttpRequest standard intentionally constraints the
use of HTTP here in line with contemporary implementations.
</ol>
<div class="example">
<p>Some simple code demonstrating what happens when setting the same
header twice:
<pre><code>// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send();
// …results in the following header being sent:
X-Test: one, two</code></pre>
</div>
<h4 id="the-timeout-attribute"><span class="secno">4.5.3 </span>The <code title="">timeout</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-timeout" title="dom-XMLHttpRequest-timeout">timeout</a></code>
<dd>
<p>Can be set to a time in milliseconds. When set to a non-zero value
will cause <a class="external" href="http://fetch.spec.whatwg.org/#concept-fetch" title="concept-fetch">fetching</a> to
terminate after the given time has passed. When the time has passed, the request has
not yet completed, and the <a href="#synchronous-flag">synchronous flag</a> is unset, a
<code title="event-xhr-timeout"><a href="#event-xhr-timeout">timeout</a></code> event will then be
<a class="external" href="http://dom.spec.whatwg.org/#concept-event-dispatch" title="concept-event-dispatch">dispatched</a>,
or a "<code class="external"><a href="http://dom.spec.whatwg.org/#timeouterror">TimeoutError</a></code>" exception will be
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">thrown</a> otherwise
(for the <code title="dom-XMLHttpRequest"><a href="#dom-xmlhttprequest">send()</a></code> method).
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception if
the <a href="#synchronous-flag">synchronous flag</a> is set and the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a>.
</dd>
</dl>
<p>The
<dfn id="dom-xmlhttprequest-timeout" title="dom-XMLHttpRequest-timeout"><code>timeout</code></dfn>
attribute must return its value. Initially its value must be zero.
<p>Setting the <code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code>
attribute must run these steps:
<ol>
<li><p>If the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a> and the
<a href="#synchronous-flag">synchronous flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception.
<li><p>Set its value to the new value.
</ol>
<p class="note">This implies that the
<code title="dom-XMLHttpRequest-timeout"><a href="#dom-xmlhttprequest-timeout">timeout</a></code> attribute can be
set while <a class="external" href="http://fetch.spec.whatwg.org/#concept-fetch" title="concept-fetch">fetching</a> is in
progress. If that occurs it will still be measured relative to the start
of <a class="external" href="http://fetch.spec.whatwg.org/#concept-fetch" title="concept-fetch">fetching</a>.
<h4 id="the-withcredentials-attribute"><span class="secno">4.5.4 </span>The <code title="">withCredentials</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-withcredentials" title="dom-XMLHttpRequest-withCredentials">withCredentials</a></code>
<dd>
<p>True when <a href="#user-credentials">user credentials</a> are to be included in a
cross-origin request. False when they are to be excluded in a
cross-origin request and when cookies are to be ignored in its response.
Initially false.
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception if the
state is not <a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>, or if
the <a href="#send-flag"><code>send()</code> flag</a> is set.
<p>When set: throws an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception if
either the <a href="#synchronous-flag">synchronous flag</a> is set and the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a>.
</dd>
</dl>
<p>The
<dfn id="dom-xmlhttprequest-withcredentials" title="dom-XMLHttpRequest-withCredentials"><code>withCredentials</code></dfn>
attribute must return its value. Initially its value must be false.
<p>Setting the
<code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute must run these steps:
<ol>
<li><p>If the state is not <a href="#dom-xmlhttprequest-unsent" title="dom-XMLHttpRequest-UNSENT">UNSENT</a> or
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception.
<li><p>If the <a href="#send-flag"><code>send()</code> flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception.
<li><p>If the
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#javascript-global-environment">JavaScript global environment</a> is a
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#document-environment">document environment</a> and the
<a href="#synchronous-flag">synchronous flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidaccesserror">InvalidAccessError</a></code>" exception.
<li><p>Set the <code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute's value to the given value.
</ol>
<p class="note">The <code title="dom-XMLHttpRequest-withCredentials"><a href="#dom-xmlhttprequest-withcredentials">withCredentials</a></code>
attribute has no effect when
<a class="external" href="http://fetch.spec.whatwg.org/#concept-fetch" title="concept-fetch">fetching</a>
<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin" title="same origin">same-origin</a> resources.
<h4 id="the-upload-attribute"><span class="secno">4.5.5 </span>The <code title="">upload</code> attribute</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-upload" title="dom-XMLHttpRequest-upload">upload</a></code>
<dd><p>Returns the associated <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code>
object. It can be used to gather transmission information when data is
transferred to a server.
</dl>
<p>The
<dfn id="dom-xmlhttprequest-upload" title="dom-XMLHttpRequest-upload"><code>upload</code></dfn>
attribute must return the associated
<code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<p class="note">As indicated earlier, each <code><a href="#xmlhttprequest">XMLHttpRequest</a></code>
object has an associated <code><a href="#xmlhttprequestupload">XMLHttpRequestUpload</a></code> object.
<h4 id="the-send()-method"><span class="secno">4.5.6 </span>The <code title="">send()</code> method</h4>
<dl class="domintro">
<dt><code><var title="">client</var> . <a href="#dom-xmlhttprequest-send" title="dom-XMLHttpRequest-send">send</a>([<var title="">data</var> = null])</code>
<dd>
<p>Initiates the request. The optional argument provides the
<a href="#request-entity-body">request entity body</a>. The argument is ignored if
<a href="#request-method">request method</a> is <code>GET</code> or
<code>HEAD</code>.
<p>Throws an "<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>"
exception if the state is not
<a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a> or if the
<a href="#send-flag"><code>send()</code> flag</a> is set.
</dd>
</dl>
<p>The <dfn id="dom-xmlhttprequest-send" title="dom-XMLHttpRequest-send"><code>send(<var>data</var>)</code></dfn>
method must run these steps:
<ol>
<li><p>If the state is not <a href="#dom-xmlhttprequest-opened" title="dom-XMLHttpRequest-OPENED">OPENED</a>,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception.
<li><p>If the <a href="#send-flag"><code>send()</code> flag</a> is set,
<a class="external" href="http://dom.spec.whatwg.org/#concept-throw" title="concept-throw">throw</a> an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception.
<li><p>If the <a href="#request-method">request method</a> is <code>GET</code> or
<code>HEAD</code>, set <var title="">data</var> to null.
<li>
<p>If <var title="">data</var> is null, do not include a
<a href="#request-entity-body">request entity body</a> and go to the next step.
<p>Otherwise, let <var>encoding</var> be null, <var>mime type</var> be
null, and then follow these rules, depending on <var title="">data</var>:
<dl class="switch">
<dt id="dom-XMLHttpRequest-send-ArrayBufferView"><code class="external"><a href="http://www.khronos.org/registry/typedarray/specs/latest/#6">ArrayBufferView</a></code>
<dd><p>Let the <a href="#request-entity-body">request entity body</a> be the raw data
represented by <var title="">data</var>.</dd>
<dt id="dom-XMLHttpRequest-send-Blob"><code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code>
<dd>
<p>If the object's <code title="">type</code> attribute value is not
the empty string, let <var>mime type</var> be its value.
<p class="note">See also <code class="external"><a href="http://dev.w3.org/2006/webapi/FileAPI/#blob">Blob</a></code>'s
<code class="external" title="dom-Blob-type"><a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-type">type</a></code> attribute.
<p>Let the <a href="#request-entity-body">request entity body</a> be the raw data
represented by <var>data</var>.
</dd>
<dt id="dom-XMLHttpRequest-send-document"><a class="external" href="http://dom.spec.whatwg.org/#concept-document" title="concept-document">document</a>
<dd>
<p>Let <var>encoding</var> be "<code title="">UTF-8</code>".
<p>If <var>data</var> is an <a class="external" href="http://dom.spec.whatwg.org/#html-document">HTML document</a>, let
<var>mime type</var> be "<code>text/html</code>", or let <var>mime type</var> be
"<code>application/xml</code>" otherwise. Then append "<code>;charset=UTF-8</code>" to
<var>mime type</var>.
<p>Let the <a href="#request-entity-body">request entity body</a> be <var>data</var>,
<a class="external" href="http://domparsing.spec.whatwg.org/#concept-serialize" title="concept-serialize">serialized</a>,
<a class="external" href="http://dev.w3.org/2006/webapi/WebIDL/#dfn-obtain-unicode" title="convert a DOMString to a sequence of Unicode characters">converted to Unicode</a>,
and <a class="external" href="http://encoding.spec.whatwg.org/#utf-8-encode" title="utf-8 encode">utf-8 encoded</a>.
Re-throw any exception
<a class="external" href="http://domparsing.spec.whatwg.org/#concept-serialize" title="concept-serialize">serializing</a> throws.
<p class="note">If <var>data</var> cannot be
<a class="external" href="http://domparsing.spec.whatwg.org/#concept-serialize" title="concept-serialize">serialized</a>, an
"<code class="external"><a href="http://dom.spec.whatwg.org/#invalidstateerror">InvalidStateError</a></code>" exception is thrown.
<dt id="dom-XMLHttpRequest-send-a-string">a string
<dd>
<p>Let <var>encoding</var> be "<code title="">UTF-8</code>".
<p>Let <var>mime type</var> be "<code>text/plain;charset=UTF-8</code>".
<p>Let the <a href="#request-entity-body">request entity body</a> be <var title="">data</var>,
<a class="external" href="http://encoding.spec.whatwg.org/#utf-8-encode" title="utf-8 encode">utf-8 encoded</a>.