Obsolete
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
nsISupports
Last changed in Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)Implemented by: @mozilla.org/download-manager;1
. To get the service, use:
var downloadManager = Components.classes["@mozilla.org/download-manager;1"] .getService(Components.interfaces.nsIDownloadManager);
Method overview
|
void addListener(in |
void cancelDownload(in unsigned long aID); |
void cleanUp(); |
void endBatchUpdate(); Obsolete since Gecko 1.9.1 |
void flush(); Obsolete since Gecko 1.8 |
|
void onClose(); Obsolete since Gecko 1.9.1 |
void open(in Obsolete since Gecko 1.9.1 |
void openProgressDialogFor(in nsIDownload aDownload, in Obsolete since Gecko 1.9.1 |
void pauseDownload(in unsigned long aID); |
void removeDownload(in unsigned long aID); |
void removeDownloadsByTimeframe(in long long aBeginTime, in long long aEndTime); |
void removeListener(in nsIDownloadProgressListener aListener); |
void resumeDownload(in unsigned long aID); |
void retryDownload(in unsigned long aID); |
void saveState(); Obsolete since Gecko 1.8 |
void startBatchUpdate(); Obsolete since Gecko 1.9.1 |
Attributes
Attribute | Type | Description |
activeDownloadCount |
long |
The number of files currently being downloaded. Read only. |
activeDownloads |
|
An enumeration of active nsIDownload s. Read only. |
canCleanUp |
boolean |
Whether or not there are downloads that can be cleaned up (removed) that is downloads that have completed, have failed or have been canceled. Read only. |
datasource |
|
Read only. Obsolete since Gecko 1.8 |
DBConnection |
|
The database connection to the downloads database. Read only. |
defaultDownloadsDirectory |
|
Returns the platform default downloads directory. Read only. |
listener |
|
The Download Manager's progress listener . Obsolete since Gecko 1.8 |
userDownloadsDirectory |
|
Returns the user configured downloads directory.
The path is dependent on two user configurable prefs set in preferences:
|
Constants
Constant | Value | Description |
DOWNLOAD_NOTSTARTED |
-1 |
The download has not been started yet. |
DOWNLOAD_DOWNLOADING |
0 |
The download is in the process of being downloaded. |
DOWNLOAD_FINISHED |
1 |
Download completed including any processing of the target file. |
DOWNLOAD_FAILED |
2 |
The download failed due to error. |
DOWNLOAD_CANCELED |
3 |
The user canceled the download. |
DOWNLOAD_PAUSED |
4 |
The download is currently paused. |
DOWNLOAD_QUEUED |
5 |
The download is in the queue but is not presently downloading. |
DOWNLOAD_BLOCKED_PARENTAL |
6 |
The download has been blocked, either by parental controls or the virus scanner determining that a file is infected and cannot be cleaned. |
DOWNLOAD_SCANNING |
7 |
The download is being scanned by a virus checking utility. |
DOWNLOAD_DIRTY |
8 |
A virus was detected in the download. The target will most likely no longer exist. |
DOWNLOAD_BLOCKED_POLICY |
9 |
Windows specific: Request was blocked by zone policy settings. (see bug 416683) |
DOWNLOAD_TYPE_DOWNLOAD |
0 |
The download type used by addDownload. Is the type for a "generic file download" according to the .idl file. |
Methods
addDownload()
Creates an nsIDownload
and adds it to the list of activities being managed by the Download Manager.
nsIWebBrowserPersist
object, call this method, set the progressListener to the returned nsIDownload
object, and then call the nsIWebBrowserPersist.saveURI()
method.Note: Prior to Gecko 12.0, this was a synchronous operation; that is, once this method returned, you knew that the download was in the Download Manager's list. That is no longer the case. Adding downloads to the Download Manager is now an asynchronous operation.
nsIDownload addDownload( in short aDownloadType, in nsIURI aSource, in nsIURI aTarget, in AString aDisplayName, in nsIMIMEInfo aMIMEInfo, in PRTime aStartTime, in nsILocalFile aTempFile, in nsICancelable aCancelable, in boolean aIsPrivate );
Parameters
-
aDownloadType
-
The download type for the transfer. Should always be set to
nsIDownloadManager.DOWNLOAD_TYPE_DOWNLOAD
(that is, zero).
-
aSource
-
The source URI of the transfer. Must not be
null
. -
aTarget
-
The URI indicating where the transferred file should be stored. Must not be
null
. -
aDisplayName
- A user-readable description of the transfer. May be an empty string.
-
aMIMEInfo
- The MIME information associated with the target; this may include MIME type and helper application when appropriate. This parameter is optional.
-
aStartTime
- The time at which the download began.
-
aTempFile
-
The location of a temporary file (a file in which the received data will be stored but is not equal to the target file). The file will be moved to the location indicated by
aTarget
when the download is complete. This may benull
. -
aCancelable
-
An object that can be used to abort the download. Must not be
null
. -
aIsPrivate
- Indicates whether this download should be considered private (ie. to be removed at the end of the private browsing session, cached in non-permanent storage, etc.)
Return value
The newly created download item with the passed-in properties.
addListener()
Adds a listener
to the Download Manager.
void addListener( in nsIDownloadProgressListener aListener );
Parameters
-
aListener
-
The
nsIDownloadProgressListener
object to receive status information from the Download Manager.
cancelDownload()
Cancels the download with the specified ID if it's currently in-progress. This calls cancel(NS_BINDING_ABORTED)
on the nsICancelable
provided by the download.
void cancelDownload( in unsigned long aID );
Parameters
-
aID
- The unique ID of the download.
Exceptions thrown
-
NS_ERROR_FAILURE
- The download is not in progress.
cleanUp()
Removes completed, failed, and canceled downloads from the list.
Also notifies observers of the "download-manager-remove-download" topic with a null
subject to allow any Download Manager consumers to react to the removals.
void cleanUp();
Parameters
None.
endBatchUpdate()
Indicate that a batch update is ending.
void endBatchUpdate();
Parameters
None.
flush()
Flush the download datasource
to disk.
void flush();
Parameters
None.
getDownload()
Retrieves a download managed by the download manager. This can be one that is in progress, or one that has completed in the past and is stored in the database.
nsIDownload getDownload( in unsigned long aID );
Parameters
-
aID
- The unique ID of the download.
Return value
The download with the specified ID.
Exceptions thrown
-
NS_ERROR_NOT_AVAILABLE
- The download is not in the database.
onClose()
Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Called when the download manager front end is closed. Useful for third party managers to let us know when they've closed.
void onClose();
Parameters
None.
open()
Opens the Download Manager front end.
void open( in nsIDOMWindow aParent, in nsIDownload aDownload );
Parameters
-
aParent
- The parent, or opener, of the front end.
-
aDownload
- A download to pass to the manager window. Useful if, for example, you want the window to select a certain download.
openProgressDialogFor()
Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Opens an individual progress dialog displaying progress for the download.
void openProgressDialogFor( in nsIDownload aDownload, in nsIDOMWindow aParent, in boolean aCancelDownloadOnClose );
Parameters
-
aDownload
-
The download object to display progress for, as returned by
getDownload()
oraddDownload()
. -
aParent
- The parent, or opener, of the front end.
-
aCancelDownloadOnClose
- Whether closing the dialog should cancel the download.
pauseDownload()
Pauses the specified download.
void pauseDownload( in unsigned long aID );
Parameters
-
aID
- The unique ID of the download to pause.
Exceptions thrown
-
NS_ERROR_FAILURE
- The download is not in progress.
removeDownload()
Removes the download with the specified ID if it is not currently in progress. Whereas cancelDownload()
simply cancels the transfer while retaining information about it, removeDownload()
removes all knowledge of it.
Also notifies observers of the "download-manager-remove-download" topic with the download id as the subject to allow any Download Manager consumers to react to the removal.
void removeDownload( in unsigned long aID );
Parameters
-
aID
- The unique ID of the download.
Exceptions thrown
-
NS_ERROR_FAILURE
- The download is active.
removeDownloadsByTimeframe()
Removes all inactive downloads that were started inclusively within the specified time frame.
void removeDownloadsByTimeframe( in long long aBeginTime, in long long aEndTime );
Parameters
-
aBeginTime
- The start time to remove downloads by in microseconds.
-
aEndTime
- The end time to remove downloads by in microseconds.
removeListener()
Removes a listener from the Download Manager.
void removeListener( in nsIDownloadProgressListener aListener );
Parameters
-
aListener
-
The
nsIDownloadProgressListener
object to stop listening to the Download Manager.
resumeDownload()
Resumes the specified download.
void resumeDownload( in unsigned long aID );
Parameters
-
aID
- The unique ID of the download to resume.
Exceptions thrown
-
NS_ERROR_FAILURE
- The download is not in progress.
retryDownload()
Retries a failed download.
void retryDownload( in unsigned long aID );
Parameters
-
aID
- The unique ID of the download.
Exceptions thrown
-
NS_ERROR_FAILURE
-
If the download is not in the following states:
DOWNLOAD_CANCELED
orDOWNLOAD_FAILED
. -
NS_ERROR_NOT_AVAILALE
- If the download id is not known.
saveState()
Update the download datasource
.
void saveState();
Parameters
None.
startBatchUpdate()
Indicate that a batch update (For example mass removal) is about to start.
void startBatchUpdate();
Parameters
None.