Skip to main content

Visit Mozilla.org

nsIDownloadManager

From MDC

This article covers features introduced in Firefox 3

The nsIDownloadManager 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.

Contents

nsIDownloadManager is defined in toolkit/components/downloads/public/nsIDownloadManager.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.9).

Inherits from: nsISupports

Implemented by: @mozilla.org/download-manager;1. To create an instance, use: 

var dm = Components.classes["@mozilla.org/download-manager;1"]
                   .createInstance(Components.interfaces.nsIDownloadManager);

[edit] 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)
nsIDownload getDownload(in unsigned long aID)
void cancelDownload(in unsigned long aID)
void removeDownload(in unsigned long aID)
void pauseDownload(in unsigned long aID)
void resumeDownload(in unsigned long aID)
void retryDownload(in unsigned long aID)
void cleanUp()
void addListener(in nsIDownloadProgressListener aListener)
void removeListener(in nsIDownloadProgressListener aListener)

[edit] Attributes

Attribute Type Description
DBConnection mozIStorageConnection The database connection to the downloads database. Read only.
canCleanUp boolean Whether or not there are downloads that can be cleaned up (removed) i.e. downloads that have completed, have failed or have been canceled. Read only.
activeDownloadCount long The number of files currently being downloaded. Read only.
activeDownloads nsISimpleEnumerator An enumeration of active nsIDownloads. Read only.
defaultDownloadsDirectory nsILocalFile Returns the platform default downloads directory. Read only.
userDownloadsDirectory nsILocalFile Returns the user configured downloads directory. Read only.

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.

[edit] Constants

Constant Value Description
DOWNLOAD_NOTSTARTED -1 The download hasn't been started yet.
DOWNLOAD_DOWNLOADING 0 The download is in the process of being downloaded.
DOWNLOAD_FINISHED 1 The download is complete.
DOWNLOAD_FAILED 2 The download failed.
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 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_TYPE_DOWNLOAD 0 What is this?

[edit] Methods

[edit] addDownload()

Creates an nsIDownload and adds it to be 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
)
[edit] Parameters
aDownloadType
The download type for the transfer. What is this?
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.
startTime
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.
[edit] Return value

The newly created download item with the passed-in properties.

Note: Adding a download doesn't actually 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 download object, then call the saveURI() method.

[edit] 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
)
[edit] Parameters
aID
The unique ID of the download.
[edit] Return value

The download with the specified ID.

[edit] Exceptions thrown
NS_ERROR_NOT_AVAILABLE
The download is not in the database.

[edit] 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
 )
[edit] Parameters
aID
The unique ID of the download.
[edit] Exceptions thrown
NS_ERROR_FAILURE
The download is not in progress.

[edit] removeDownload()

Removes the download with the specified ID if it's not currently in progress. Whereas cancelDownload() simply cancels the transfer while retaining information about it, removeDownload() removes all knowledge of it. 

 void removeDownload(
   in unsigned long aID
 )
[edit] Parameters
aID
The unique ID of the download.
[edit] Exceptions thrown
NS_ERROR_FAILURE
The download is active.


[edit] pauseDownload()

Pauses the specified download. 

 void pauseDownload(
   in unsigned long aID
 )
[edit] Parameters
aID
The unique ID of the download to pause.
[edit] Exceptions thrown
NS_ERROR_FAILURE
The download is not in progress.

[edit] resumeDownload()

Resumes the specified download. 

 void resumeDownload(
   in unsigned long aID
 )
[edit] Parameters
aID
The unique ID of the download to resume.
[edit] Exceptions thrown
NS_ERROR_FAILURE
The download is not in progress.

[edit] retryDownload()

Retries a failed download. 

 void retryDownload(
   in unsigned long aID
 )
[edit] Parameters
aID
The unique ID of the download.
[edit] Exceptions thrown
NS_ERROR_NOT_AVAILALE
if the download id is not known.

[edit] cleanUp()

Removes completed, failed, and canceled downloads from the list. 

 void cleanUp()
[edit] Parameters

None.

[edit] addListener()

Adds a listener to the Download Manager. 

 void addListener(
   in nsIDownloadProgressListener aListener
 )
[edit] Parameters
aListener
The nsIDownloadProgressListener object to receive status information from the Download Manager.

[edit] removeListener()

Removes a listener from the Download Manager. 

 void removeListener(
   in nsIDownloadProgressListener aListener
 )
[edit] Parameters
aListener
The nsIDownloadProgressListener object to stop listening to the Download Manager.

[edit] See also

Retrieved from "http://developer.mozilla.org/en/docs/nsIDownloadManager"