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