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 |
|
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()
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 benull
. -
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 benull
. -
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 theaCurSelfProgress
andaMaxSelfProgress
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 benull
. -
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 benull
. -
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 thensIDownloadManager.Constants
. -
aDownload
- The download whose state changed.
onStatusChange()
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 benull
. -
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) { } });