mozilla
Your Search Results

    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.

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

    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.

    Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

    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.

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

    endBatchUpdate()

    Indicate that a batch update is ending.

    void endBatchUpdate();
    
    Parameters

    None.

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

    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.

    Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

    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.

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

    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.

    Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

    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.

    Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

    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.

    Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

    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.

    Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

    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.

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

    saveState()

    Update the download datasource.

    void saveState();
    
    Parameters

    None.

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

    startBatchUpdate()

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

    void startBatchUpdate();
    
    Parameters

    None.

    See also

    Document Tags and Contributors

    Last updated by: Sheppy,