1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/downloads/nsIDownloadManager.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,358 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +// Keeps track of ongoing downloads, in the form of nsIDownload's.
1.10 +
1.11 +#include "nsISupports.idl"
1.12 +
1.13 +interface nsIURI;
1.14 +interface nsIFile;
1.15 +interface nsIDownload;
1.16 +interface nsICancelable;
1.17 +interface nsIMIMEInfo;
1.18 +interface nsIDownloadProgressListener;
1.19 +interface nsISimpleEnumerator;
1.20 +interface mozIStorageConnection;
1.21 +
1.22 +[scriptable, function, uuid(0c07ffeb-791b-49f3-ae38-2c331fd55a52)]
1.23 +interface nsIDownloadManagerResult : nsISupports {
1.24 + /**
1.25 + * Process an asynchronous result from getDownloadByGUID.
1.26 + *
1.27 + * @param aStatus The result code of the operation:
1.28 + * * NS_OK: an item was found. No other success values are returned.
1.29 + * * NS_ERROR_NOT_AVAILABLE: no such item was found.
1.30 + * * Other error values are possible, but less well-defined.
1.31 + */
1.32 + void handleResult(in nsresult aStatus, in nsIDownload aDownload);
1.33 +};
1.34 +
1.35 +[scriptable, uuid(b29aac15-7ec4-4ab3-a53b-08f78aed3b34)]
1.36 +interface nsIDownloadManager : nsISupports {
1.37 + /**
1.38 + * Download type for generic file download.
1.39 + */
1.40 + const short DOWNLOAD_TYPE_DOWNLOAD = 0;
1.41 +
1.42 + /**
1.43 + * Download state for uninitialized download object.
1.44 + */
1.45 + const short DOWNLOAD_NOTSTARTED = -1;
1.46 +
1.47 + /**
1.48 + * Download is currently transferring data.
1.49 + */
1.50 + const short DOWNLOAD_DOWNLOADING = 0;
1.51 +
1.52 + /**
1.53 + * Download completed including any processing of the target
1.54 + * file. (completed)
1.55 + */
1.56 + const short DOWNLOAD_FINISHED = 1;
1.57 +
1.58 + /**
1.59 + * Transfer failed due to error. (completed)
1.60 + */
1.61 + const short DOWNLOAD_FAILED = 2;
1.62 +
1.63 + /**
1.64 + * Download was canceled by the user. (completed)
1.65 + */
1.66 + const short DOWNLOAD_CANCELED = 3;
1.67 +
1.68 + /**
1.69 + * Transfer was paused by the user.
1.70 + */
1.71 + const short DOWNLOAD_PAUSED = 4;
1.72 +
1.73 + /**
1.74 + * Download is active but data has not yet been received.
1.75 + */
1.76 + const short DOWNLOAD_QUEUED = 5;
1.77 +
1.78 + /**
1.79 + * Transfer request was blocked by parental controls proxies. (completed)
1.80 + */
1.81 + const short DOWNLOAD_BLOCKED_PARENTAL = 6;
1.82 +
1.83 + /**
1.84 + * Transferred download is being scanned by virus scanners.
1.85 + */
1.86 + const short DOWNLOAD_SCANNING = 7;
1.87 +
1.88 + /**
1.89 + * A virus was detected in the download. The target will most likely
1.90 + * no longer exist. (completed)
1.91 + */
1.92 + const short DOWNLOAD_DIRTY = 8;
1.93 +
1.94 + /**
1.95 + * Win specific: Request was blocked by zone policy settings.
1.96 + * (see bug #416683) (completed)
1.97 + */
1.98 + const short DOWNLOAD_BLOCKED_POLICY = 9;
1.99 +
1.100 +
1.101 + /**
1.102 + * Creates an nsIDownload and adds it to be managed by the download manager.
1.103 + *
1.104 + * @param aSource The source URI of the transfer. Must not be null.
1.105 + *
1.106 + * @param aTarget The target URI of the transfer. Must not be null.
1.107 + *
1.108 + * @param aDisplayName The user-readable description of the transfer.
1.109 + * Can be empty.
1.110 + *
1.111 + * @param aMIMEInfo The MIME info associated with the target,
1.112 + * including MIME type and helper app when appropriate.
1.113 + * This parameter is optional.
1.114 + *
1.115 + * @param startTime Time when the download started
1.116 + *
1.117 + * @param aTempFile The location of a temporary file; i.e. a file in which
1.118 + * the received data will be stored, but which is not
1.119 + * equal to the target file. (will be moved to the real
1.120 + * target by the DownloadManager, when the download is
1.121 + * finished). This will be null for all callers except for
1.122 + * nsExternalHelperAppHandler. Addons should generally pass
1.123 + * null for aTempFile. This will be moved to the real target
1.124 + * by the download manager when the download is finished,
1.125 + * and the action indicated by aMIMEInfo will be executed.
1.126 + *
1.127 + * @param aCancelable An object that can be used to abort the download.
1.128 + * Must not be null.
1.129 + *
1.130 + * @param aIsPrivate Used to determine the privacy status of the new download.
1.131 + * If true, the download is stored in a manner that leaves
1.132 + * no permanent trace outside of the current private session.
1.133 + *
1.134 + * @return The newly created download item with the passed-in properties.
1.135 + *
1.136 + * @note This does not actually start a download. If you want to add and
1.137 + * start a download, you need to create an nsIWebBrowserPersist, pass it
1.138 + * as the aCancelable object, call this method, set the progressListener
1.139 + * as the returned download object, then call saveURI.
1.140 + */
1.141 + nsIDownload addDownload(in short aDownloadType,
1.142 + in nsIURI aSource,
1.143 + in nsIURI aTarget,
1.144 + in AString aDisplayName,
1.145 + in nsIMIMEInfo aMIMEInfo,
1.146 + in PRTime aStartTime,
1.147 + in nsIFile aTempFile,
1.148 + in nsICancelable aCancelable,
1.149 + in boolean aIsPrivate);
1.150 +
1.151 + /**
1.152 + * Retrieves a download managed by the download manager. This can be one that
1.153 + * is in progress, or one that has completed in the past and is stored in the
1.154 + * database.
1.155 + *
1.156 + * @param aID The unique ID of the download.
1.157 + * @return The download with the specified ID.
1.158 + * @throws NS_ERROR_NOT_AVAILABLE if the download is not in the database.
1.159 + */
1.160 + nsIDownload getDownload(in unsigned long aID);
1.161 +
1.162 + /**
1.163 + * Retrieves a download managed by the download manager. This can be one that
1.164 + * is in progress, or one that has completed in the past and is stored in the
1.165 + * database. The result of this method is returned via an asynchronous callback,
1.166 + * the parameter of which will be an nsIDownload object, or null if none exists
1.167 + * with the provided GUID.
1.168 + *
1.169 + * @param aGUID The unique GUID of the download.
1.170 + * @param aCallback The callback to invoke with the result of the search.
1.171 + */
1.172 + void getDownloadByGUID(in ACString aGUID, in nsIDownloadManagerResult aCallback);
1.173 +
1.174 + /**
1.175 + * Cancels the download with the specified ID if it's currently in-progress.
1.176 + * This calls cancel(NS_BINDING_ABORTED) on the nsICancelable provided by the
1.177 + * download.
1.178 + *
1.179 + * @param aID The unique ID of the download.
1.180 + * @throws NS_ERROR_FAILURE if the download is not in-progress.
1.181 + */
1.182 + void cancelDownload(in unsigned long aID);
1.183 +
1.184 + /**
1.185 + * Removes the download with the specified id if it's not currently
1.186 + * in-progress. Whereas cancelDownload simply cancels the transfer, but
1.187 + * retains information about it, removeDownload removes all knowledge of it.
1.188 + *
1.189 + * Also notifies observers of the "download-manager-remove-download-guid"
1.190 + * topic with the download guid as the subject to allow any DM consumers to
1.191 + * react to the removal.
1.192 + *
1.193 + * Also may notify observers of the "download-manager-remove-download" topic
1.194 + * with the download id as the subject, if the download removed is public
1.195 + * or if global private browsing mode is in use. This notification is deprecated;
1.196 + * the guid notification should be relied upon instead.
1.197 + *
1.198 + * @param aID The unique ID of the download.
1.199 + * @throws NS_ERROR_FAILURE if the download is active.
1.200 + */
1.201 + void removeDownload(in unsigned long aID);
1.202 +
1.203 + /**
1.204 + * Removes all inactive downloads that were started inclusively within the
1.205 + * specified time frame.
1.206 + *
1.207 + * @param aBeginTime
1.208 + * The start time to remove downloads by in microseconds.
1.209 + * @param aEndTime
1.210 + * The end time to remove downloads by in microseconds.
1.211 + */
1.212 + void removeDownloadsByTimeframe(in long long aBeginTime,
1.213 + in long long aEndTime);
1.214 +
1.215 + /**
1.216 + * Pause the specified download.
1.217 + *
1.218 + * @param aID The unique ID of the download.
1.219 + * @throws NS_ERROR_FAILURE if the download is not in-progress.
1.220 + */
1.221 + void pauseDownload(in unsigned long aID);
1.222 +
1.223 + /**
1.224 + * Resume the specified download.
1.225 + *
1.226 + * @param aID The unique ID of the download.
1.227 + * @throws NS_ERROR_FAILURE if the download is not in-progress.
1.228 + */
1.229 + void resumeDownload(in unsigned long aID);
1.230 +
1.231 + /**
1.232 + * Retries a failed download.
1.233 + *
1.234 + * @param aID The unique ID of the download.
1.235 + * @throws NS_ERROR_NOT_AVAILALE if the download id is not known.
1.236 + * @throws NS_ERROR_FAILURE if the download is not in the following states:
1.237 + * nsIDownloadManager::DOWNLOAD_CANCELED
1.238 + * nsIDownloadManager::DOWNLOAD_FAILED
1.239 + */
1.240 + void retryDownload(in unsigned long aID);
1.241 +
1.242 + /**
1.243 + * The database connection to the downloads database.
1.244 + */
1.245 + readonly attribute mozIStorageConnection DBConnection;
1.246 + readonly attribute mozIStorageConnection privateDBConnection;
1.247 +
1.248 + /**
1.249 + * Whether or not there are downloads that can be cleaned up (removed)
1.250 + * i.e. downloads that have completed, have failed or have been canceled.
1.251 + * In global private browsing mode, this reports the status of the relevant
1.252 + * private or public downloads. In per-window mode, it only reports for
1.253 + * public ones.
1.254 + */
1.255 + readonly attribute boolean canCleanUp;
1.256 +
1.257 + /**
1.258 + * Whether or not there are private downloads that can be cleaned up (removed)
1.259 + * i.e. downloads that have completed, have failed or have been canceled.
1.260 + */
1.261 +readonly attribute boolean canCleanUpPrivate;
1.262 +
1.263 + /**
1.264 + * Removes completed, failed, and canceled downloads from the list.
1.265 + * In global private browsing mode, this operates on the relevant
1.266 + * private or public downloads. In per-window mode, it only operates
1.267 + * on public ones.
1.268 + *
1.269 + * Also notifies observers of the "download-manager-remove-download-gui"
1.270 + * and "download-manager-remove-download" topics with a null subject to
1.271 + * allow any DM consumers to react to the removals.
1.272 + */
1.273 + void cleanUp();
1.274 +
1.275 + /**
1.276 + * Removes completed, failed, and canceled downloads from the list
1.277 + * of private downloads.
1.278 + *
1.279 + * Also notifies observers of the "download-manager-remove-download-gui"
1.280 + * and "download-manager-remove-download" topics with a null subject to
1.281 + * allow any DM consumers to react to the removals.
1.282 + */
1.283 +void cleanUpPrivate();
1.284 +
1.285 + /**
1.286 + * The number of files currently being downloaded.
1.287 + *
1.288 + * In global private browsing mode, this reports the status of the relevant
1.289 + * private or public downloads. In per-window mode, it only reports public
1.290 + * ones.
1.291 + */
1.292 + readonly attribute long activeDownloadCount;
1.293 +
1.294 + /**
1.295 + * The number of private files currently being downloaded.
1.296 + */
1.297 + readonly attribute long activePrivateDownloadCount;
1.298 +
1.299 + /**
1.300 + * An enumeration of active nsIDownloads
1.301 + *
1.302 + * In global private browsing mode, this reports the status of the relevant
1.303 + * private or public downloads. In per-window mode, it only reports public
1.304 + * ones.
1.305 + */
1.306 + readonly attribute nsISimpleEnumerator activeDownloads;
1.307 +
1.308 + /**
1.309 + * An enumeration of active private nsIDownloads
1.310 + */
1.311 + readonly attribute nsISimpleEnumerator activePrivateDownloads;
1.312 +
1.313 + /**
1.314 + * Adds a listener to the download manager. It is expected that this
1.315 + * listener will only access downloads via their deprecated integer id attribute,
1.316 + * and when global private browsing compatibility mode is disabled, this listener
1.317 + * will receive no notifications for downloads marked private.
1.318 + */
1.319 + void addListener(in nsIDownloadProgressListener aListener);
1.320 +
1.321 + /**
1.322 + * Adds a listener to the download manager. This listener must be able to
1.323 + * understand and use the guid attribute of downloads for all interactions
1.324 + * with the download manager.
1.325 + */
1.326 + void addPrivacyAwareListener(in nsIDownloadProgressListener aListener);
1.327 +
1.328 + /**
1.329 + * Removes a listener from the download manager.
1.330 + */
1.331 + void removeListener(in nsIDownloadProgressListener aListener);
1.332 +
1.333 + /**
1.334 + * Returns the platform default downloads directory.
1.335 + */
1.336 + readonly attribute nsIFile defaultDownloadsDirectory;
1.337 +
1.338 + /**
1.339 + * Returns the user configured downloads directory.
1.340 + * The path is dependent on two user configurable prefs
1.341 + * set in preferences:
1.342 + *
1.343 + * browser.download.folderList
1.344 + * Indicates the location users wish to save downloaded
1.345 + * files too.
1.346 + * Values:
1.347 + * 0 - The desktop is the default download location.
1.348 + * 1 - The system's downloads folder is the default download location.
1.349 + * 2 - The default download location is elsewhere as specified in
1.350 + * browser.download.dir. If invalid, userDownloadsDirectory
1.351 + * will fallback on defaultDownloadsDirectory.
1.352 + *
1.353 + * browser.download.dir -
1.354 + * A local path the user may have selected at some point
1.355 + * where downloaded files are saved. The use of which is
1.356 + * enabled when folderList equals 2.
1.357 + */
1.358 + readonly attribute nsIFile userDownloadsDirectory;
1.359 +};
1.360 +
1.361 +
