nsIDownloadProgressListener

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

Attributes

Methods

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.

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.

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

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) { }
});

See also

• nsIDownloadManager
• nsIDownload
• nsIWebProgressListener