We make the distinction here between "load" and "decode" notifications. Load notifications are fired as the image is loaded from the network or filesystem. Decode notifications are fired as the image is decoded. If an image is decoded on load and not visibly discarded, decode notifications are nested logically inside load notifications as one might expect. However, with decode-on-draw, the set of decode notifications can come completely after the load notifications, and can come multiple times if the image is discardable. Moreover, they can be interleaved in various ways. In general, any presumed ordering between load and decode notifications should not be relied upon.

Decode notifications may or may not be synchronous, depending on the situation. If imgIDecoder::FLAG_SYNC_DECODE is passed to a function that triggers a decode, all notifications that can be generated from the currently loaded data fire before the call returns. If FLAG_SYNC_DECODE is not passed, all, some, or none of the notifications may fire before the call returns.

Method overview

Methods

Decode notification. Called when there is more to paint.

void onDataAvailable(
  in imgIRequest aRequest,
  in boolean aCurrentFrame,
  [const] in nsIntRect aRect
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

aCurrentFrame

Missing Description

aRect

Missing Description

onDiscard()

Called when the decoded image data is discarded. This means that the frames no longer exist in decoded form, and any attempt to access or draw the image will initiate a new series of progressive decode notifications.

void onDiscard(
  in imgIRequest aRequest
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

onImageIsAnimated()

Notification for when an image is known to be animated. This should be fired at the earliest possible time.

void onImageIsAnimated(
  in imgIRequest aRequest
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

onStartContainer()

This load notification is called once enough data has been loaded from the network that we were able to parse the width and height from the image. By the time this callback is been called, the size has been set on the container and STATUS_SIZE_AVAILABLE has been set on the associated imgRequest.

void onStartContainer(
  in imgIRequest aRequest,
  in imgIContainer aContainer
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

aContainer

Missing Description

onStartDecode()

This decode notification is called as soon as the image begins getting decoded. This does not include "header-only" decodes used by decode-on-draw to parse the width/height out of the image. Thus, it is a decode notification only.

void onStartDecode(
  in imgIRequest aRequest
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

onStartFrame()

This is a decode notification which is called when each frame is created.

void onStartFrame(
  in imgIRequest aRequest,
  in unsigned long aFrame
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

aFrame

Missing Description

onStartRequest()

A load notification which is called at the same time that nsIRequestObserver.onStartRequest() would be (used only for observers of imgIRequest objects, which are nsIRequests, not imgIDecoder objects).

void onStartRequest(
  in imgIRequest aRequest
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

onStopContainer()

void onStopContainer(
  in imgIRequest aRequest,
  in imgIContainer aContainer
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

aContainer

Missing Description

onStopDecode()

In theory a decode notification, but currently a load notification.

Ideally this would be called when the decode is complete. Unfortunately, this is currently the only way to signal decoding errors to consumers, and the only decoding errors that consumers care about (indeed, the only ones that they're prepared to hear about) are failures to instantiate the decoder (<img src="foo.html"> for example). Thus, currently this is just a companion to onStopRequest to signal success or failure. You probably want onStopContainer instead. This will be revisited in bug 505385. If you're thinking of doing something new with this, please talk to bholley first.

void onStopDecode(
  in imgIRequest aRequest,
  in nsresult status,
  in wstring statusArg
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

status

Missing Description

statusArg

Missing Description

onStopFrame()

A decode notification that is called when a frame is finished decoding.

void onStopFrame(
  in imgIRequest aRequest,
  in unsigned long aFrame
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

aFrame

Missing Description

onStopRequest()

A load notification that is called at the same time that nsIRequestObserver.onStopRequest() would be (used only for observers of imgIRequest objects, which are nsIRequests, not imgIDecoder objects).

void onStopRequest(
  in imgIRequest aRequest,
  in boolean aIsLastPart
);

Parameters

aRequest

The request on which data is available, or null if being called for an imgIDecoder object.

aIsLastPart

Missing Description

See also

• imgIRequest
• imgIDecoder
• imgIContainer