Microsoft invented the XMLHttpRequest, so they get to document it. Mozilla copies the Microsoft API and their documentation simply links to the Microsoft docs.
Unfortunately the Microsoft docs are lacking... (What is it about MSDN? Does it work better if you view it with IE? Trying to use it with Firefox on a Linux box is a uniformly frustrating experience. Hard to read, and even harder to navigate)
Here's what MSDN has to say about readyState values 2 and 3:
(2) LOADED: The send method has been called, but the status and headers are not yet available.
(3) INTERACTIVE: Some data has been received. Calling the responseBody and responseText properties at this state to obtain partial results will return an error, because status and response headers are not fully available.
The description of state 2 implies that the next state will be the one in which the status code and headers are avaialble. But then the documentation for state 3 just falls apart, saying that the body of the response is not available because the status and headers are not available.
This reads to me like a documentation mistake. In state 3 I would expect status and headers to be available, but I would not expect to be able to query the responseText property.
Has anyone figured out if it is okay to query the response headers in state 3? That is, is this a documentation error? Or does the documentation correctly describe an implementation error?
Update: In comments, Ian Hickson points out that the WhatWG draft spec for XMLHttpRequest addresses this precise question: in readyState 3, responseText should give us all text that has been downloaded so far, and getResponseHeader() and getResponseHeaders() should return any headers that have been downloaded so far. If we can assume that all headers will be in the first IP packet of the response, then those methods should work for readyState 3.
MSDN is slightly better in IE, but still sucks. The Incredible Re-Shrinking Left Content Pane is a prime example.
I'd assume that the documentation for code '3' is correct, and '2' is misleading.
So the INTERACTIVE status means that the request object has begun receiving an HTTP response, but you have no idea where in the response it is. So you could have the response code and the headers already, or you could have only received the first four bytes of the HTTP response string.
I guess the only real answer is to wait for '4' before doing anything with the response.
I somewhere found and copied
switch(readyState) {
case 0: ... // nothing to do
case 1: ... // no request made yet
case 2: ... // server talk established
case 3: ... // downloading
case 4: ... // success
}
The single time I tried querying headers during readyState==3 it failed. It worked when I did it in state 4. So I think the docs are correct about it.
I started out reading the documentation for Mozilla, which does point to the IE docs, but they do describe the object better on their pages than MSDN does. Check http://www.xulplanet.com/references/objref/XMLHttpRequest.html and http://kb.mozillazine.org/XMLHttpRequest.
Yes Microsoft may have invented it. But I think Mozilla did a better job implementing it and cleaning it up. I think Mozilla's version of the readyState state sequence is more useful to the developer.
They also added a few new useful properties, which they dutifully note are mozilla only. The only hole in their documentation I think is just that they don't note that the readyState property has been implemented differently... off to leave a note on XUlPlanet!
Yeah, what everyone else said. 2 means that nothing has been received yet, whereas 3 means *something* has come down the wire, but it may be as little as the first byte of the response header.
I can’t think of anything useful to do with the distinction; maybe it’s for scripts which want to manually time out requests or something. For the most part, only “state != 4”/”state == 4” are interesting.
This is in fact *not* a mistake but the context in which it is applicable is not clear at all...
Here's the basic deal (and why the Moz et al implementation is actually not quite correct): the MS version has 4 different response properties: responseStream, responseBody, responseXML and responseText. Moz et al implemented the last two, because the first two are an IStream and a byte array, respectively, and are not accessible from script--but they *are* accessible to C++ and VB code. The various readyState enumerations are only really useful in that context, and not the context of script.
So if you're using it with script, you only have access to responseText and responseXML when readyState == 4, at which point the incoming byte array is completely translated and/or parsed.
And yes, MSDN works much much better in IE; at this point, it's the only time I use the browser (outside of testing).
Guys, the readyStage messages (if they work, I haven't tried yet), will be very useful to build an operation monitor that keeps track of what is going on. This way users (like in the GUI of a control panel) will be facing a sending/loading/confirm panel.
Cheers!
Does this help?:
http://whatwg.org/specs/web-apps/current-work/#scripted-http
If it doesn't, let us know -- whatwg@whatwg.org