diff options
Diffstat (limited to 'toolkit/components/downloads/nsIDownloadManager.idl')
| -rw-r--r-- | toolkit/components/downloads/nsIDownloadManager.idl | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/toolkit/components/downloads/nsIDownloadManager.idl b/toolkit/components/downloads/nsIDownloadManager.idl new file mode 100644 index 000000000..d7eba8940 --- /dev/null +++ b/toolkit/components/downloads/nsIDownloadManager.idl @@ -0,0 +1,358 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +// Keeps track of ongoing downloads, in the form of nsIDownload's. + +#include "nsISupports.idl" + +interface nsIURI; +interface nsIFile; +interface nsIDownload; +interface nsICancelable; +interface nsIMIMEInfo; +interface nsIDownloadProgressListener; +interface nsISimpleEnumerator; +interface mozIStorageConnection; + +[scriptable, function, uuid(0c07ffeb-791b-49f3-ae38-2c331fd55a52)] +interface nsIDownloadManagerResult : nsISupports { + /** + * Process an asynchronous result from getDownloadByGUID. + * + * @param aStatus The result code of the operation: + * * NS_OK: an item was found. No other success values are returned. + * * NS_ERROR_NOT_AVAILABLE: no such item was found. + * * Other error values are possible, but less well-defined. + */ + void handleResult(in nsresult aStatus, in nsIDownload aDownload); +}; + +[scriptable, uuid(b29aac15-7ec4-4ab3-a53b-08f78aed3b34)] +interface nsIDownloadManager : nsISupports { + /** + * Download type for generic file download. + */ + const short DOWNLOAD_TYPE_DOWNLOAD = 0; + + /** + * Download state for uninitialized download object. + */ + const short DOWNLOAD_NOTSTARTED = -1; + + /** + * Download is currently transferring data. + */ + const short DOWNLOAD_DOWNLOADING = 0; + + /** + * Download completed including any processing of the target + * file. (completed) + */ + const short DOWNLOAD_FINISHED = 1; + + /** + * Transfer failed due to error. (completed) + */ + const short DOWNLOAD_FAILED = 2; + + /** + * Download was canceled by the user. (completed) + */ + const short DOWNLOAD_CANCELED = 3; + + /** + * Transfer was paused by the user. + */ + const short DOWNLOAD_PAUSED = 4; + + /** + * Download is active but data has not yet been received. + */ + const short DOWNLOAD_QUEUED = 5; + + /** + * Transfer request was blocked by parental controls proxies. (completed) + */ + const short DOWNLOAD_BLOCKED_PARENTAL = 6; + + /** + * Transferred download is being scanned by virus scanners. + */ + const short DOWNLOAD_SCANNING = 7; + + /** + * A virus was detected in the download. The target will most likely + * no longer exist. (completed) + */ + const short DOWNLOAD_DIRTY = 8; + + /** + * Win specific: Request was blocked by zone policy settings. + * (see bug #416683) (completed) + */ + const short DOWNLOAD_BLOCKED_POLICY = 9; + + + /** + * Creates an nsIDownload and adds it to be managed by the download manager. + * + * @param aSource The source URI of the transfer. Must not be null. + * + * @param aTarget The target URI of the transfer. Must not be null. + * + * @param aDisplayName The user-readable description of the transfer. + * Can be empty. + * + * @param aMIMEInfo The MIME info associated with the target, + * including MIME type and helper app when appropriate. + * This parameter is optional. + * + * @param startTime Time when the download started + * + * @param aTempFile The location of a temporary file; i.e. a file in which + * the received data will be stored, but which is not + * equal to the target file. (will be moved to the real + * target by the DownloadManager, when the download is + * finished). This will be null for all callers except for + * nsExternalHelperAppHandler. Addons should generally pass + * null for aTempFile. This will be moved to the real target + * by the download manager when the download is finished, + * and the action indicated by aMIMEInfo will be executed. + * + * @param aCancelable An object that can be used to abort the download. + * Must not be null. + * + * @param aIsPrivate Used to determine the privacy status of the new download. + * If true, the download is stored in a manner that leaves + * no permanent trace outside of the current private session. + * + * @return The newly created download item with the passed-in properties. + * + * @note This does not actually start a download. If you want to add and + * start a download, you need to create an nsIWebBrowserPersist, pass it + * as the aCancelable object, call this method, set the progressListener + * as the returned download object, then call saveURI. + */ + nsIDownload addDownload(in short aDownloadType, + in nsIURI aSource, + in nsIURI aTarget, + in AString aDisplayName, + in nsIMIMEInfo aMIMEInfo, + in PRTime aStartTime, + in nsIFile aTempFile, + in nsICancelable aCancelable, + in boolean aIsPrivate); + + /** + * 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. + * + * @param aID The unique ID of the download. + * @return The download with the specified ID. + * @throws NS_ERROR_NOT_AVAILABLE if the download is not in the database. + */ + nsIDownload getDownload(in unsigned long aID); + + /** + * 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. The result of this method is returned via an asynchronous callback, + * the parameter of which will be an nsIDownload object, or null if none exists + * with the provided GUID. + * + * @param aGUID The unique GUID of the download. + * @param aCallback The callback to invoke with the result of the search. + */ + void getDownloadByGUID(in ACString aGUID, in nsIDownloadManagerResult aCallback); + + /** + * 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. + * + * @param aID The unique ID of the download. + * @throws NS_ERROR_FAILURE if the download is not in-progress. + */ + void cancelDownload(in unsigned long aID); + + /** + * Removes the download with the specified id if it's not currently + * in-progress. Whereas cancelDownload simply cancels the transfer, but + * retains information about it, removeDownload removes all knowledge of it. + * + * Also notifies observers of the "download-manager-remove-download-guid" + * topic with the download guid as the subject to allow any DM consumers to + * react to the removal. + * + * Also may notify observers of the "download-manager-remove-download" topic + * with the download id as the subject, if the download removed is public + * or if global private browsing mode is in use. This notification is deprecated; + * the guid notification should be relied upon instead. + * + * @param aID The unique ID of the download. + * @throws NS_ERROR_FAILURE if the download is active. + */ + void removeDownload(in unsigned long aID); + + /** + * Removes all inactive downloads that were started inclusively within the + * specified time frame. + * + * @param aBeginTime + * The start time to remove downloads by in microseconds. + * @param aEndTime + * The end time to remove downloads by in microseconds. + */ + void removeDownloadsByTimeframe(in long long aBeginTime, + in long long aEndTime); + + /** + * Pause the specified download. + * + * @param aID The unique ID of the download. + * @throws NS_ERROR_FAILURE if the download is not in-progress. + */ + void pauseDownload(in unsigned long aID); + + /** + * Resume the specified download. + * + * @param aID The unique ID of the download. + * @throws NS_ERROR_FAILURE if the download is not in-progress. + */ + void resumeDownload(in unsigned long aID); + + /** + * Retries a failed download. + * + * @param aID The unique ID of the download. + * @throws NS_ERROR_NOT_AVAILALE if the download id is not known. + * @throws NS_ERROR_FAILURE if the download is not in the following states: + * nsIDownloadManager::DOWNLOAD_CANCELED + * nsIDownloadManager::DOWNLOAD_FAILED + */ + void retryDownload(in unsigned long aID); + + /** + * The database connection to the downloads database. + */ + readonly attribute mozIStorageConnection DBConnection; + readonly attribute mozIStorageConnection privateDBConnection; + + /** + * Whether or not there are downloads that can be cleaned up (removed) + * i.e. downloads that have completed, have failed or have been canceled. + * In global private browsing mode, this reports the status of the relevant + * private or public downloads. In per-window mode, it only reports for + * public ones. + */ + readonly attribute boolean canCleanUp; + + /** + * Whether or not there are private downloads that can be cleaned up (removed) + * i.e. downloads that have completed, have failed or have been canceled. + */ +readonly attribute boolean canCleanUpPrivate; + + /** + * Removes completed, failed, and canceled downloads from the list. + * In global private browsing mode, this operates on the relevant + * private or public downloads. In per-window mode, it only operates + * on public ones. + * + * Also notifies observers of the "download-manager-remove-download-gui" + * and "download-manager-remove-download" topics with a null subject to + * allow any DM consumers to react to the removals. + */ + void cleanUp(); + + /** + * Removes completed, failed, and canceled downloads from the list + * of private downloads. + * + * Also notifies observers of the "download-manager-remove-download-gui" + * and "download-manager-remove-download" topics with a null subject to + * allow any DM consumers to react to the removals. + */ +void cleanUpPrivate(); + + /** + * The number of files currently being downloaded. + * + * In global private browsing mode, this reports the status of the relevant + * private or public downloads. In per-window mode, it only reports public + * ones. + */ + readonly attribute long activeDownloadCount; + + /** + * The number of private files currently being downloaded. + */ + readonly attribute long activePrivateDownloadCount; + + /** + * An enumeration of active nsIDownloads + * + * In global private browsing mode, this reports the status of the relevant + * private or public downloads. In per-window mode, it only reports public + * ones. + */ + readonly attribute nsISimpleEnumerator activeDownloads; + + /** + * An enumeration of active private nsIDownloads + */ + readonly attribute nsISimpleEnumerator activePrivateDownloads; + + /** + * Adds a listener to the download manager. It is expected that this + * listener will only access downloads via their deprecated integer id attribute, + * and when global private browsing compatibility mode is disabled, this listener + * will receive no notifications for downloads marked private. + */ + void addListener(in nsIDownloadProgressListener aListener); + + /** + * Adds a listener to the download manager. This listener must be able to + * understand and use the guid attribute of downloads for all interactions + * with the download manager. + */ + void addPrivacyAwareListener(in nsIDownloadProgressListener aListener); + + /** + * Removes a listener from the download manager. + */ + void removeListener(in nsIDownloadProgressListener aListener); + + /** + * Returns the platform default downloads directory. + */ + readonly attribute nsIFile defaultDownloadsDirectory; + + /** + * Returns the user configured downloads directory. + * The path is dependent on two user configurable prefs + * set in preferences: + * + * browser.download.folderList + * Indicates the location users wish to save downloaded + * files too. + * Values: + * 0 - The desktop is the default download location. + * 1 - The system's downloads folder is the default download location. + * 2 - The default download location is elsewhere as specified in + * browser.download.dir. If invalid, userDownloadsDirectory + * will fallback on defaultDownloadsDirectory. + * + * browser.download.dir - + * A local path the user may have selected at some point + * where downloaded files are saved. The use of which is + * enabled when folderList equals 2. + */ + readonly attribute nsIFile userDownloadsDirectory; +}; + + |