nsIDownloadManager

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

Attributes

Constants

Methods

addDownload()

Creates an nsIDownload and adds it to the list of activities being managed by the Download Manager.

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.

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.

Indicate that a batch update is ending.

void endBatchUpdate();

Parameters

None.

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.

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.

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.

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.

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.

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.

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.

Update the download datasource.

void saveState();

Parameters

None.

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

void startBatchUpdate();

Parameters

None.

See also

• nsIDownload
• nsIDownloadManagerUI
• nsIDownloadProgressListener
• The Download Manager schema