/toolkit/components/downloads/nsIDownloadProgressListener.idlScriptable
This interface gives applications and extensions a way to monitor the status of downloads being processed by the Download Manager.
Inherits from: nsISupports Last changed in Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

To use simply implement this interface in your code, then call nsIDownloadManager.addListener() to start listening.

When you no longer need to listen to the Download Manager's state, call nsIDownloadManager.removeListener() to stop listening.

As the states of downloads change, the methods described here are called by the Download Manager so your code can take whatever steps it needs to.

This interface works very similarly to the nsIWebProgress interface. It is important to note that there is no service for this listener. Rather, the developer must create an object with the methods provided below to implement it.

Method overview

void onDownloadStateChange(in short aState, in nsIDownload aDownload);
void onLocationChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in nsIURI aLocation, in nsIDownload aDownload); Obsolete since Gecko 1.9.1
void onProgressChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in long long aCurSelfProgress, in long long aMaxSelfProgress, in long long aCurTotalProgress, in long long aMaxTotalProgress, in nsIDownload aDownload);
void onSecurityChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in unsigned long aState, in nsIDownload aDownload);
void onStateChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in unsigned long aStateFlags, in nsresult aStatus, in nsIDownload aDownload);
void onStatusChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in nsresult aStatus, in wstring aMessage, in nsIDownload aDownload); Obsolete since Gecko 1.9.1

Attributes

Attribute Type Description
document nsIDOMDocument document The document of the download manager frontend.

Methods

onDownloadStateChange()

Called when the status of a particular download changes.

void onDownloadStateChange(
  in short aState,
  in nsIDownload aDownload
);
Parameters
aState
The previous state of the download. See nsIDownloadManager.Constants for a list of possible values.
aDownload
The nsIDownload object representing the file whose download status has changed. You can get the new state of the download from this object.

onLocationChange()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0) 

void onLocationChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in nsIURI aLocation,
  in nsIDownload aDownload
);
Parameters
aWebProgress
The nsIWebProgress instance used by the Download Manager to monitor downloads.
aRequest
The nsIChannel that changed state. This parameter will not be null.
aLocation
The URI of the file being downloaded.
aDownload
The nsIDownload object representing the file being downloaded.

onProgressChange()

Called when the download progress level changes for a download.

void onProgressChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in long long aCurSelfProgress,
  in long long aMaxSelfProgress,
  in long long aCurTotalProgress,
  in long long aMaxTotalProgress,
  in nsIDownload aDownload
);
Parameters
aWebProgress
The nsIWebProgress instance used by the Download Manager to monitor downloads.
aRequest
The nsIChannel that changed state. This parameter will not be null.
aCurSelfProgress
The current amount of progress that's been made on the download specified by aDownload.
aMaxSelfProgress
The value that the self progress needs to reach to indicate that the download is complete.
aCurTotalProgress
The current amount of progress that's been made on all downloads.
aMaxTotalProgress
The value that the total progress needs to reach to indicate that all downloads are complete.
aDownload
The nsIDownload object whose progress is represented by the aCurSelfProgress and aMaxSelfProgress parameters.

onSecurityChange()

Called when the level of security being used while downloading changes; for example, if the initial request is made via HTTPS but the download switches to HTTP, this function gets called to notify you of that transition.

void onSecurityChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in unsigned long aState,
  in nsIDownload aDownload
);
Parameters
aWebProgress
The nsIWebProgress instance used by the Download Manager to monitor downloads.
aRequest
The nsIChannel that changed state. This parameter will not be null.
aState
The new state of the download. See nsIDownloadManager.Constants for a list of possible values.
aDownload
The download whose security level is changing.

onStateChange()

Called when the state of a particular download changes.

void onStateChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in unsigned long aStateFlags,
  in nsresult aStatus,
  in nsIDownload aDownload
);
Parameters
aWebProgress
The nsIWebProgress instance used by the Download Manager to monitor downloads.
aRequest
The nsIChannel that changed state. This parameter will not be null.
aStateFlags
Flags indicating the download's new state. This value is a combination of one of the nsIWebProgressListener.State_Transition_Flags.
aStatus
The new state information for the download. See nsIWebProgressListener.onStateChange() for details. This can also be one of the nsIDownloadManager.Constants.
aDownload
The download whose state changed.

onStatusChange()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

Called when the status of a download request has changed. The received status message is intended to be displayed visibly to the user.

Note: If source and destination are identical, which is possible in case of file URLs or chrome URLs, this is called even in Gecko 1.9.2. In such a situation no further event handlers are called and the stop flag is set; if there are more pending downloads in such a situation not yet started they never start. In normal situations this is never called. The method even if never called must be implemented in the listener, because the WebProgress used to do the physical part of the download requires it and uses the listener instance provided to the download manager.

void onStatusChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in nsresult aStatus,
  in wstring aMessage,
  in nsIDownload aDownload
);
Parameters
aWebProgress
The nsIWebProgress instance used by the Download Manager to monitor downloads.
aRequest
The nsIRequest that changed state. This parameter will not be null.
aStatus
The new state information for the download. See nsIWebProgressListener.onStateChange() for details.
aMessage
A user-readable status message intended to be displayed visibly on the screen.
aDownload
The download whose status changed.

Example

var dm = Components.classes["@mozilla.org/download-manager;1"]
         .getService(Components.interfaces.nsIDownloadManager);

dm.addListener({
  onSecurityChange : function(prog, req, state, dl) { },
  onProgressChange : function(prog, req, prog, progMax, tProg, tProgMax, dl) { },
  onStateChange : function(prog, req, flags, status, dl) { },
  onDownloadStateChange : function(state, dl) { }
});

Even if you do not want to use some of the listeners, you must include all of them. An exception will be thrown if one of them is missing. Rather, only fill in the code for the ones you need, and leave the others blank as shown.

See also