The Tor Browser / annotate

toolkit/components/downloads/nsIDownloadManager.idl@6474c204b198 (annotated)

toolkit/components/downloads/nsIDownloadManager.idl

Wed, 31 Dec 2014 06:09:35 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Wed, 31 Dec 2014 06:09:35 +0100
changeset 0
6474c204b198
permissions
-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

michael@0 1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0 2 /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0 3 * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0 5
michael@0 6 // Keeps track of ongoing downloads, in the form of nsIDownload's.
michael@0 7
michael@0 8 #include "nsISupports.idl"
michael@0 9
michael@0 10 interface nsIURI;
michael@0 11 interface nsIFile;
michael@0 12 interface nsIDownload;
michael@0 13 interface nsICancelable;
michael@0 14 interface nsIMIMEInfo;
michael@0 15 interface nsIDownloadProgressListener;
michael@0 16 interface nsISimpleEnumerator;
michael@0 17 interface mozIStorageConnection;
michael@0 18
michael@0 19 [scriptable, function, uuid(0c07ffeb-791b-49f3-ae38-2c331fd55a52)]
michael@0 20 interface nsIDownloadManagerResult : nsISupports {
michael@0 21 /**
michael@0 22 * Process an asynchronous result from getDownloadByGUID.
michael@0 23 *
michael@0 24 * @param aStatus The result code of the operation:
michael@0 25 * * NS_OK: an item was found. No other success values are returned.
michael@0 26 * * NS_ERROR_NOT_AVAILABLE: no such item was found.
michael@0 27 * * Other error values are possible, but less well-defined.
michael@0 28 */
michael@0 29 void handleResult(in nsresult aStatus, in nsIDownload aDownload);
michael@0 30 };
michael@0 31
michael@0 32 [scriptable, uuid(b29aac15-7ec4-4ab3-a53b-08f78aed3b34)]
michael@0 33 interface nsIDownloadManager : nsISupports {
michael@0 34 /**
michael@0 35 * Download type for generic file download.
michael@0 36 */
michael@0 37 const short DOWNLOAD_TYPE_DOWNLOAD = 0;
michael@0 38
michael@0 39 /**
michael@0 40 * Download state for uninitialized download object.
michael@0 41 */
michael@0 42 const short DOWNLOAD_NOTSTARTED = -1;
michael@0 43
michael@0 44 /**
michael@0 45 * Download is currently transferring data.
michael@0 46 */
michael@0 47 const short DOWNLOAD_DOWNLOADING = 0;
michael@0 48
michael@0 49 /**
michael@0 50 * Download completed including any processing of the target
michael@0 51 * file. (completed)
michael@0 52 */
michael@0 53 const short DOWNLOAD_FINISHED = 1;
michael@0 54
michael@0 55 /**
michael@0 56 * Transfer failed due to error. (completed)
michael@0 57 */
michael@0 58 const short DOWNLOAD_FAILED = 2;
michael@0 59
michael@0 60 /**
michael@0 61 * Download was canceled by the user. (completed)
michael@0 62 */
michael@0 63 const short DOWNLOAD_CANCELED = 3;
michael@0 64
michael@0 65 /**
michael@0 66 * Transfer was paused by the user.
michael@0 67 */
michael@0 68 const short DOWNLOAD_PAUSED = 4;
michael@0 69
michael@0 70 /**
michael@0 71 * Download is active but data has not yet been received.
michael@0 72 */
michael@0 73 const short DOWNLOAD_QUEUED = 5;
michael@0 74
michael@0 75 /**
michael@0 76 * Transfer request was blocked by parental controls proxies. (completed)
michael@0 77 */
michael@0 78 const short DOWNLOAD_BLOCKED_PARENTAL = 6;
michael@0 79
michael@0 80 /**
michael@0 81 * Transferred download is being scanned by virus scanners.
michael@0 82 */
michael@0 83 const short DOWNLOAD_SCANNING = 7;
michael@0 84
michael@0 85 /**
michael@0 86 * A virus was detected in the download. The target will most likely
michael@0 87 * no longer exist. (completed)
michael@0 88 */
michael@0 89 const short DOWNLOAD_DIRTY = 8;
michael@0 90
michael@0 91 /**
michael@0 92 * Win specific: Request was blocked by zone policy settings.
michael@0 93 * (see bug #416683) (completed)
michael@0 94 */
michael@0 95 const short DOWNLOAD_BLOCKED_POLICY = 9;
michael@0 96
michael@0 97
michael@0 98 /**
michael@0 99 * Creates an nsIDownload and adds it to be managed by the download manager.
michael@0 100 *
michael@0 101 * @param aSource The source URI of the transfer. Must not be null.
michael@0 102 *
michael@0 103 * @param aTarget The target URI of the transfer. Must not be null.
michael@0 104 *
michael@0 105 * @param aDisplayName The user-readable description of the transfer.
michael@0 106 * Can be empty.
michael@0 107 *
michael@0 108 * @param aMIMEInfo The MIME info associated with the target,
michael@0 109 * including MIME type and helper app when appropriate.
michael@0 110 * This parameter is optional.
michael@0 111 *
michael@0 112 * @param startTime Time when the download started
michael@0 113 *
michael@0 114 * @param aTempFile The location of a temporary file; i.e. a file in which
michael@0 115 * the received data will be stored, but which is not
michael@0 116 * equal to the target file. (will be moved to the real
michael@0 117 * target by the DownloadManager, when the download is
michael@0 118 * finished). This will be null for all callers except for
michael@0 119 * nsExternalHelperAppHandler. Addons should generally pass
michael@0 120 * null for aTempFile. This will be moved to the real target
michael@0 121 * by the download manager when the download is finished,
michael@0 122 * and the action indicated by aMIMEInfo will be executed.
michael@0 123 *
michael@0 124 * @param aCancelable An object that can be used to abort the download.
michael@0 125 * Must not be null.
michael@0 126 *
michael@0 127 * @param aIsPrivate Used to determine the privacy status of the new download.
michael@0 128 * If true, the download is stored in a manner that leaves
michael@0 129 * no permanent trace outside of the current private session.
michael@0 130 *
michael@0 131 * @return The newly created download item with the passed-in properties.
michael@0 132 *
michael@0 133 * @note This does not actually start a download. If you want to add and
michael@0 134 * start a download, you need to create an nsIWebBrowserPersist, pass it
michael@0 135 * as the aCancelable object, call this method, set the progressListener
michael@0 136 * as the returned download object, then call saveURI.
michael@0 137 */
michael@0 138 nsIDownload addDownload(in short aDownloadType,
michael@0 139 in nsIURI aSource,
michael@0 140 in nsIURI aTarget,
michael@0 141 in AString aDisplayName,
michael@0 142 in nsIMIMEInfo aMIMEInfo,
michael@0 143 in PRTime aStartTime,
michael@0 144 in nsIFile aTempFile,
michael@0 145 in nsICancelable aCancelable,
michael@0 146 in boolean aIsPrivate);
michael@0 147
michael@0 148 /**
michael@0 149 * Retrieves a download managed by the download manager. This can be one that
michael@0 150 * is in progress, or one that has completed in the past and is stored in the
michael@0 151 * database.
michael@0 152 *
michael@0 153 * @param aID The unique ID of the download.
michael@0 154 * @return The download with the specified ID.
michael@0 155 * @throws NS_ERROR_NOT_AVAILABLE if the download is not in the database.
michael@0 156 */
michael@0 157 nsIDownload getDownload(in unsigned long aID);
michael@0 158
michael@0 159 /**
michael@0 160 * Retrieves a download managed by the download manager. This can be one that
michael@0 161 * is in progress, or one that has completed in the past and is stored in the
michael@0 162 * database. The result of this method is returned via an asynchronous callback,
michael@0 163 * the parameter of which will be an nsIDownload object, or null if none exists
michael@0 164 * with the provided GUID.
michael@0 165 *
michael@0 166 * @param aGUID The unique GUID of the download.
michael@0 167 * @param aCallback The callback to invoke with the result of the search.
michael@0 168 */
michael@0 169 void getDownloadByGUID(in ACString aGUID, in nsIDownloadManagerResult aCallback);
michael@0 170
michael@0 171 /**
michael@0 172 * Cancels the download with the specified ID if it's currently in-progress.
michael@0 173 * This calls cancel(NS_BINDING_ABORTED) on the nsICancelable provided by the
michael@0 174 * download.
michael@0 175 *
michael@0 176 * @param aID The unique ID of the download.
michael@0 177 * @throws NS_ERROR_FAILURE if the download is not in-progress.
michael@0 178 */
michael@0 179 void cancelDownload(in unsigned long aID);
michael@0 180
michael@0 181 /**
michael@0 182 * Removes the download with the specified id if it's not currently
michael@0 183 * in-progress. Whereas cancelDownload simply cancels the transfer, but
michael@0 184 * retains information about it, removeDownload removes all knowledge of it.
michael@0 185 *
michael@0 186 * Also notifies observers of the "download-manager-remove-download-guid"
michael@0 187 * topic with the download guid as the subject to allow any DM consumers to
michael@0 188 * react to the removal.
michael@0 189 *
michael@0 190 * Also may notify observers of the "download-manager-remove-download" topic
michael@0 191 * with the download id as the subject, if the download removed is public
michael@0 192 * or if global private browsing mode is in use. This notification is deprecated;
michael@0 193 * the guid notification should be relied upon instead.
michael@0 194 *
michael@0 195 * @param aID The unique ID of the download.
michael@0 196 * @throws NS_ERROR_FAILURE if the download is active.
michael@0 197 */
michael@0 198 void removeDownload(in unsigned long aID);
michael@0 199
michael@0 200 /**
michael@0 201 * Removes all inactive downloads that were started inclusively within the
michael@0 202 * specified time frame.
michael@0 203 *
michael@0 204 * @param aBeginTime
michael@0 205 * The start time to remove downloads by in microseconds.
michael@0 206 * @param aEndTime
michael@0 207 * The end time to remove downloads by in microseconds.
michael@0 208 */
michael@0 209 void removeDownloadsByTimeframe(in long long aBeginTime,
michael@0 210 in long long aEndTime);
michael@0 211
michael@0 212 /**
michael@0 213 * Pause the specified download.
michael@0 214 *
michael@0 215 * @param aID The unique ID of the download.
michael@0 216 * @throws NS_ERROR_FAILURE if the download is not in-progress.
michael@0 217 */
michael@0 218 void pauseDownload(in unsigned long aID);
michael@0 219
michael@0 220 /**
michael@0 221 * Resume the specified download.
michael@0 222 *
michael@0 223 * @param aID The unique ID of the download.
michael@0 224 * @throws NS_ERROR_FAILURE if the download is not in-progress.
michael@0 225 */
michael@0 226 void resumeDownload(in unsigned long aID);
michael@0 227
michael@0 228 /**
michael@0 229 * Retries a failed download.
michael@0 230 *
michael@0 231 * @param aID The unique ID of the download.
michael@0 232 * @throws NS_ERROR_NOT_AVAILALE if the download id is not known.
michael@0 233 * @throws NS_ERROR_FAILURE if the download is not in the following states:
michael@0 234 * nsIDownloadManager::DOWNLOAD_CANCELED
michael@0 235 * nsIDownloadManager::DOWNLOAD_FAILED
michael@0 236 */
michael@0 237 void retryDownload(in unsigned long aID);
michael@0 238
michael@0 239 /**
michael@0 240 * The database connection to the downloads database.
michael@0 241 */
michael@0 242 readonly attribute mozIStorageConnection DBConnection;
michael@0 243 readonly attribute mozIStorageConnection privateDBConnection;
michael@0 244
michael@0 245 /**
michael@0 246 * Whether or not there are downloads that can be cleaned up (removed)
michael@0 247 * i.e. downloads that have completed, have failed or have been canceled.
michael@0 248 * In global private browsing mode, this reports the status of the relevant
michael@0 249 * private or public downloads. In per-window mode, it only reports for
michael@0 250 * public ones.
michael@0 251 */
michael@0 252 readonly attribute boolean canCleanUp;
michael@0 253
michael@0 254 /**
michael@0 255 * Whether or not there are private downloads that can be cleaned up (removed)
michael@0 256 * i.e. downloads that have completed, have failed or have been canceled.
michael@0 257 */
michael@0 258 readonly attribute boolean canCleanUpPrivate;
michael@0 259
michael@0 260 /**
michael@0 261 * Removes completed, failed, and canceled downloads from the list.
michael@0 262 * In global private browsing mode, this operates on the relevant
michael@0 263 * private or public downloads. In per-window mode, it only operates
michael@0 264 * on public ones.
michael@0 265 *
michael@0 266 * Also notifies observers of the "download-manager-remove-download-gui"
michael@0 267 * and "download-manager-remove-download" topics with a null subject to
michael@0 268 * allow any DM consumers to react to the removals.
michael@0 269 */
michael@0 270 void cleanUp();
michael@0 271
michael@0 272 /**
michael@0 273 * Removes completed, failed, and canceled downloads from the list
michael@0 274 * of private downloads.
michael@0 275 *
michael@0 276 * Also notifies observers of the "download-manager-remove-download-gui"
michael@0 277 * and "download-manager-remove-download" topics with a null subject to
michael@0 278 * allow any DM consumers to react to the removals.
michael@0 279 */
michael@0 280 void cleanUpPrivate();
michael@0 281
michael@0 282 /**
michael@0 283 * The number of files currently being downloaded.
michael@0 284 *
michael@0 285 * In global private browsing mode, this reports the status of the relevant
michael@0 286 * private or public downloads. In per-window mode, it only reports public
michael@0 287 * ones.
michael@0 288 */
michael@0 289 readonly attribute long activeDownloadCount;
michael@0 290
michael@0 291 /**
michael@0 292 * The number of private files currently being downloaded.
michael@0 293 */
michael@0 294 readonly attribute long activePrivateDownloadCount;
michael@0 295
michael@0 296 /**
michael@0 297 * An enumeration of active nsIDownloads
michael@0 298 *
michael@0 299 * In global private browsing mode, this reports the status of the relevant
michael@0 300 * private or public downloads. In per-window mode, it only reports public
michael@0 301 * ones.
michael@0 302 */
michael@0 303 readonly attribute nsISimpleEnumerator activeDownloads;
michael@0 304
michael@0 305 /**
michael@0 306 * An enumeration of active private nsIDownloads
michael@0 307 */
michael@0 308 readonly attribute nsISimpleEnumerator activePrivateDownloads;
michael@0 309
michael@0 310 /**
michael@0 311 * Adds a listener to the download manager. It is expected that this
michael@0 312 * listener will only access downloads via their deprecated integer id attribute,
michael@0 313 * and when global private browsing compatibility mode is disabled, this listener
michael@0 314 * will receive no notifications for downloads marked private.
michael@0 315 */
michael@0 316 void addListener(in nsIDownloadProgressListener aListener);
michael@0 317
michael@0 318 /**
michael@0 319 * Adds a listener to the download manager. This listener must be able to
michael@0 320 * understand and use the guid attribute of downloads for all interactions
michael@0 321 * with the download manager.
michael@0 322 */
michael@0 323 void addPrivacyAwareListener(in nsIDownloadProgressListener aListener);
michael@0 324
michael@0 325 /**
michael@0 326 * Removes a listener from the download manager.
michael@0 327 */
michael@0 328 void removeListener(in nsIDownloadProgressListener aListener);
michael@0 329
michael@0 330 /**
michael@0 331 * Returns the platform default downloads directory.
michael@0 332 */
michael@0 333 readonly attribute nsIFile defaultDownloadsDirectory;
michael@0 334
michael@0 335 /**
michael@0 336 * Returns the user configured downloads directory.
michael@0 337 * The path is dependent on two user configurable prefs
michael@0 338 * set in preferences:
michael@0 339 *
michael@0 340 * browser.download.folderList
michael@0 341 * Indicates the location users wish to save downloaded
michael@0 342 * files too.
michael@0 343 * Values:
michael@0 344 * 0 - The desktop is the default download location.
michael@0 345 * 1 - The system's downloads folder is the default download location.
michael@0 346 * 2 - The default download location is elsewhere as specified in
michael@0 347 * browser.download.dir. If invalid, userDownloadsDirectory
michael@0 348 * will fallback on defaultDownloadsDirectory.
michael@0 349 *
michael@0 350 * browser.download.dir -
michael@0 351 * A local path the user may have selected at some point
michael@0 352 * where downloaded files are saved. The use of which is
michael@0 353 * enabled when folderList equals 2.
michael@0 354 */
michael@0 355 readonly attribute nsIFile userDownloadsDirectory;
michael@0 356 };
michael@0 357
michael@0 358

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial