nsIDownloadManager

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.

This interface is deprecated as of Firefox 26. Please use Downloads.jsm instead.

toolkit/components/downloads/public/nsIDownloadManager.idlScriptable

This interface lets applications and extensions communicate with the Download Manager, adding and removing files to be downloaded, fetching information about downloads, and being notified when downloads are completed.

Inherits from: 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

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

void addListener(in nsIDownloadProgressListener aListener);

void cancelDownload(in unsigned long aID);

void cleanUp();

void endBatchUpdate(); Obsolete since Gecko 1.9.1

void flush(); Obsolete since Gecko 1.8

nsIDownload getDownload(in unsigned long aID);

void onClose(); Obsolete since Gecko 1.9.1

void open(in nsIDOMWindow aParent, in nsIDownload aDownload); Obsolete since Gecko 1.9.1

void openProgressDialogFor(in nsIDownload aDownload, in nsIDOMWindow aParent, in boolean aCancelDownloadOnClose); 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`	`nsISimpleEnumerator`	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`	`nsIRDFDataSource`	Read only. Obsolete since Gecko 1.8
`DBConnection`	`mozIStorageConnection`	The database connection to the downloads database. Read only.
`defaultDownloadsDirectory`	`nsILocalFile`	Returns the platform default downloads directory. Read only.
`listener`	`nsIDownloadProgressListener`	The Download Manager's progress `listener`. Obsolete since Gecko 1.8
`userDownloadsDirectory`	`nsILocalFile`	Returns the user configured downloads directory. The path is dependent on two user configurable prefs set in preferences: `browser.download.folderList` defines the default download location for files: 0: Files are downloaded to the desktop by default. 1: Files are downloaded to the system's downloads folder by default. 2: Files are downloaded to the local path specified by the `browser.download.dir` preference. If this preference is invalid, the download directory falls back to the default. Read only.

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.

Note: Adding a download doesn't automatically begin the transfer. If you want to both add and start a download, you need to create an 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 be null.
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()

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

Indicate that a batch update is ending.

void endBatchUpdate();

Parameters

None.

flush()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

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()

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

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()

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() or addDownload().
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 or DOWNLOAD_FAILED.
NS_ERROR_NOT_AVAILALE: If the download id is not known.

saveState()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Update the download datasource.

void saveState();

Parameters

None.

startBatchUpdate()

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

Indicate that a batch update (For example mass removal) is about to start.

void startBatchUpdate();

Parameters

None.

Method overview

Attributes

Constants

Methods

addDownload()

Parameters

Return value

addListener()

Parameters

cancelDownload()

Parameters

Exceptions thrown

cleanUp()

Parameters

endBatchUpdate()

Parameters

flush()

Parameters

getDownload()

Parameters

Return value

Exceptions thrown

onClose()

Parameters

open()

Parameters

openProgressDialogFor()

Parameters

pauseDownload()

Parameters

Exceptions thrown

removeDownload()

Parameters

Exceptions thrown

removeDownloadsByTimeframe()

Parameters

removeListener()

Parameters

resumeDownload()

Parameters

Exceptions thrown

retryDownload()

Parameters

Exceptions thrown

saveState()

Parameters

startBatchUpdate()

Parameters

See also