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

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

See also

• nsIDownload
• nsIDownloadManagerUI
• nsIDownloadProgressListener
• The Download Manager schema