-
Notifications
You must be signed in to change notification settings - Fork 131
/
Overview.src.html
2351 lines (1848 loc) · 94.1 KB
/
Overview.src.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 src=//resources.whatwg.org/logo-xhr.svg width=100 height=100></a>
<h1 class="head" id="xmlhttprequest-ls">XMLHttpRequest</h1>
<h2 class="no-num no-toc">Living Standard — Last Updated [DATE: 3 August 2002]</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 src=//resources.whatwg.org/file-bug.js async></script>
<p class=copyright><a rel=license href="http://creativecommons.org/publicdomain/zero/1.0/"><img src="http://i.creativecommons.org/p/zero/1.0/80x15.png" alt=CC0></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
[DATE: 01 Jan 1901], the editor has made this specification available
under the
<a rel=license
href="http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0">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>
<!--toc-->
<h2 id="introduction">Introduction</h2>
<p><em>This section is non-normative.</em>
<p>The <code>XMLHttpRequest</code> object is an API for
<span data-anolis-spec=fetch title=concept-fetch>fetching</span> resources.
<p>The name <code>XMLHttpRequest</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>Specification history</h3>
<p>The <code>XMLHttpRequest</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>XMLHttpRequest</code> were developed in a
separate draft (XMLHttpRequest Level 2) until end of 2011, at which point
the two drafts were merged and <code>XMLHttpRequest</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">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.
<span data-anolis-ref>RFC2119</span>
<h3 id="extensibility">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">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.
<span data-anolis-ref>DOM</span>
<span data-anolis-ref>DOMPS</span>
<span data-anolis-ref>ENCODING</span>
<span data-anolis-ref>FETCH</span>
<span data-anolis-ref>FILEAPI</span>
<span data-anolis-ref>HTML</span>
<span data-anolis-ref>HTTP</span>
<span data-anolis-ref>TYPEDARRAY</span>
<span data-anolis-ref>URL</span>
<span data-anolis-ref>WEBIDL</span>
<span data-anolis-ref>XML</span> <span data-anolis-ref>XMLNS</span>
<p>It uses the typographic conventions from HTML. <span data-anolis-ref>HTML</span>
<p>The term <dfn>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.
<span data-anolis-ref>COOKIES</span> <!-- XXX ref? -->
<h2>Interface <code title>XMLHttpRequest</code></h2>
<pre class="idl">[NoInterfaceObject]
interface <dfn id="xmlhttprequesteventtarget">XMLHttpRequestEventTarget</dfn> : <span data-anolis-spec=dom>EventTarget</span> {
// <a href="#event-handlers">event handlers</a>
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-onloadstart">onloadstart</span>;
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-onprogress">onprogress</span>;
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-onabort">onabort</span>;
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-onerror">onerror</span>;
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-onload">onload</span>;
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-ontimeout">ontimeout</span>;
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-onloadend">onloadend</span>;
};
[Exposed=Window,Worker]
interface <dfn id="xmlhttprequestupload">XMLHttpRequestUpload</dfn> : <span>XMLHttpRequestEventTarget</span> {
};
enum <dfn>XMLHttpRequestResponseType</dfn> {
"",
"arraybuffer",
"blob",
"document",
"json",
"text"
};
[<span title="dom-XMLHttpRequest">Constructor</span>,
Exposed=Window,Worker]
interface <dfn id="xmlhttprequest">XMLHttpRequest</dfn> : <span>XMLHttpRequestEventTarget</span> {
// <a href="#event-handlers">event handler</a>
attribute <span data-anolis-spec=html>EventHandler</span> <span title="handler-xhr-onreadystatechange">onreadystatechange</span>;
// <a href="#states">states</a>
const unsigned short <span title="dom-XMLHttpRequest-UNSENT">UNSENT</span> = 0;
const unsigned short <span title="dom-XMLHttpRequest-OPENED">OPENED</span> = 1;
const unsigned short <span title="dom-XMLHttpRequest-HEADERS_RECEIVED">HEADERS_RECEIVED</span> = 2;
const unsigned short <span title="dom-XMLHttpRequest-LOADING">LOADING</span> = 3;
const unsigned short <span title="dom-XMLHttpRequest-DONE">DONE</span> = 4;
readonly attribute unsigned short <span title="dom-XMLHttpRequest-readyState">readyState</span>;
// <a href="#request">request</a>
void <span title="dom-XMLHttpRequest-open">open</span>(ByteString <var>method</var>, [EnsureUTF16] DOMString <var title>url</var>);
void <span title="dom-XMLHttpRequest-open">open</span>(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 <span title="dom-XMLHttpRequest-setRequestHeader">setRequestHeader</span>(ByteString <var>name</var>, ByteString <var>value</var>);
attribute unsigned long <span title="dom-XMLHttpRequest-timeout">timeout</span>;
attribute boolean <span title="dom-XMLHttpRequest-withCredentials">withCredentials</span>;
readonly attribute <span>XMLHttpRequestUpload</span> <span title="dom-XMLHttpRequest-upload">upload</span>;
void <span title="dom-XMLHttpRequest-send">send</span>(optional (<span data-anolis-spec=typedarray>ArrayBufferView</span> or <span data-anolis-spec=fileapi>Blob</span> or <span data-anolis-spec=dom>Document</span> or [EnsureUTF16] DOMString or <span>FormData</span> or <span data-anolis-spec=url>URLSearchParams</span>)? <var>data</var> = null);
void <span title="dom-XMLHttpRequest-abort">abort</span>();
// <a href="#response">response</a>
readonly attribute DOMString <span title=dom-XMLHttpRequest-responseURL>responseURL</span>;
readonly attribute unsigned short <span title="dom-XMLHttpRequest-status">status</span>;
readonly attribute ByteString <span title="dom-XMLHttpRequest-statusText">statusText</span>;
ByteString? <span title="dom-XMLHttpRequest-getResponseHeader">getResponseHeader</span>(ByteString <var>name</var>);
ByteString <span title="dom-XMLHttpRequest-getAllResponseHeaders">getAllResponseHeaders</span>();
void <span title="dom-XMLHttpRequest-overrideMimeType">overrideMimeType</span>(DOMString <var>mime</var>);
attribute <span>XMLHttpRequestResponseType</span> <span title="dom-XMLHttpRequest-responseType">responseType</span>;
readonly attribute any <span title="dom-XMLHttpRequest-response">response</span>;
readonly attribute DOMString <span title="dom-XMLHttpRequest-responseText">responseText</span>;
[Exposed=Window] readonly attribute <span data-anolis-spec=dom>Document</span>? <span title="dom-XMLHttpRequest-responseXML">responseXML</span>;
};</pre>
<p>Each <code>XMLHttpRequest</code> object has a unique, associated
<code>XMLHttpRequestUpload</code> object.
<h3 id="constructors">Constructors</h3>
<p>The <code>XMLHttpRequest</code> object has an associated
<dfn title=concept-XMLHttpRequest-settings-object>settings object</dfn>.
<dl class=domintro>
<dt><code><var title>client</var> = new <span title=dom-XMLHttpRequest>XMLHttpRequest</span>()</code>
<dd>Returns a new <code>XMLHttpRequest</code> object.
</dl>
<p>The
<dfn title="dom-XMLHttpRequest"><code>XMLHttpRequest()</code></dfn>
constructor must run these steps:
<ol>
<li><p>Let <var title>xhr</var> be a new <code>XMLHttpRequest</code>
object.
<li><p>Set <var title>xhr</var>'s
<span title=concept-XMLHttpRequest-settings-object>settings object</span> to the
<span data-anolis-spec=html title="relevant settings object for a global object">relevant settings object</span>
for the global object of <var title>xhr</var>'s interface object.
<li><p>Return <var title>xhr</var>.
</ol>
<h3>Garbage collection</h3>
<!-- Based on EventSource and WebSocket. Not sure what I am doing. -->
<p>An <code>XMLHttpRequest</code> object must not be garbage collected if
its state is <span title=dom-XMLHttpRequest-OPENED>OPENED</span> and the
<span><code>send()</code> flag</span> is set, its state is
<span title=dom-XMLHttpRequest-HEADERS_RECEIVED>HEADERS_RECEIVED</span>, or
its state is <span title=dom-XMLHttpRequest-LOADING>LOADING</span>, and
one of the following is true:
<ul>
<li><p>It has one or more
<span data-anolis-spec=dom title=concept-event-listener>event listeners</span>
registered whose <b>type</b> is
<code title=event-xhr-readystatechange>readystatechange</code>,
<code title=event-xhr-progress>progress</code>,
<code title=event-xhr-abort>abort</code>,
<code title=event-xhr-error>error</code>,
<code title=event-xhr-load>load</code>,
<code title=event-xhr-timeout>timeout</code>, or
<code title=event-xhr-loadend>loadend</code>.
<li><p>The <span>upload complete flag</span> is unset and the associated
<code>XMLHttpRequestUpload</code> object has one or more
<span data-anolis-spec=dom title=concept-event-listener>event listeners</span>
registered whose <b>type</b> is
<code title=event-xhr-progress>progress</code>,
<code title=event-xhr-abort>abort</code>,
<code title=event-xhr-error>error</code>,
<code title=event-xhr-load>load</code>,
<code title=event-xhr-timeout>timeout</code>, or
<code title=event-xhr-loadend>loadend</code>.
</ul>
<p>If an <code>XMLHttpRequest</code> object is garbage collected while its
connection is still open, the user agent must <span>terminate the request</span>.
<h3 id="event-handlers">Event handlers</h3>
<p>The following are the
<span data-anolis-spec=html>event handlers</span> (and their corresponding
<span data-anolis-spec=html title="event handler event type">event handler event types</span>)
that must be supported on objects implementing an interface that inherits
from <code>XMLHttpRequestEventTarget</code> as attributes:
<table>
<thead>
<tr>
<th><span data-anolis-spec=html title="event handlers">event handler</span>
<th><span data-anolis-spec=html>event handler event type</span>
<tbody>
<tr>
<td><dfn title="handler-xhr-onloadstart"><code>onloadstart</code></dfn>
<td><code title="event-xhr-loadstart">loadstart</code>
<tr>
<td><dfn title="handler-xhr-onprogress"><code>onprogress</code></dfn>
<td><code title="event-xhr-progress">progress</code>
<tr>
<td><dfn title="handler-xhr-onabort"><code>onabort</code></dfn>
<td><code title="event-xhr-abort">abort</code>
<tr>
<td><dfn title="handler-xhr-onerror"><code>onerror</code></dfn>
<td><code title="event-xhr-error">error</code>
<tr>
<td><dfn title="handler-xhr-onload"><code>onload</code></dfn>
<td><code title="event-xhr-load">load</code>
<tr>
<td><dfn title="handler-xhr-ontimeout"><code>ontimeout</code></dfn>
<td><code title="event-xhr-timeout">timeout</code>
<tr>
<td><dfn title="handler-xhr-onloadend"><code>onloadend</code></dfn>
<td><code title="event-xhr-loadend">loadend</code>
</table>
<p>The following is the
<span data-anolis-spec=html title="event handlers">event handler</span>
(and its corresponding
<span data-anolis-spec=html>event handler event type</span>) that must be
supported as attribute solely by the
<code>XMLHttpRequest</code> object:
<table>
<thead>
<tr>
<th><span data-anolis-spec=html title="event handlers">event handler</span>
<th><span data-anolis-spec=html>event handler event type</span>
<tbody>
<tr>
<td><dfn title="handler-xhr-onreadystatechange"><code>onreadystatechange</code></dfn>
<td><code title="event-xhr-readystatechange">readystatechange</code></td>
</table>
<h3 id="states">States</h3>
<dl class=domintro>
<dt><code><var title>client</var> . <span title="dom-XMLHttpRequest-readyState">readyState</span></code>
<dd><p>Returns the current state.
</dl>
<p>The <code>XMLHttpRequest</code> object can be in several states. The
<dfn 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 title="dom-XMLHttpRequest-UNSENT"><code>UNSENT</code></dfn>
(numeric value 0)</dt>
<dd><p>The object has been constructed.</dd>
<dt><dfn title="dom-XMLHttpRequest-OPENED"><code>OPENED</code></dfn>
(numeric value 1)</dt>
<dd><p>The <code title="dom-XMLHttpRequest-open">open()</code> method has been successfully invoked.
During this state request headers can be set using
<code title="dom-XMLHttpRequest-setRequestHeader">setRequestHeader()</code>
and the request can be made using the
<code title="dom-XMLHttpRequest-send">send()</code> method.</dd>
<dt><dfn 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 title="dom-XMLHttpRequest-LOADING"><code>LOADING</code></dfn>
(numeric value 3)</dt>
<dd><p>The <span>response entity body</span> is being received.</dd>
<dt><dfn 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">send()</code> method has
been invoked. It is initially unset and is used during the
<span title="dom-XMLHttpRequest-OPENED">OPENED</span> state.
<h3 id="request">Request</h3>
<p>Each <code>XMLHttpRequest</code> object has the following
request-associated concepts:
<dfn>request method</dfn>,
<dfn>request URL</dfn>,
<dfn id="author-request-headers">author request headers</dfn>,
<dfn>request entity body</dfn>,
<dfn>synchronous flag</dfn>,
<dfn id="upload-complete-flag">upload complete flag</dfn>, and
<dfn id="upload-events-flag">upload events flag</dfn>.
<p>The <span>author request headers</span> is an initially empty list of
<span data-anolis-spec=fetch title=concept-header>headers</span>.
<p>The <span>request entity body</span> is initially null.
<p>The <span>synchronous flag</span>,
<span>upload complete flag</span>, and
<span>upload events flag</span> are initially unset.
<hr>
<p>To <dfn>terminate the request</dfn>,
<span data-anolis-spec=fetch title=concept-fetch-terminate>terminate</span> the
<span data-anolis-spec=fetch title=concept-fetch>fetch</span> algorithm operated by the
<code>XMLHttpRequest</code> object with reason <i title>fatal</i>.
<h4>The <code title>open()</code> method</h4>
<dl class=domintro>
<dt><code><var title>client</var> . <span title=dom-XMLHttpRequest-open>open</span>(<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 <span>request method</span>, <span>request URL</span>, and
<span>synchronous flag</span>.
<p>Throws a "<code data-anolis-spec=dom>SyntaxError</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 data-anolis-spec=dom>SecurityError</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 data-anolis-spec=dom>InvalidAccessError</code>"
exception if <var title>async</var> is false, the
<span data-anolis-spec=html>JavaScript global environment</span> is a
<span data-anolis-spec=html>document environment</span>, and either the
<code title=dom-XMLHttpRequest-timeout>timeout</code> attribute is not
zero, the
<code title=dom-XMLHttpRequest-withCredentials>withCredentials</code>
attribute is true, or the
<code title=dom-XMLHttpRequest-responseType>responseType</code>
attribute is not the empty string.
</dl>
<p class=warning id=sync-warning>Developers must not pass false for the
<var title>async</var> argument when the
<span data-anolis-spec=html>JavaScript global environment</span> is a
<span data-anolis-spec=html>document environment</span> as it has detrimental effects to
the end user's experience. User agents are strongly encouraged to warn about such usage in
developer tools and may experiment with
<span data-anolis-spec=dom title=concept-throw>throwing</span> a
"<code data-anolis-spec=dom>InvalidAccessError</code>" exception when it occurs so the
feature can eventually be removed from the platform.
<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>If <span title=concept-XMLHttpRequest-settings-object>settings object</span>'s
<span data-anolis-spec=html>responsible document</span> is not
<span data-anolis-spec=html>fully active</span>,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidStateError</code>" exception.
<li><p>Set <var title>base</var> to
<span title=concept-XMLHttpRequest-settings-object>settings object</span>'s
<span data-anolis-spec=html>API base URL</span>.
<li><p>If <var>method</var> does not match the <span data-anolis-spec=http>Method</span>
token production, <span data-anolis-spec=dom title=concept-throw>throw</span> a
"<code data-anolis-spec=dom>SyntaxError</code>" exception.
<li><p>If <var>method</var> is a
<span data-anolis-spec=fetch title=concept-forbidden-methods>forbidden method</span>,
<span data-anolis-spec=dom title=concept-throw>throw</span> a
"<code data-anolis-spec=dom>SecurityError</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>parsedURL</var> be the result of
<span data-anolis-spec=url title=concept-url-parser>parsing</span> <var title>url</var>
with <var title>base</var>.
<li><p>If <var title>parsedURL</var> is failure,
<span data-anolis-spec=dom title=concept-throw>throw</span> a
"<code data-anolis-spec=dom>SyntaxError</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>parsedURL</var>'s <span data-anolis-spec=url>relative flag</span> is
set, run these substeps:
<ol>
<li><p>If the <var title>username</var> argument is not null, set
<var title>parsedURL</var>'s
<span data-anolis-spec=url title=concept-url-username>username</span> to
<var>username</var>.
<li><p>If the <var title>password</var> argument is not null, set
<var title>parsedURL</var>'s
<span data-anolis-spec=url title=concept-url-password>password</span> to
<var>password</var>.
</ol>
<li><p>If <var>async</var> is false, the
<span data-anolis-spec=html>JavaScript global environment</span> is a
<span data-anolis-spec=html>document environment</span>, and either the
<code title=dom-XMLHttpRequest-timeout>timeout</code> attribute value is not zero, the
<code title=dom-XMLHttpRequest-withCredentials>withCredentials</code> attribute value is
true, or the <code title=dom-XMLHttpRequest-responseType>responseType</code> attribute
value is not the empty string,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidAccessError</code>" exception.
<li>
<p><span>Terminate the request</span>.
<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 <span>request method</span> to <var>method</var>.
<li><p>Set <span>request URL</span> to <var title>parsedURL</var>.
<li><p>Set the <span>synchronous flag</span>, if <var>async</var> is false, and unset
the <span>synchronous flag</span> otherwise.
<li><p>Set <span>author request headers</span> to the empty list.
<li><p>Unset the <span><code>send()</code> flag</span>.
<li><p>Set <span>response</span> to a
<span data-anolis-spec=fetch title=concept-network-error>network error</span>.
<li><p>Set <span>arraybuffer response entity body</span> to null.
<li><p>Set <span>blob response entity body</span> to null.
<li><p>Set <span>document response entity body</span> to null.
<li><p>Set <span>JSON response entity body</span> to null.
<li><p>Set <span>text response entity body</span> to null.
</ul>
<li>
<p>If the state is not <span title="dom-XMLHttpRequest-OPENED">OPENED</span>, run these
substeps:
<ol>
<li><p>Change the state to <span title="dom-XMLHttpRequest-OPENED">OPENED</span>.
<li><p><span data-anolis-spec=dom title=concept-event-fire>Fire an event</span> named <code title=event-xhr-readystatechange>readystatechange</code>.
</ol>
</ol>
<h4>The <code title>setRequestHeader()</code> method</h4>
<dl class=domintro>
<dt><code><var title>client</var> . <span title=dom-XMLHttpRequest-setRequestHeader>setRequestHeader</span>(<var>name</var>, <var>value</var>)</code>
<dd>
<p>Appends an <span data-anolis-spec=fetch title=concept-header>header</span> to
<span>author request headers</span>, or if <var>name</var> is already a
<span data-anolis-spec=fetch title=concept-header>header</span>'s
<span data-anolis-spec=fetch title=concept-header-name>name</span> in
<span>author request headers</span>, appends <var>value</var> to that
<span data-anolis-spec=fetch title=concept-header>header</span>'s
<span data-anolis-spec=fetch title=concept-header-value>value</span>.
<p>Throws an "<code data-anolis-spec=dom>InvalidStateError</code>"
exception if the state is not
<span title="dom-XMLHttpRequest-OPENED">OPENED</span> or if the
<span><code>send()</code> flag</span> is set.
<p>Throws a "<code data-anolis-spec=dom>SyntaxError</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">send()</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 <span title="dom-XMLHttpRequest-OPENED">OPENED</span>,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidStateError</code>" exception.
<li><p>If the <span><code>send()</code> flag</span> is set,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidStateError</code>" exception.
<li><p>If <var>name</var> does not match the
<span data-anolis-spec=http>field-name</span> production,
<span data-anolis-spec=dom title=concept-throw>throw</span> a
"<code data-anolis-spec=dom>SyntaxError</code>" exception.
<li>
<p>If <var>value</var> does not match the
<span data-anolis-spec=http>field-value</span> production,
<span data-anolis-spec=dom title=concept-throw>throw</span> a
"<code data-anolis-spec=dom>SyntaxError</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
<span data-anolis-spec=fetch title=concept-forbidden-author-header-names>forbidden author header name</span>.
<li><p>If <var>name</var> is not a
<span data-anolis-spec=fetch title=concept-header-name>name</span> of a
<span data-anolis-spec=fetch title=concept-header>header</span> in
<span>author request headers</span>, append a
<span data-anolis-spec=fetch title=concept-header>header</span> whose
<span data-anolis-spec=fetch title=concept-header-name>name</span> is
<var>name</var> and
<span data-anolis-spec=fetch title=concept-header-value>value</span> is
<var>value</var> to <span>author request headers</span>.
<li>
<p>Otherwise, append `<code>,</code>`, followed by 0x20, followed by
<var>value</var>, to the
<span data-anolis-spec=fetch title=concept-header-value>value</span> of the
<span data-anolis-spec=fetch title=concept-header>header</span> in
<span>author request headers</span> whose
<span data-anolis-spec=fetch title=concept-header-name>name</span> 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>The <code title>timeout</code> attribute</h4>
<dl class=domintro>
<dt><code><var title>client</var> . <span title="dom-XMLHttpRequest-timeout">timeout</span></code>
<dd>
<p>Can be set to a time in milliseconds. When set to a non-zero value
will cause <span data-anolis-spec=fetch title=concept-fetch>fetching</span> to
terminate after the given time has passed. When the time has passed, the request has
not yet completed, and the <span>synchronous flag</span> is unset, a
<code title=event-xhr-timeout>timeout</code> event will then be
<span title=concept-event-dispatch data-anolis-spec=dom>dispatched</span>,
or a "<code data-anolis-spec=dom>TimeoutError</code>" exception will be
<span data-anolis-spec=dom title=concept-throw>thrown</span> otherwise
(for the <code title=dom-XMLHttpRequest>send()</code> method).
<p>When set: throws an
"<code data-anolis-spec=dom>InvalidAccessError</code>" exception if
the <span>synchronous flag</span> is set and the
<span data-anolis-spec=html>JavaScript global environment</span> is a
<span data-anolis-spec=html>document environment</span>.
</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">timeout</code>
attribute must run these steps:
<ol>
<li><p>If the
<span data-anolis-spec=html>JavaScript global environment</span> is a
<span data-anolis-spec=html>document environment</span> and the
<span>synchronous flag</span> is set,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidAccessError</code>" exception.
<li><p>Set its value to the new value.
</ol>
<p class=note>This implies that the
<code title="dom-XMLHttpRequest-timeout">timeout</code> attribute can be
set while <span data-anolis-spec=fetch title=concept-fetch>fetching</span> is in
progress. If that occurs it will still be measured relative to the start
of <span data-anolis-spec=fetch title=concept-fetch>fetching</span>.
<h4>The <code title>withCredentials</code> attribute</h4>
<dl class=domintro>
<dt><code><var title>client</var> . <span title=dom-XMLHttpRequest-withCredentials>withCredentials</span></code>
<dd>
<p>True when <span>user credentials</span> 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 data-anolis-spec=dom>InvalidStateError</code>" exception if the
state is not <span title="dom-XMLHttpRequest-UNSENT">UNSENT</span> or
<span title="dom-XMLHttpRequest-OPENED">OPENED</span>, or if
the <span><code>send()</code> flag</span> is set.
<p>When set: throws an
"<code data-anolis-spec=dom>InvalidAccessError</code>" exception if
either the <span>synchronous flag</span> is set and the
<span data-anolis-spec=html>JavaScript global environment</span> is a
<span data-anolis-spec=html>document environment</span>.
</dd>
</dl>
<p>The
<dfn 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">withCredentials</code>
attribute must run these steps:
<ol>
<li><p>If the state is not <span title="dom-XMLHttpRequest-UNSENT">UNSENT</span> or
<span title="dom-XMLHttpRequest-OPENED">OPENED</span>,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidStateError</code>" exception.
<li><p>If the <span><code>send()</code> flag</span> is set,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidStateError</code>" exception.
<li><p>If the
<span data-anolis-spec=html>JavaScript global environment</span> is a
<span data-anolis-spec=html>document environment</span> and the
<span>synchronous flag</span> is set,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidAccessError</code>" exception.
<li><p>Set the <code title="dom-XMLHttpRequest-withCredentials">withCredentials</code>
attribute's value to the given value.
</ol>
<p class=note>The <code title="dom-XMLHttpRequest-withCredentials">withCredentials</code>
attribute has no effect when
<span data-anolis-spec=fetch title=concept-fetch>fetching</span>
<span data-anolis-spec=html title="same origin">same-origin</span> resources.
<h4>The <code title>upload</code> attribute</h4>
<dl class=domintro>
<dt><code><var title>client</var> . <span title=dom-XMLHttpRequest-upload>upload</span></code>
<dd><p>Returns the associated <code>XMLHttpRequestUpload</code>
object. It can be used to gather transmission information when data is
transferred to a server.
</dl>
<p>The
<dfn title="dom-XMLHttpRequest-upload"><code>upload</code></dfn>
attribute must return the associated
<code>XMLHttpRequestUpload</code> object.
<p class=note>As indicated earlier, each <code>XMLHttpRequest</code>
object has an associated <code>XMLHttpRequestUpload</code> object.
<h4>The <code title>send()</code> method</h4>
<dl class=domintro>
<dt><code><var title>client</var> . <span title=dom-XMLHttpRequest-send>send</span>([<var title>data</var> = null])</code>
<dd>
<p>Initiates the request. The optional argument provides the
<span>request entity body</span>. The argument is ignored if
<span>request method</span> is <code>GET</code> or
<code>HEAD</code>.
<p>Throws an "<code data-anolis-spec=dom>InvalidStateError</code>"
exception if the state is not
<span title="dom-XMLHttpRequest-OPENED">OPENED</span> or if the
<span><code>send()</code> flag</span> is set.
</dd>
</dl>
<p>The <dfn title="dom-XMLHttpRequest-send"><code>send(<var>data</var>)</code></dfn>
method must run these steps:
<ol>
<li><p>If the state is not <span title="dom-XMLHttpRequest-OPENED">OPENED</span>,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidStateError</code>" exception.
<li><p>If the <span><code>send()</code> flag</span> is set,
<span data-anolis-spec=dom title=concept-throw>throw</span> an
"<code data-anolis-spec=dom>InvalidStateError</code>" exception.
<li><p>If the <span>request method</span> 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
<span>request entity body</span> 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 data-anolis-spec=typedarray>ArrayBufferView</code>
<dd><p>Let the <span>request entity body</span> be the raw data
represented by <var title>data</var>.</dd>
<dt id="dom-XMLHttpRequest-send-Blob"><code data-anolis-spec=fileapi>Blob</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 data-anolis-spec=fileapi>Blob</code>'s
<code data-anolis-spec=fileapi title=dom-Blob-type>type</code> attribute.
<p>Let the <span>request entity body</span> be the raw data
represented by <var>data</var>.
</dd>
<dt id="dom-XMLHttpRequest-send-document"><span data-anolis-spec=dom title=concept-document>document</span>
<dd>
<p>Let <var>encoding</var> be "<code title>UTF-8</code>".
<p>If <var>data</var> is an <span data-anolis-spec=dom>HTML document</span>, 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 <span>request entity body</span> be <var>data</var>,
<span data-anolis-spec=domps title=concept-serialize>serialized</span>,
<span data-anolis-spec=webidl title="convert a DOMString to a sequence of Unicode characters">converted to Unicode</span>,
and <span data-anolis-spec=encoding title="utf-8 encode">utf-8 encoded</span>.
Re-throw any exception
<span data-anolis-spec=domps title=concept-serialize>serializing</span> throws.
<p class=note>If <var>data</var> cannot be
<span data-anolis-spec=domps title=concept-serialize>serialized</span>, an
"<code data-anolis-spec=dom>InvalidStateError</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 <span>request entity body</span> be <var title>data</var>,
<span data-anolis-spec=encoding title="utf-8 encode">utf-8 encoded</span>.
<dt id="dom-XMLHttpRequest-send-FormData"><code>FormData</code>
<dd>
<p>Let the <span>request entity body</span> be the result of running
the
<span data-anolis-spec=html><code>multipart/form-data</code> encoding algorithm</span>
with <var>data</var> as <var>form data set</var> and with
<span data-anolis-spec=encoding>utf-8</span> as the
explicit character encoding.
<!-- need to provide explicit character encoding because otherwise the
encoding of the document is used -->
<p>Let <var>mime type</var> be the concatenation of
"<code title>multipart/form-data;</code>",
a U+0020 SPACE character,
"<code title>boundary=</code>", and the
<span data-anolis-spec=html><code>multipart/form-data</code> boundary string</span>
generated by the
<span data-anolis-spec=html><code>multipart/form-data</code> encoding algorithm</span>.
<dt id=dom-XMLHttpRequest-send-URLSearchParams><code data-anolis-spec=url>URLSearchParams</code>
<dd>
<p>Let the <span>request entity body</span> be the result of running the
<span data-anolis-spec=url title=concept-urlencoded-serializer><code>application/x-www-form-urlencoded</code> serializer</span>
with <var>data</var>'s associated list of name-value pairs as <var>pairs</var>.
<!-- utf-8 implied -->
<p>Let <var>mime type</var> be
"<code title>application/x-www-form-urlencoded;charset=UTF-8</code>".
</dl>
<p>If a <code>Content-Type</code> header is in
<span>author request headers</span> and its value is a
<span data-anolis-spec=html>valid MIME type</span> that has a
<code>charset</code> parameter whose value is not a case-insensitive
match for <var title>encoding</var>, and <var title>encoding</var>
is not null, set all the <code>charset</code> parameters of that
<code>Content-Type</code> header to <var title>encoding</var>.
<p>If no <code>Content-Type</code> header is in
<span>author request headers</span> and <var title>mime type</var> is
not null, append a <code>Content-Type</code> header with value
<var title>mime type</var> to <span>author request headers</span>.
<!-- reminder: if we ever change this to always include charset it has
to be included as the first parameter for compatibility reasons -->
<li><p>If the <span>synchronous flag</span> is set, release the
<span data-anolis-spec=html>storage mutex</span>.
<li><p>Unset the <span>upload complete flag</span> and <span>upload events flag</span>.
<li><p>If there is no <span>request entity body</span> or if it is empty,
set the <span>upload complete flag</span>.
<li><p>If the <span>synchronous flag</span> is unset and one or more
event listeners are registered on the <code>XMLHttpRequestUpload</code>
object, set the <span>upload events flag</span>.
<li>
<p>If the <span>synchronous flag</span> is unset, run these substeps:
<ol>
<li><p>Set the <span><code>send()</code> flag</span>.
<li><p><span title=concept-event-fire-progress>Fire a progress event</span> named <code title="event-xhr-loadstart">loadstart</code>.
<li><p>If the <span>upload complete flag</span> is unset,
<span title=concept-event-fire-upload-progress>fire an upload progress event</span> named <code title="event-xhr-loadstart">loadstart</code>
on the <code>XMLHttpRequestUpload</code> object.
<li><p>Return the <code title="dom-XMLHttpRequest-send">send()</code>
method call, but continue running the steps in this algorithm.
</ol>