XMLHttpRequest

1.Introduction

This section is non-normative.

TheXMLHttpRequestobject is an API forfetchingresources.

The nameXMLHttpRequestis historical and has no bearing on its functionality.

functionprocessData(data){
// taking care of data
}

functionhandler(){
if(this.status==200&&
this.responseXML!=null&&
this.responseXML.getElementById('test').textContent){
// success!
processData(this.responseXML.getElementById('test').textContent);
}else{
// something went wrong
…
}
}

varclient=newXMLHttpRequest();
client.onload=handler;
client.open("GET","unicorn.xml");
client.send();

functionlog(message){
varclient=newXMLHttpRequest();
client.open("POST","/log");
client.setRequestHeader("Content-Type","text/plain;charset=UTF-8");
client.send(message);
}

functionfetchStatus(address){
varclient=newXMLHttpRequest();
client.onload=function(){
// in case of network errors this might not give reliable results
returnStatus(this.status);
}
client.open("HEAD",address);
client.send();
}

1.1.Specification history

TheXMLHttpRequestobject was initially defined as part of the WHATWG’s HTML effort. (Based on Microsoft’s implementation many years prior.) It moved to the W3C in 2006. Extensions (e.g., progress events and cross-origin requests) toXMLHttpRequestwere developed in a separate draft (XMLHttpRequest Level 2) until end of 2011, at which point the two drafts were merged andXMLHttpRequestbecame a single entity again from a standards perspective. End of 2012 it moved back to the WHATWG.

Discussion that led to the current draft can be found in the following mailing list archives:

• [email protected]
• [email protected]
• [email protected]
• [email protected]

2.Terminology

This specification depends on the Infra Standard.[INFRA]

This specification uses terminology from DOM, DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, URL, Web IDL, and XML.

[DOM][DOM-PARSING][ENCODING][FETCH][FILEAPI][HTML][URL][WEBIDL][XML][XML-NAMES]

3.InterfaceXMLHttpRequest

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interfaceXMLHttpRequestEventTarget:EventTarget{
// event handlers
attributeEventHandleronloadstart;
attributeEventHandleronprogress;
attributeEventHandleronabort;
attributeEventHandleronerror;
attributeEventHandleronload;
attributeEventHandlerontimeout;
attributeEventHandleronloadend;
};

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interfaceXMLHttpRequestUpload:XMLHttpRequestEventTarget{
};

enumXMLHttpRequestResponseType{
"",
"arraybuffer",
"blob",
"document",
"json",
"text"
};

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interfaceXMLHttpRequest:XMLHttpRequestEventTarget{
constructor();

// event handler
attributeEventHandleronreadystatechange;

// states
constunsignedshortUNSENT= 0;
constunsignedshortOPENED= 1;
constunsignedshortHEADERS_RECEIVED= 2;
constunsignedshortLOADING= 3;
constunsignedshortDONE= 4;
readonlyattributeunsignedshortreadyState;

// request
undefinedopen(ByteStringmethod,USVStringurl);
undefinedopen(ByteStringmethod,USVStringurl,booleanasync,optionalUSVString?username=null,optionalUSVString?password=null);
undefinedsetRequestHeader(ByteStringname,ByteStringvalue);
attributeunsignedlongtimeout;
attributebooleanwithCredentials;
[SameObject]readonlyattributeXMLHttpRequestUploadupload;
undefinedsend(optional(DocumentorXMLHttpRequestBodyInit)?body=null);
undefinedabort();

// response
readonlyattributeUSVStringresponseURL;
readonlyattributeunsignedshortstatus;
readonlyattributeByteStringstatusText;
ByteString?getResponseHeader(ByteStringname);
ByteStringgetAllResponseHeaders();
undefinedoverrideMimeType(DOMStringmime);
attributeXMLHttpRequestResponseTyperesponseType;
readonlyattributeanyresponse;
readonlyattributeUSVStringresponseText;
[Exposed=Window]readonlyattributeDocument?responseXML;
};

AnXMLHttpRequestobject has an associated:

upload object

AnXMLHttpRequestUploadobject.

state

One ofunsent,opened,headers received,loading,anddone; initiallyunsent.

send()flag

A flag, initially unset.

timeout

An unsigned integer, initially 0.

cross-origin credentials

A boolean, initially false.

request method

Amethod.

request URL

AURL.

author request headers

Aheader list,initially empty.

request body

Initially null.

synchronous flag

A flag, initially unset.

upload complete flag

A flag, initially unset.

upload listener flag

A flag, initially unset.

timed out flag

A flag, initially unset.

response

Aresponse,initially anetwork error.

received bytes

Abyte sequence,initially the empty byte sequence.

response type

One of the empty string, "arraybuffer","blob", "document","json",and"text";initially the empty string.

response object

An object, failure, or null, initially null.

fetch controller

Afetch controller,initially a newfetch controller.Thesend()method sets it to a usefulfetch controller,but for simplicity it always holds afetch controller.

override MIME type

AMIME typeor null, initially null.Can get a value whenoverrideMimeType()is invoked.

3.1.Constructors

client= newXMLHttpRequest()

Returns a newXMLHttpRequestobject.

Thenew XMLHttpRequest()constructor steps are:

1. Setthis’supload objectto anewXMLHttpRequestUploadobject.

3.2.Garbage collection

AnXMLHttpRequestobject must not be garbage collected if itsstateis eitheropenedwith thesend()flagset,headers received,orloading,and it has one or moreevent listenersregistered whosetypeis one ofreadystatechange,progress,abort,error,load,timeout,andloadend.

If anXMLHttpRequestobject is garbage collected while its connection is still open, the user agent mustterminatetheXMLHttpRequestobject’sfetch controller.

3.3.Event handlers

The following are theevent handlers(and their correspondingevent handler event types) that must be supported on objects implementing an interface that inherits fromXMLHttpRequestEventTargetas attributes:

The following is theevent handler(and its correspondingevent handler event type) that must be supported as attribute solely by theXMLHttpRequestobject:

3.4.States

client.readyState

Returnsclient’sstate.

ThereadyStategetter steps are to return the value from the table below in the cell of the second column, from the row where the value in the cell in the first column isthis’sstate:

3.5.Request

Registering one or more event listeners on anXMLHttpRequestUploadobject will result in aCORS-preflight request.(That is because registering an event listener causes theupload listener flagto be set, which in turn causes theuse-CORS-preflight flagto be set.)

3.5.1.Theopen()method

client.open(method,url[,async= true [,username= null [,password= null]]])

Sets therequest method,request URL,andsynchronous flag.

Throws a "SyntaxError"DOMExceptionif eithermethodis not a valid method orurlcannot be parsed.

Throws a "SecurityError"DOMExceptionifmethodis a case-insensitive match for `CONNECT`, `TRACE`, or `TRACK`.

Throws an "InvalidAccessError"DOMExceptionifasyncis false, thecurrent global objectis aWindowobject, and thetimeoutattribute is not zero or theresponseTypeattribute is not the empty string.

SynchronousXMLHttpRequestoutside of workers is in the process of being removed from the web platform as it has detrimental effects to the end user’s experience. (This is a long process that takes many years.) Developers must not pass false for theasyncargument when thecurrent global objectis aWindowobject. User agents are strongly encouraged to warn about such usage in developer tools and may experiment withthrowingan "InvalidAccessError"DOMExceptionwhen it occurs.

Theopen(method,url)andopen(method,url,async,username,password)method steps are:

1. Ifthis’srelevant global objectis aWindowobject and itsassociatedDocumentis notfully active,thenthrowan "InvalidStateError"DOMException.

2. Ifmethodis not amethod,thenthrowa "SyntaxError"DOMException.

3. Ifmethodis aforbidden method,thenthrowa "SecurityError"DOMException.

4. Normalizemethod.

5. LetparsedURLbe the result ofencoding-parsing a URLurl,relative tothis’srelevant settings object.

6. IfparsedURLis failure, thenthrowa "SyntaxError"DOMException.

7. If theasyncargument is omitted, setasyncto true, and setusernameandpasswordto null.

   Unfortunately legacy content prevents treating theasyncargument beingundefinedidentical from it being omitted.

8. IfparsedURL’shostis non-null, then:

   1. If theusernameargument is not null,set the usernamegivenparsedURLandusername.

   2. If thepasswordargument is not null,set the passwordgivenparsedURLandpassword.

9. Ifasyncis false, thecurrent global objectis aWindowobject, and eitherthis’stimeoutis not 0 orthis’sresponse typeis not the empty string, thenthrowan "InvalidAccessError"DOMException.

10. Terminatethis’sfetch controller.

    Afetchcan be ongoing at this point.

11. Set variables associated with the object as follows:

    • Unsetthis’ssend()flag.

    • Unsetthis’supload listener flag.

    • Setthis’srequest methodtomethod.

    • Setthis’srequest URLtoparsedURL.

    • Setthis’ssynchronous flagifasyncis false; otherwise unsetthis’ssynchronous flag.

    • Emptythis’sauthor request headers.

    • Setthis’sresponseto anetwork error.

    • Setthis’sreceived bytesto the empty byte sequence.

    • Setthis’sresponse objectto null.

    Override MIME typeis not overridden here as theoverrideMimeType()method can be invoked before theopen()method.

12. Ifthis’sstateis notopened,then:

    1. Setthis’sstatetoopened.

    2. Fire an eventnamedreadystatechangeatthis.

The reason there are twoopen()methods defined is due to a limitation of the editing software used to write the XMLHttpRequest Standard.

3.5.2.ThesetRequestHeader()method

client.setRequestHeader(name,value)

Appends a value to an existing request header or adds a new request header.

Throws an "InvalidStateError"DOMExceptionif eitherstateis notopenedor thesend()flagis set.

Throws a "SyntaxError"DOMExceptionifnameis not a header name or ifvalueis not a header value.

ThesetRequestHeader(name,value)method must run these steps:

1. Ifthis’sstateis notopened,thenthrowan "InvalidStateError"DOMException.

2. Ifthis’ssend()flagis set, thenthrowan "InvalidStateError"DOMException.

3. Normalizevalue.

4. Ifnameis not aheader nameorvalueis not aheader value,thenthrowa "SyntaxError"DOMException.

   An empty byte sequence represents an emptyheader value.

5. If (name,value) is aforbidden request-header,then return.

6. Combine(name,value) inthis’sauthor request headers.

// The following script:
varclient=newXMLHttpRequest();
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

3.5.3.Thetimeoutgetter and setter

client.timeout

Can be set to a time in milliseconds. When set to a non-zero value will causefetchingto terminate after the given time has passed. When the time has passed, the request has not yet completed, andthis’ssynchronous flagis unset, atimeoutevent will then bedispatched,or a "TimeoutError"DOMExceptionwill bethrownotherwise (for thesend()method).

When set: throws an "InvalidAccessError"DOMExceptionif thesynchronous flagis set and thecurrent global objectis aWindowobject.

Thetimeoutgetter steps are to returnthis’stimeout.

Thetimeoutsetter steps are:

1. If thecurrent global objectis aWindowobject andthis’ssynchronous flagis set, thenthrowan "InvalidAccessError"DOMException.

2. Setthis’stimeoutto the given value.

This implies that thetimeoutattribute can be set whilefetchingis in progress. If that occurs it will still be measured relative to the start offetching.

3.5.4.ThewithCredentialsgetter and setter

client.withCredentials

True whencredentialsare 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.

When set: throws an "InvalidStateError"DOMExceptionifstateis notunsentoropened,or if thesend()flagis set.

ThewithCredentialsgetter steps are to returnthis’scross-origin credentials.

ThewithCredentialssetter steps are:

1. Ifthis’sstateis notunsentoropened,thenthrowan "InvalidStateError"DOMException.

2. Ifthis’ssend()flagis set, thenthrowan "InvalidStateError"DOMException.

3. Setthis’scross-origin credentialsto the given value.

3.5.5.Theuploadgetter

client.upload

Returns the associatedXMLHttpRequestUploadobject. It can be used to gather transmission information when data is transferred to a server.

Theuploadgetter steps are to returnthis’supload object.

3.5.6.Thesend()method

client.send([body= null])

Initiates the request. Thebodyargument provides therequest body,if any, and is ignored if therequest methodisGETorHEAD.

Throws an "InvalidStateError"DOMExceptionif eitherstateis notopenedor thesend()flagis set.

Thesend(body)method steps are:

1. Ifthis’sstateis notopened,thenthrowan "InvalidStateError"DOMException.

2. Ifthis’ssend()flagis set, thenthrowan "InvalidStateError"DOMException.

3. Ifthis’srequest methodis `GET` or `HEAD`, then setbodyto null.

4. Ifbodyis not null, then:

   1. LetextractedContentTypebe null.

   2. Ifbodyis aDocument,then setthis’srequest bodytobody,serialized,converted,andUTF-8 encoded.

   3. Otherwise:

      1. LetbodyWithTypebe the result ofsafely extractingbody.

      2. Setthis’srequest bodytobodyWithType’sbody.

      3. SetextractedContentTypetobodyWithType’stype.

   4. LetoriginalAuthorContentTypebe the result ofgetting`Content-Type` fromthis’sauthor request headers.

   5. IforiginalAuthorContentTypeis non-null, then:

      1. Ifbodyis aDocumentor aUSVString,then:

         1. LetcontentTypeRecordbe the result ofparsingoriginalAuthorContentType.

         2. IfcontentTypeRecordis not failure,contentTypeRecord’sparameters[ "charset"]exists,andparameters[ "charset"] is not anASCII case-insensitivematch for "UTF-8",then:

            1. SetcontentTypeRecord’sparameters[ "charset"] to"UTF-8".

            2. LetnewContentTypeSerializedbe the result ofserializingcontentTypeRecord.

            3. Set(`Content-Type`,newContentTypeSerialized) inthis’sauthor request headers.

   6. Otherwise:

      1. Ifbodyis anHTML document,thenset(`Content-Type`, `text/html;charset=UTF-8`) inthis’sauthor request headers.

      2. Otherwise, ifbodyis anXML document,set(`Content-Type`, `application/xml;charset=UTF-8`) inthis’sauthor request headers.

      3. Otherwise, ifextractedContentTypeis not null,set(`Content-Type`,extractedContentType) inthis’sauthor request headers.

5. If one or more event listeners are registered onthis’supload object,then setthis’supload listener flag.

6. Letreqbe a newrequest,initialized as follows:

   method

   This’srequest method.

   URL

   This’srequest URL.

   header list

   This’sauthor request headers.

   unsafe-request flag

   Set.

   body

   This’srequest body.

   client

   This’srelevant settings object.

   mode

   "cors".

   use-CORS-preflight flag

   Set ifthis’supload listener flagis set.

   credentials mode

   Ifthis’scross-origin credentialsis true, then "include"; otherwise"same-origin".

   use-URL-credentials flag

   Set ifthis’srequest URLincludes credentials.

   initiator type

   "xmlhttprequest".

7. Unsetthis’supload complete flag.

8. Unsetthis’stimed out flag.

9. Ifreq’sbodyis null, then setthis’supload complete flag.

10. Setthis’ssend()flag.

11. Ifthis’ssynchronous flagis unset, then:

    1. Fire a progress eventnamedloadstartatthiswith 0 and 0.

    2. LetrequestBodyTransmittedbe 0.

    3. LetrequestBodyLengthbereq’sbody’slength,ifreq’sbodyis non-null; otherwise 0.

    4. Assert:requestBodyLengthis an integer.

    5. Ifthis’supload complete flagis unset andthis’supload listener flagis set, thenfire a progress eventnamedloadstartatthis’supload objectwithrequestBodyTransmittedandrequestBodyLength.

    6. Ifthis’sstateis notopenedorthis’ssend()flagis unset, then return.

    7. LetprocessRequestBodyChunkLength,given abytesLength,be these steps:

       1. IncreaserequestBodyTransmittedbybytesLength.

       2. If not roughly 50ms have passed since these steps were last invoked, then return.

       3. Ifthis’supload listener flagis set, thenfire a progress eventnamedprogressatthis’supload objectwithrequestBodyTransmittedandrequestBodyLength.

       These steps are only invoked when new bytes are transmitted.

    8. LetprocessRequestEndOfBodybe these steps:

       1. Setthis’supload complete flag.

       2. Ifthis’supload listener flagis unset, then return.

       3. Fire a progress eventnamedprogressatthis’supload objectwithrequestBodyTransmittedandrequestBodyLength.

       4. Fire a progress eventnamedloadatthis’supload objectwithrequestBodyTransmittedandrequestBodyLength.

       5. Fire a progress eventnamedloadendatthis’supload objectwithrequestBodyTransmittedandrequestBodyLength.

    9. LetprocessResponse,given aresponse,be these steps:

       1. Setthis’sresponsetoresponse.

       2. Handle errorsforthis.

       3. Ifthis’sresponseis anetwork error,then return.

       4. Setthis’sstatetoheaders received.

       5. Fire an eventnamedreadystatechangeatthis.

       6. Ifthis’sstateis notheaders received,then return.

       7. Ifthis’sresponse’sbodyis null, then runhandle response end-of-bodyforthisand return.

       8. Letlengthbe the result ofextracting a lengthfromthis’sresponse’sheader list.

       9. Iflengthis not an integer, then set it to 0.

       10. LetprocessBodyChunkgivenbytesbe these steps:

           1. Appendbytestothis’sreceived bytes.

           2. If not roughly 50ms have passed since these steps were last invoked, then return.

           3. Ifthis’sstateisheaders received,then setthis’sstatetoloading.

           4. Fire an eventnamedreadystatechangeatthis.

              Web compatibility is the reasonreadystatechangefires more often thanthis’sstatechanges.

           5. Fire a progress eventnamedprogressatthiswiththis’sreceived bytes’slengthandlength.

       11. LetprocessEndOfBodybe this step: runhandle response end-of-bodyforthis.

       12. LetprocessBodyErrorbe these steps:

           1. Setthis’sresponseto anetwork error.

           2. Runhandle errorsforthis.

       13. Incrementally readthis’sresponse’sbody,givenprocessBodyChunk,processEndOfBody,processBodyError,andthis’srelevant global object.

    10. Setthis’sfetch controllerto the result offetchingreqwithprocessRequestBodyChunkLengthset toprocessRequestBodyChunkLength,processRequestEndOfBodyset toprocessRequestEndOfBody,andprocessResponseset toprocessResponse.

    11. Letnowbe the present time.

    12. Run these stepsin parallel:

        1. Wait until eitherreq’sdone flagis set orthis’stimeoutis not 0 andthis’stimeoutmilliseconds have passed sincenow.

        2. Ifreq’sdone flagis unset, then setthis’stimed out flagandterminatethis’sfetch controller.

12. Otherwise, ifthis’ssynchronous flagis set:

    1. LetprocessedResponsebe false.

    2. LetprocessResponseConsumeBody,given aresponseandnullOrFailureOrBytes,be these steps:

       1. IfnullOrFailureOrBytesis not failure, then setthis’sresponsetoresponse.

       2. IfnullOrFailureOrBytesis abyte sequence,then appendnullOrFailureOrBytestothis’sreceived bytes.

       3. SetprocessedResponseto true.

    3. Setthis’sfetch controllerto the result offetchingreqwithprocessResponseConsumeBodyset toprocessResponseConsumeBodyanduseParallelQueueset to true.

    4. Letnowbe the present time.

    5. Pauseuntil eitherprocessedResponseis true orthis’stimeoutis not 0 andthis’stimeoutmilliseconds have passed sincenow.

    6. IfprocessedResponseis false, then setthis’stimed out flagandterminatethis’sfetch controller.

    7. Report timingforthis’sfetch controllergiven thecurrent global object.

    8. Runhandle response end-of-bodyforthis.

Tohandle response end-of-bodyfor anXMLHttpRequestobjectxhr,run these steps:

1. Handle errorsforxhr.

2. Ifxhr’sresponseis anetwork error,then return.

3. Lettransmittedbexhr’sreceived bytes’slength.

4. Letlengthbe the result ofextracting a lengthfromthis’sresponse’sheader list.

5. Iflengthis not an integer, then set it to 0.

6. Ifxhr’ssynchronous flagis unset, thenfire a progress eventnamedprogressatxhrwithtransmittedandlength.

7. Setxhr’sstatetodone.

8. Unsetxhr’ssend()flag.

9. Fire an eventnamedreadystatechangeatxhr.

10. Fire a progress eventnamedloadatxhrwithtransmittedandlength.

11. Fire a progress eventnamedloadendatxhrwithtransmittedandlength.

Tohandle errorsfor anXMLHttpRequestobjectxhr,run these steps:

1. Ifxhr’ssend()flagis unset, then return.

2. Ifxhr’stimed out flagis set, then run therequest error stepsforxhr,timeout,and "TimeoutError"DOMException.

3. Otherwise, ifxhr’sresponse’saborted flagis set, run therequest error stepsforxhr,abort,and "AbortError"DOMException.

4. Otherwise, ifxhr’sresponseis anetwork error,then run therequest error stepsforxhr,error,and "NetworkError"DOMException.

Therequest error stepsfor anXMLHttpRequestobjectxhr,event,and optionallyexceptionare:

1. Setxhr’sstatetodone.

2. Unsetxhr’ssend()flag.

3. Setxhr’sresponseto anetwork error.

4. Ifxhr’ssynchronous flagis set, thenthrowexception.

5. Fire an eventnamedreadystatechangeatxhr.

   At this point it is clear thatxhr’ssynchronous flagis unset.

6. Ifxhr’supload complete flagis unset, then:

   1. Setxhr’supload complete flag.

   2. Ifxhr’supload listener flagis set, then:

      1. Fire a progress eventnamedeventatxhr’supload objectwith 0 and 0.

      2. Fire a progress eventnamedloadendatxhr’supload objectwith 0 and 0.

7. Fire a progress eventnamedeventatxhrwith 0 and 0.

8. Fire a progress eventnamedloadendatxhrwith 0 and 0.

3.5.7.Theabort()method

client.abort()

Cancels any network activity.

Theabort()method steps are:

1. Abortthis’sfetch controller.

2. Ifthis’sstateisopenedwiththis’ssend()flagset,headers received,orloading,then run therequest error stepsforthisandabort.

3. Ifthis’sstateisdone,then setthis’sstatetounsentandthis’sresponseto anetwork error.

   Noreadystatechangeevent is dispatched.

3.6.Response

3.6.1.TheresponseURLgetter

TheresponseURLgetter steps are to return the empty string ifthis’sresponse’sURLis null; otherwise itsserializationwith theexclude fragment flagset.

3.6.2.Thestatusgetter

Thestatusgetter steps are to returnthis’sresponse’sstatus.

3.6.3.ThestatusTextgetter

ThestatusTextgetter steps are to returnthis’sresponse’sstatus message.

3.6.4.ThegetResponseHeader()method

ThegetResponseHeader(name)method steps are to return the result ofgettingnamefromthis’sresponse’sheader list.

The Fetch Standard filtersthis’sresponse’sheader list.[FETCH]

varclient=newXMLHttpRequest();
client.open("GET","unicorns-are-awesome.txt",true);
client.send();
client.onreadystatechange=function(){
if(this.readyState==this.HEADERS_RECEIVED){
print(client.getResponseHeader("Content-Type"));
}
}

text/plain; charset=UTF-8

3.6.5.ThegetAllResponseHeaders()method

Abyte sequenceaislegacy-uppercased-byte less thanabyte sequencebif the following steps return true:

1. LetAbea,byte-uppercased.

2. LetBbeb,byte-uppercased.

3. ReturnAisbyte less thanB.

ThegetAllResponseHeaders()method steps are:

1. Letoutputbe an empty byte sequence.

2. LetinitialHeadersbe the result of runningsort and combinewiththis’sresponse’sheader list.

3. Letheadersbe the result ofsortinginitialHeadersin ascending order, withabeing less thanbifa’snameislegacy-uppercased-byte less thanb’sname.

   Unfortunately, this is needed for compatibility with deployed content.

4. For eachheaderinheaders,appendheader’sname,followed by a 0x3A 0x20 byte pair, followed byheader’svalue,followed by a 0x0D 0x0A byte pair, tooutput.

5. Returnoutput.

The Fetch Standard filtersthis’sresponse’sheader list.[FETCH]

varclient=newXMLHttpRequest();
client.open("GET","narwhals-too.txt",true);
client.send();
client.onreadystatechange=function(){
if(this.readyState==this.HEADERS_RECEIVED){
print(this.getAllResponseHeaders());
}
}

connection: Keep-Alive
content-type: text/plain; charset=utf-8
date: Sun, 24 Oct 2004 04:58:38 GMT
keep-alive: timeout=15, max=99
server: Apache/1.3.31 (Unix)
transfer-encoding: chunked

3.6.6.Response body

Toget a response MIME typefor anXMLHttpRequestobjectxhr,run these steps:

1. LetmimeTypebe the result ofextracting a MIME typefromxhr’sresponse’sheader list.

2. IfmimeTypeis failure, then setmimeTypetotext/xml.

3. ReturnmimeType.

Toget a final MIME typefor anXMLHttpRequestobjectxhr,run these steps:

1. Ifxhr’soverride MIME typeis null, return the result ofget a response MIME typeforxhr.

2. Returnxhr’soverride MIME type.

Toget a final encodingfor anXMLHttpRequestobjectxhr,run these steps:

1. Letlabelbe null.

2. LetresponseMIMEbe the result ofget a response MIME typeforxhr.

3. IfresponseMIME’sparameters[ "charset"]exists,then setlabelto it.

4. Ifxhr’soverride MIME type’sparameters[ "charset"]exists,then setlabelto it.

5. Iflabelis null, then return null.

6. Letencodingbe the result ofgetting an encodingfromlabel.

7. Ifencodingis failure, then return null.

8. Returnencoding.

The above steps intentionally do not use theget a final MIME typeas it would not be web compatible.

Toset a document responsefor anXMLHttpRequestobjectxhr,run these steps:

1. Ifxhr’sresponse’sbodyis null, then return.

2. LetfinalMIMEbe the result ofget a final MIME typeforxhr.

3. IffinalMIMEis not anHTML MIME typeor anXML MIME type,then return.

4. Ifxhr’sresponse typeis the empty string andfinalMIMEis anHTML MIME type,then return.

   This is restricted toxhr’sresponse typebeing "document"in order to prevent breaking legacy content.

5. IffinalMIMEis anHTML MIME type,then:

   1. Letcharsetbe the result ofget a final encodingforxhr.

   2. Ifcharsetis null,prescanthe first 1024 bytes ofxhr’sreceived bytesand if that does not terminate unsuccessfully then letcharsetbe the return value.

   3. Ifcharsetis null, then setcharsettoUTF-8.

   4. Letdocumentbe adocumentthat represents the result parsingxhr’sreceived bytesfollowing the rules set forth in the HTML Standard for an HTML parser with scripting disabled anda known definite encodingcharset.[HTML]

   5. Flagdocumentas anHTML document.

6. Otherwise, letdocumentbe adocumentthat represents the result of running theXML parserwithXML scripting support disabledonxhr’sreceived bytes.If that fails (unsupported character encoding, namespace well-formedness error, etc.), then return null.[HTML]

   Resources referenced will not be loaded and no associated XSLT will be applied.

7. Ifcharsetis null, then setcharsettoUTF-8.

8. Setdocument’sencodingtocharset.

9. Setdocument’scontent typetofinalMIME.

10. Setdocument’sURLtoxhr’sresponse’sURL.

11. Setdocument’sorigintoxhr’srelevant settings object’sorigin.

12. Setxhr’sresponse objecttodocument.

Toget a text responsefor anXMLHttpRequestobjectxhr,run these steps:

1. Ifxhr’sresponse’sbodyis null, then return the empty string.

2. Letcharsetbe the result ofget a final encodingforxhr.

3. Ifxhr’sresponse typeis the empty string,charsetis null, and the result ofget a final MIME typeforxhris anXML MIME type,then use the rules set forth in the XML specifications to determine the encoding. Letcharsetbe the determined encoding.[XML][XML-NAMES]

   This is restricted toxhr’sresponse typebeing the empty string to keep the non-legacyresponse typevalue "text"simple.

4. Ifcharsetis null, then setcharsettoUTF-8.

5. Return the result of runningdecodeonxhr’sreceived bytesusing fallback encodingcharset.

Authors are strongly encouraged to always encode their resources usingUTF-8.

3.6.7.TheoverrideMimeType()method

client.overrideMimeType(mime)

Acts as if the `Content-Type` header value for a response ismime.(It does not change the header.)

Throws an "InvalidStateError"DOMExceptionifstateisloadingordone.

TheoverrideMimeType(mime)method steps are:

1. Ifthis’sstateisloadingordone,thenthrowan "InvalidStateError"DOMException.

2. Setthis’soverride MIME typeto the result ofparsingmime.

3. Ifthis’soverride MIME typeis failure, then setthis’soverride MIME typetoapplication/octet-stream.

3.6.8.TheresponseTypegetter and setter

client.responseType[ =value]

Returns the response type.

Can be set to change the response type. Values are: the empty string (default), "arraybuffer", "blob", "document", "json",and "text".

When set: setting to "document"is ignored if thecurrent global objectis not aWindowobject.

When set: throws an "InvalidStateError"DOMExceptionifstateisloadingordone.

When set: throws an "InvalidAccessError"DOMExceptionif thesynchronous flagis set and thecurrent global objectis aWindowobject.

TheresponseTypegetter steps are to returnthis’sresponse type.

TheresponseTypesetter steps are:

1. If thecurrent global objectis not aWindowobject and the given value is "document",then return.

2. Ifthis’sstateisloadingordone,thenthrowan "InvalidStateError"DOMException.

3. If thecurrent global objectis aWindowobject andthis’ssynchronous flagis set, thenthrowan "InvalidAccessError"DOMException.

4. Setthis’sresponse typeto the given value.

3.6.9.Theresponsegetter

client.response

Returns the response body.

Theresponsegetter steps are:

1. Ifthis’sresponse typeis the empty string or "text",then:

   1. Ifthis’sstateis notloadingordone,then return the empty string.

   2. Return the result ofgetting a text responseforthis.

2. Ifthis’sstateis notdone,then return null.

3. Ifthis’sresponse objectis failure, then return null.

4. Ifthis’sresponse objectis non-null, then return it.

5. Ifthis’sresponse typeis "arraybuffer",then setthis’sresponse objectto anewArrayBufferobject representingthis’sreceived bytes.If this throws an exception, then setthis’sresponse objectto failure and return null.

   Allocating anArrayBufferobject is not guaranteed to succeed.[ECMASCRIPT]

6. Otherwise, ifthis’sresponse typeis "blob", setthis’sresponse objectto anewBlobobject representingthis’sreceived byteswithtypeset to the result ofget a final MIME typeforthis.

7. Otherwise, ifthis’sresponse typeis "document",set a document responseforthis.

8. Otherwise:

   1. Assert:this’sresponse typeis "json".

   2. Ifthis’sresponse’sbodyis null, then return null.

   3. LetjsonObjectbe the result of runningparse JSON from bytesonthis’sreceived bytes.If that threw an exception, then return null.

   4. Setthis’sresponse objecttojsonObject.

9. Returnthis’sresponse object.

3.6.10.TheresponseTextgetter

client.responseText

Returns response as text.

Throws an "InvalidStateError"DOMExceptionifresponseTypeis not the empty string or "text".

TheresponseTextgetter steps are:

1. Ifthis’sresponse typeis not the empty string or "text",thenthrowan "InvalidStateError"DOMException.

2. Ifthis’sstateis notloadingordone,then return the empty string.

3. Return the result ofgetting a text responseforthis.

3.6.11.TheresponseXMLgetter

client.responseXML

Returns the response as document.

Throws an "InvalidStateError"DOMExceptionifresponseTypeis not the empty string or "document".

TheresponseXMLgetter steps are:

1. Ifthis’sresponse typeis not the empty string or "document", thenthrowan "InvalidStateError"DOMException.

2. Ifthis’sstateis notdone,then return null.

3. Assert:this’sresponse objectis not failure.

4. Ifthis’sresponse objectis non-null, then return it.

5. Set a document responseforthis.

6. Returnthis’sresponse object.

3.7.Events summary

This section is non-normative.

The following events are dispatched onXMLHttpRequestorXMLHttpRequestUploadobjects:

4.InterfaceFormData

typedef(FileorUSVString)FormDataEntryValue;

[Exposed=(Window,Worker)]
interfaceFormData{
constructor(optionalHTMLFormElementform,optionalHTMLElement?submitter=null);

undefinedappend(USVStringname,USVStringvalue);
undefinedappend(USVStringname,BlobblobValue,optionalUSVStringfilename);
undefineddelete(USVStringname);
FormDataEntryValue?get(USVStringname);
sequence<FormDataEntryValue>getAll(USVStringname);
booleanhas(USVStringname);
undefinedset(USVStringname,USVStringvalue);
undefinedset(USVStringname,BlobblobValue,optionalUSVStringfilename);
iterable<USVString,FormDataEntryValue>;
};

EachFormDataobject has an associatedentry list(anentry list). It is initially empty.

This section used to defineentry,an entry’snameandvalue,and thecreate an entryalgorithm. These definitions have been moved to the HTML Standard.[HTML]

Thenew FormData(form,submitter)constructor steps are:

1. Ifformis given, then:

   1. Ifsubmitteris non-null, then:

      1. Ifsubmitteris not asubmit button,thenthrowaTypeError.

      2. Ifsubmitter’sform owneris notform,thenthrowa "NotFoundError"DOMException.

   2. Letlistbe the result ofconstructing the entry listforformandsubmitter.

   3. Iflistis null, thenthrowan "InvalidStateError"DOMException.

   4. Setthis’sentry listtolist.

Theappend(name,value)andappend(name,blobValue,filename)method steps are:

1. Letvaluebevalueif given; otherwiseblobValue.

2. Letentrybe the result ofcreating an entrywithname,value,andfilenameif given.

3. Appendentrytothis’sentry list.

The reason there is an argument namedvalueas well asblobValueis due to a limitation of the editing software used to write the XMLHttpRequest Standard.

Thedelete(name)method steps are toremoveallentrieswhosenameisnamefromthis’sentry list.

Theget(name)method steps are:

1. If there is noentrywhosenameisnameinthis’sentry list,then return null.

2. Return thevalueof the firstentrywhosenameisnamefromthis’sentry list.

ThegetAll(name)method steps are:

1. If there is noentrywhosenameisnameinthis’sentry list,then return the empty list.

2. Return thevaluesof allentrieswhosenameisname,in order, fromthis’sentry list.

Thehas(name)method steps are to return true if there is anentrywhosenameisnameinthis’sentry list;otherwise false.

Theset(name,value)andset(name,blobValue,filename)method steps are:

1. Letvaluebevalueif given; otherwiseblobValue.

2. Letentrybe the result ofcreating an entrywithname,value,andfilenameif given.

3. If there areentriesinthis’sentry listwhosenameisname,thenreplacethe first suchentrywithentryandremovethe others.

4. Otherwise,appendentrytothis’sentry list.

The reason there is an argument namedvalueas well asblobValueis due to a limitation of the editing software used to write the XMLHttpRequest Standard.

Thevalue pairs to iterate overarethis’sentry list’sentrieswith the key being thenameand the value being thevalue.

5.InterfaceProgressEvent

[Exposed=(Window,Worker)]
interfaceProgressEvent:Event{
constructor(DOMStringtype,optionalProgressEventIniteventInitDict= {});

readonlyattributebooleanlengthComputable;
readonlyattributeunsignedlonglongloaded;
readonlyattributeunsignedlonglongtotal;
};

dictionaryProgressEventInit:EventInit{
booleanlengthComputable=false;
unsignedlonglongloaded= 0;
unsignedlonglongtotal= 0;
};

Eventsusing theProgressEventinterface indicate some kind of progression.

ThelengthComputable,loaded,andtotalgetter steps are to return the value they were initialized to.

5.1.Firing events using theProgressEventinterface

Tofire a progress eventnamedeattarget,giventransmittedandlength,means tofire an eventnamedeattarget,usingProgressEvent,with theloadedattribute initialized totransmitted,and iflengthis not 0, with thelengthComputableattribute initialized to true and thetotalattribute initialized tolength.

5.2.Suggested names for events using theProgressEventinterface

This section is non-normative.

The suggestedtypeattribute values for use witheventsusing theProgressEventinterface are summarized in the table below. Specification editors are free to tune the details to their specific scenarios, though are strongly encouraged to discuss their usage with the WHATWG community to ensure input from people familiar with the subject.

Theerror,abort,timeout,andloadevent types are mutually exclusive.

Throughout the web platform theerror,abort,timeoutandloadevent types have theirbubblesandcancelableattributes initialized to false, so it is suggested that for consistency alleventsusing theProgressEventinterface do the same.

5.3.Security considerations

For cross-origin requests some kind of opt-in, e.g., theCORS protocoldefined in the Fetch Standard, has to be used beforeeventsusing theProgressEventinterface aredispatchedas information (e.g., size) would be revealed that cannot be obtained otherwise.[FETCH]

5.4.Example

<!DOCTYPE html>
<title>Waiting for Magical Unicorns</title>
<progressid=p></progress>
<script>
varprogressBar=document.getElementById("p"),
client=newXMLHttpRequest()
client.open("GET","magical-unicorns")
client.onprogress=function(pe){
if(pe.lengthComputable){
progressBar.max=pe.total
progressBar.value=pe.loaded
}
}
client.onloadend=function(pe){
progressBar.value=pe.loaded
}
client.send()
</script>

Acknowledgments

Thanks to Addison Phillips, Adrian Bateman, Ahmed Kamel, Alan Thomas, Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Ali Alabbas, Andrea Marchesini, Asbjørn Ulsberg, Bertrand Guay-Paquet, Björn Höhrmann, Boris Zbarsky, Caitlin Potter, Cameron McCormack, Bạch thừa hữu (Cheng-You Bai), Chris Marrin, Christophe Jolif, Charles McCathieNevile, Chirag S Kumar, Dan Winship, David Andersson, David Flanagan, David Håsäther, David Levin, Dean Jackson, Denis Sureau, Domenic Denicola, Dominik Röttsches, Doug Schepers, Douglas Livingstone, Elliott Sprehn, Elliotte Harold, Eric Lawrence, Eric Uhrhane, Erik Arvidsson, Erik Dahlström, Feras Moussa, Gideon Cohn, Glenn Adams, Gorm Haug Eriksen, Gregory Terzian, Håkon Wium Lie, Hallvord R. M. Steen, Henri Sivonen, Hiroshige Hayashizaki, Huub Schaeks, Ian Clelland, Ian Davis, Ian Hickson, Ivan Herman, Jake Archibald, Jared Jacobs, Jarred Nicholls, Jeff Walden, Jens Lindström, Jim Deegan, Jim Ley, Joe Farro, Jonas Sicking, Julian Reschke, 송정기 (Jungkee Song), Lữ khang hào (Kang-Hao Lu), Karl Dubost, Keith Yeung, Điền thôn kiện nhân (Kent TAMURA), Lachlan Hunt, Maciej Stachowiak, Magnus Kristiansen, Manish Goregaokar, Marc Hadley, Marcos Caceres, Mark Baker, Mark Birbeck, Mark Nottingham, Mark S. Miller, Martin Hassman, Mike Pennisi, Mohamed Zergaoui, Ms2ger, Noam Rosenthal, Odin Hørthe Omdal, Olli Pettay, Pawel Glowacki, Peter Michaux, Philip Jägenstedt, Philip Taylor, Rashika Jaggi, Robin Berjon, RuneF.Halvorsen, Ruud Steltenpool, Ryo Onodera, Sam Sneddon, Sergiu Dumitriu, Shivakumar Jagalur Matt, Sigbjørn Finne, Simon Pieters, Stewart Brodie, Sunava Dutta, Takeshi Kurosawa, Takeshi Yoshino, Thomas Roessler, Thomas Wisniewski, Tom Magliery, Travis Leithead, triple-underscore, Yaron Tausky, Yehuda Katz, Youenn Fablet, and Zhenbin Xu for their contributions to this standard.

Special thanks to the Microsoft employees who first implemented theXMLHttpRequestinterface, which was first widely deployed by the Windows Internet Explorer browser.

Special thanks to Ian Hickson for drafting an initial version of this specification in the HTML Standard (then Web Applications 1.0).[HTML]

Special thanks to the W3C SVG WG for drafting the originalProgressEventclass as part of theSVG Micro DOM.

This standard is written byAnne van Kesteren(Apple,[email protected]).

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under aCreative Commons Attribution 4.0 International License.To the extent portions of it are incorporated into source code, such portions in the source code are licensed under theBSD 3-Clause Licenseinstead.

This is the Living Standard. Those interested in the patent-review version should view theLiving Standard Review Draft.