This document describes event types that can be used for monitoring the
progress of an operation. It is primarily intended for contexts such as data
transfer operations specified by XMLHTTPRequest [XHR], or
Media Access Events [MAE].

Status of this Document

This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current
W3C publications and the latest revision of this technical report can be
found in the W3C technical reports index
at http://www.w3.org/TR/.

This document is a W3C Working Draft specification of the ProgressEvent
events from the Web API group,
part of the Rich Web Client Activity. It defines events which can be used to
monitor a process and provide feedback to a user, particularly for
network-based events. This draft does not imply consensus of or endorsement
by the working group, and may contain minor or major errors.

This version is published as a replacement for the second W3C
Working Draft and resolves all known technical
issues from that draft. All comments are welcome and may be sent to public-webapi@w3.org. All messages
received at this address are viewable in a public archive.
Unless any issues are raised by review of this draft this specification will
hopefully be published as a Last Call Working draft in the second quarter of
2008. Currently there are no known technical issues which are unresolved by
this specification.

Publication as a Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.

Conformance

The terms must, should,
may, must not, should not,
are used in this document in accordance with [RFC2119]. A conformant implementation of this
specification meets all relevant requirements identified by the use of these
terms.

A conforming user agent implements all the requirements described for
user agents throughout this specification. A conforming user agent
should implement all the recommendations for user agents as
well.

Content

Conforming content generates and consumes progress events in
accordance with the requirements defined in this specification, and in
accordance with any additional conformance requirements defined by a
specification which describes an operation that can lead to progress
events being dispatched. (Note that content which meets the
requirements of a specification which is not conformant to this
specification may still be conforming content as defined for this
specification).

The ProgressEvent events

Event definitions

The following events are defined in this specification

Name

Description

How often?

When?

loadstart

The operation has begun

once

Must be dispatched first

progress

The operation is in progress

zero or more

May be dispatched zero or more times after a loadstart
event, before any of error, abort or load events are dispatched

error

The operation failed to complete, e.g. as a result of a network
error

never or once

Exactly one of these must be
dispatched

abort

The operation was cancelled, e.g. as a result of user
interaction

never or once

load

The operation successfuly completed

never or once

User agents must implement these events such that by default they events
do not bubble, and are not be cancelable.

User agents must ensure that these events trigger event listeners attached
on Element nodes for that event and on the capture and target
phases.

No default action is defined for these events.

These events are in the null namespace. Two kinds of
initialisation methods are provided: one in which the namespace is required
(and must be null) and one which assigns the null
namespace automatically, This specification does not recommend use of one
method over the other, and authors may choose whichever method suits them
better for any given usage.

Event firing order

The user agent must dispatch a loadstart event when a
relevant operation has begun.

The user agent may dispatch one or
more progress events while a network operation is taking
place.

If the operation fails to complete the user agent must
dispatch either an error event, if the failure to complete
was due to an error (such as a timeout, or network error), or an
abort event if the operation was deliberately cancelled
(e.g. by user interaction or through a script call).

If the Operation successfully completes, the user agent must
dispatch a load event.

In short, there must be at least one loadstart event, followed by
zero or more progress events, followed by one event which may be
any of error, abort or load, according
to the outcome of the operation.

Interface definitions

Where this specification repeats information from the DOM Level 3 Events
specification [D3E], the repeated information in this
section is informative. In the case of any conflict between the
specifications the DOM Level 3 Events specification is normative.

Specifies the number of bytes downloaded since the beginning of
the download. This refers to the content, excluding headers and
overhead from the transaction, and where there is a
content-encoding or transfer-encoding refers to the number of
bytes to be transferred, i.e. with the relevant encodings
applied. For more details on HTTP see [RFC2616].

readonlyunsigned longtotal

Specifies the expected total number of bytes of the content
transferred in the operation. Where the size of the transfer is
for some reason unknown, the value of this attribute
must be zero.

Methods

initProgressEvent

This method is used to initialize the value of a ProgressEvent
object and has the same behavior as
Event.initEventNS(), where the value of the
namespace parameter is specified as null [D3E].

Parameters

typeArg of type DOMString

This must be one of
loadstart, progress,
error, abort,
load. If it is not one of those values
then this specification does not define the resulting
event. Refer to the Event.initEvent()
method [D3E] for further
description of this parameter.

canBubbleArg of type boolean

Specifies Event.bubbles. This
parameter overrides the intrinsic bubbling behavior
of the event and determines whether the event created
will bubble

cancelableArg of type boolean

Specifies Event.cancelable. This
parameter overrides the intrinsic cancel behavior of
the event and determines whether the event created is
cancelable

lengthComputableArg of type boolean

If the user agent has reliable information about
the value of total, then this should be
true. If the user agent does not have reliable
information about the vale of total, this
should be false

loadedArg of type unsigned long

This parameter specifies the total number of bytes
already loaded. If this value is not a non-negative
number, the user agent must change it to
zero.

totalArg of type unsigned long

This specifies the total number of bytes to be
loaded. If lengthComputable is false, this
must be zero. If any other parameter is
passed, and lengthComputable is false, the user agent
must override this and set the value to
zero. If lengthComputable is true, and the
value of this parameter is not a non-negative number,
the user agent must set lengthComputable to
false and the value of total to zero.

No Return Value

No Exceptions

initProgressEventNS

This method is used to initialize the value of a namespaced
ProgressEvent object and has the same behavior as
Event.initEventNS() [D3E]. Except
as described below, parameters are the same as for initProgressEvent.

Parameters

namespaceURIArg of type DOMString

For all events defined in this specification, the
value of this parameter is null.

No Return Value

No Exceptions

Referring to progress events from other specifications

A progress event occurs when the user agent makes progress in some data
transfer operation, such as loading a resource from the web via
XMLHttpRequest [XHR]. Specifications which have a use case
for these events should define when Progress events are
dispatched.

Either by reference or by direct inclusion, specifications must maintain
the requirements for and definition of the events as described in the section
The ProgressEvent events

Example 1: Using progress events in another
specification:

This example is informative and does not necessarily illustrate best
practice.

FooAPI has a sendAndRetrieve() method, which sends some
content via a predefined SMTP server and retrieves some other content via
HTTP HEAD from a URI given as a parameter. It specifies two event targets
send and receive. Progress events as specified in
the ProgressEvent events specification may be dispatched on these targets for
the send and receive phases respectively. If any progress events are
dispatched, then at least one loadstart event, and one of
error, abort, or load must be
dispatched on each target. For the send phase, the total
attribute of the progress events measures the size of the RFC822 message
body. For the receive phase, the total attribute specifies the size of the
content to be returned in the HTTP HEAD operation.

Using progress events in Web content

Scripts may use progress events in order to provide feedback on operations
performed by an application.

Example 2: Using progress event an SVG
document.

In this example, the application uses the information in progress events
emitted as an image loads in order to fill a progress bar as it receives
progress events. Where the size of a download is unknown or there has been no
progress yet there is simply a block moving back and forth within the
progress bar to indicate that there is still some kind of activity.

Resolved ISSUE-108 and ISSUE-113 Specifications must describe
what values are issued in a progress event themselves. The event
simply describes traffic in any one direction, and specifications
using it must describe what the progress measures.

Acknowledgements

The editor would like to thank the SVG working group for producing the
draft [SVGD] that this was initially based on. The
WHATWG's proposed progress element [WPE] and
the documentation for Internet Explorer's onProgress
implementation [IEoP] were also useful as initial
reference material for this specification. In addition, the following
individuals' comments have been invaluable in preparing this draft: