Re: XMLHttpRequest progress events

OK, so I'd like to summarize where we seem to stand on progress events:

I propose we define a  WebAPIProgressEvent interface as follows:

interface WebAPIProgressEvent : events::Event {
   readonly attribute unsigned long long currentProgress;
   readonly attribute unsigned long long maxProgress;
};

Here "unsigned long long" is some type that can reasonably represent 64-bit 
integers.  In Mozilla's XPIDL this would actually be "unsigned long long", but 
I'm not sure what, if anything, it would be in the IDL being used for the spec; 
help would be appreciated here.  The names of the properties are just straw-man 
proposals; my only concern is that they NOT have the same names as either 
LSProgressEvent [1] or SVG's ProgressEvent [2], since the types are not really 
compatible with the other interfaces.  Basically, I want to be able to implement 
both WebAPIProgressEvent and LSProgressEvent on the same object, and they have 
different behavior when the numbers get large.  The name of the interface is 
also a straw-man, of course.  I welcome naming suggestions.  Both properties are 
measured in bytes.

I'm happy to either add a boolean indicating whether the maxProgress number 
makes sense (a la SVG's ProgressEvent), or to define maxProgress to be 0, or 
0xFFFFFFFFFFFFFFFF or whatever for cases when the total size is not known.

Note that I'm not happy with the proposal to just report a fraction-of-total 
number.  Far too often, this would make it impossible to report anything at all, 
whereas with two separate properties things can work ok if there is out-of-band 
size information.

With this interface in hand, I propose the following text; the parts in square 
brackets are my comments about remaining issues, etc:

--------------------------------------------------------------------------
Listeners registered for the "progress" event on the XMLHttpRequest object may
receive events implementing the WebAPIProgressEvent interface as data is 
returned from the server.  The events received, if any, must satisfy the 
following constraints:

1)  The currentProgress property values must be nondecreasing. [There's the 
question of how this should interact with multipart responses; right now in 
Gecko multiple parts of a multipart response would just continue to increment 
the currentProgress to indicate the progress made on the overall multipart data, 
while the readyState would cycle 2 -> 3 -> 4 for every part; that behavior is 
consistent with everything I say below, though we may need to filter progress 
notifications out during the 2 and 4 stages in Gecko to be fully compliant with 
my proposal.]
2)  For HTTP, the currentProgress and maxProgress property values correspond to 
the data before any content-encoding or transfer-encoding conversions are 
applied by the UA [because for something like streaming gzip decompression it's 
not possible to know the total data size up front, so reporting the number of 
compressed bytes processed out of the total number of bytes seems like a better 
bet than reporting the decompressed number out of an unknown total].  Other 
protocols may have similar situations.
3)  The events must fire while readyState has the value 3.
4)  The events must not bubble and must not be cancelable.
5)  [Maybe] A progress event indicating all progress to date must be dispatched
before readyState changes value from 3.

While the progress events must generally track changes to responseText, it is 
not defined whether new text is added to responseText before or after the 
corresponding progress event fires.  Since responseText represents data after 
content-encoding has been undone while the progress numbers refer to 
still-encoded data, there is no correlation between the actual value of 
responseText.length and the properties of any given progress event.

Apart from condition (5) above, this specification does not mandate any 
particular frequency of firing for progress events.

Listeners registered for the "uploadprogress" event on the XMLHttpRequest object 
may  receive events implementing the WebAPIProgressEvent interface as data is 
sent to the server.  The events received, if any, must satisfy the following 
constraints:

1)  The currentProgress property values must be nondecreasing.
2)  The maxProgress property must represent the total size of the request being 
sent to the server [note that this should always be known by the client for 
HTTP, since it has to send a Content-Length.  I'm not sure whether we should 
require this for other protocols...].
3)  The events must fire while readyState has the value 2.
4)  The events must not bubble and must not be cancelable
5)  [Maybe] An uploadprogress event indicating all progress to date must be 
dispatched before readyState changes value from 2.

Apart from condition (5) above, this specification does not mandate any 
particular frequency of firing for upload progress events.

--------------------------------------------------------------------------------

Thoughts?
-Boris

[1] 
http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSProgressEvent
[2] http://www.w3.org/TR/SVGMobile12/svgudom.html#events::ProgressEvent

Received on Monday, 1 May 2006 06:40:36 UTC