DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (dcc6d7a0dc00)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 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;
};