The Tor Browser: toolkit/components/jsdownloads/src/DownloadCore.jsm@b8a032363ba2 (annotated)

toolkit/components/jsdownloads/src/DownloadCore.jsm@b8a032363ba2 (annotated)

toolkit/components/jsdownloads/src/DownloadCore.jsm

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* vim: set ts=2 et sw=2 tw=80 filetype=javascript: */
 /* 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/. */
 /**
  * This file includes the following constructors and global objects:
  *
  * Download
  * Represents a single download, with associated state and actions.  This object
  * is transient, though it can be included in a DownloadList so that it can be
  * managed by the user interface and persisted across sessions.
  *
  * DownloadSource
  * Represents the source of a download, for example a document or an URI.
  *
  * DownloadTarget
  * Represents the target of a download, for example a file in the global
  * downloads directory, or a file in the system temporary directory.
  *
  * DownloadError
  * Provides detailed information about a download failure.
  *
  * DownloadSaver
  * Template for an object that actually transfers the data for the download.
  *
  * DownloadCopySaver
  * Saver object that simply copies the entire source file to the target.
  *
  * DownloadLegacySaver
  * Saver object that integrates with the legacy nsITransfer interface.
  */
 "use strict";
 this.EXPORTED_SYMBOLS = [
   "Download",
   "DownloadSource",
   "DownloadTarget",
   "DownloadError",
   "DownloadSaver",
   "DownloadCopySaver",
   "DownloadLegacySaver",
 ];
 ////////////////////////////////////////////////////////////////////////////////
 //// Globals
 const Cc = Components.classes;
 const Ci = Components.interfaces;
 const Cu = Components.utils;
 const Cr = Components.results;
 Cu.import("resource://gre/modules/XPCOMUtils.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "DownloadIntegration",
                                   "resource://gre/modules/DownloadIntegration.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "FileUtils",
                                   "resource://gre/modules/FileUtils.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "NetUtil",
                                   "resource://gre/modules/NetUtil.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "OS",
                                   "resource://gre/modules/osfile.jsm")
 XPCOMUtils.defineLazyModuleGetter(this, "Promise",
                                   "resource://gre/modules/Promise.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Services",
                                   "resource://gre/modules/Services.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Task",
                                   "resource://gre/modules/Task.jsm");
 XPCOMUtils.defineLazyServiceGetter(this, "gDownloadHistory",
            "@mozilla.org/browser/download-history;1",
            Ci.nsIDownloadHistory);
 XPCOMUtils.defineLazyServiceGetter(this, "gExternalAppLauncher",
            "@mozilla.org/uriloader/external-helper-app-service;1",
            Ci.nsPIExternalAppLauncher);
 XPCOMUtils.defineLazyServiceGetter(this, "gExternalHelperAppService",
            "@mozilla.org/uriloader/external-helper-app-service;1",
            Ci.nsIExternalHelperAppService);
 const BackgroundFileSaverStreamListener = Components.Constructor(
       "@mozilla.org/network/background-file-saver;1?mode=streamlistener",
       "nsIBackgroundFileSaver");
 /**
  * Returns true if the given value is a primitive string or a String object.
  */
 function isString(aValue) {
   // We cannot use the "instanceof" operator reliably across module boundaries.
   return (typeof aValue == "string") ||
          (typeof aValue == "object" && "charAt" in aValue);
 }
 /**
  * Serialize the unknown properties of aObject into aSerializable.
  */
 function serializeUnknownProperties(aObject, aSerializable)
 {
   if (aObject._unknownProperties) {
     for (let property in aObject._unknownProperties) {
       aSerializable[property] = aObject._unknownProperties[property];
     }
   }
 }
 /**
  * Check for any unknown properties in aSerializable and preserve those in the
  * _unknownProperties field of aObject. aFilterFn is called for each property
  * name of aObject and should return true only for unknown properties.
  */
 function deserializeUnknownProperties(aObject, aSerializable, aFilterFn)
 {
   for (let property in aSerializable) {
     if (aFilterFn(property)) {
       if (!aObject._unknownProperties) {
         aObject._unknownProperties = { };
       }
       aObject._unknownProperties[property] = aSerializable[property];
     }
   }
 }
 /**
  * This determines the minimum time interval between updates to the number of
  * bytes transferred, and is a limiting factor to the sequence of readings used
  * in calculating the speed of the download.
  */
 const kProgressUpdateIntervalMs = 400;
 ////////////////////////////////////////////////////////////////////////////////
 //// Download
 /**
  * Represents a single download, with associated state and actions.  This object
  * is transient, though it can be included in a DownloadList so that it can be
  * managed by the user interface and persisted across sessions.
  */
 this.Download = function ()
 {
   this._deferSucceeded = Promise.defer();
 }
 this.Download.prototype = {
   /**
    * DownloadSource object associated with this download.
    */
   source: null,
   /**
    * DownloadTarget object associated with this download.
    */
   target: null,
   /**
    * DownloadSaver object associated with this download.
    */
   saver: null,
   /**
    * Indicates that the download never started, has been completed successfully,
    * failed, or has been canceled.  This property becomes false when a download
    * is started for the first time, or when a failed or canceled download is
    * restarted.
    */
   stopped: true,
   /**
    * Indicates that the download has been completed successfully.
    */
   succeeded: false,
   /**
    * Indicates that the download has been canceled.  This property can become
    * true, then it can be reset to false when a canceled download is restarted.
    *
    * This property becomes true as soon as the "cancel" method is called, though
    * the "stopped" property might remain false until the cancellation request
    * has been processed.  Temporary files or part files may still exist even if
    * they are expected to be deleted, until the "stopped" property becomes true.
    */
   canceled: false,
   /**
    * When the download fails, this is set to a DownloadError instance indicating
    * the cause of the failure.  If the download has been completed successfully
    * or has been canceled, this property is null.  This property is reset to
    * null when a failed download is restarted.
    */
   error: null,
   /**
    * Indicates the start time of the download.  When the download starts,
    * this property is set to a valid Date object.  The default value is null
    * before the download starts.
    */
   startTime: null,
   /**
    * Indicates whether this download's "progress" property is able to report
    * partial progress while the download proceeds, and whether the value in
    * totalBytes is relevant.  This depends on the saver and the download source.
    */
   hasProgress: false,
   /**
    * Progress percent, from 0 to 100.  Intermediate values are reported only if
    * hasProgress is true.
    *
    * @note You shouldn't rely on this property being equal to 100 to determine
    *       whether the download is completed.  You should use the individual
    *       state properties instead.
    */
   progress: 0,
   /**
    * When hasProgress is true, indicates the total number of bytes to be
    * transferred before the download finishes, that can be zero for empty files.
    *
    * When hasProgress is false, this property is always zero.
    */
   totalBytes: 0,
   /**
    * Number of bytes currently transferred.  This value starts at zero, and may
    * be updated regardless of the value of hasProgress.
    *
    * @note You shouldn't rely on this property being equal to totalBytes to
    *       determine whether the download is completed.  You should use the
    *       individual state properties instead.
    */
   currentBytes: 0,
   /**
    * Fractional number representing the speed of the download, in bytes per
    * second.  This value is zero when the download is stopped, and may be
    * updated regardless of the value of hasProgress.
    */
   speed: 0,
   /**
    * Indicates whether, at this time, there is any partially downloaded data
    * that can be used when restarting a failed or canceled download.
    *
    * This property is relevant while the download is in progress, and also if it
    * failed or has been canceled.  If the download has been completed
    * successfully, this property is always false.
    *
    * Whether partial data can actually be retained depends on the saver and the
    * download source, and may not be known before the download is started.
    */
   hasPartialData: false,
   /**
    * This can be set to a function that is called after other properties change.
    */
   onchange: null,
   /**
    * This tells if the user has chosen to open/run the downloaded file after
    * download has completed.
    */
   launchWhenSucceeded: false,
   /**
    * This represents the MIME type of the download.
    */
   contentType: null,
   /**
    * This indicates the path of the application to be used to launch the file,
    * or null if the file should be launched with the default application.
    */
   launcherPath: null,
   /**
    * Raises the onchange notification.
    */
   _notifyChange: function D_notifyChange() {
     try {
       if (this.onchange) {
         this.onchange();
       }
     } catch (ex) {
       Cu.reportError(ex);
     }
   },
   /**
    * The download may be stopped and restarted multiple times before it
    * completes successfully. This may happen if any of the download attempts is
    * canceled or fails.
    *
    * This property contains a promise that is linked to the current attempt, or
    * null if the download is either stopped or in the process of being canceled.
    * If the download restarts, this property is replaced with a new promise.
    *
    * The promise is resolved if the attempt it represents finishes successfully,
    * and rejected if the attempt fails.
    */
   _currentAttempt: null,
   /**
    * Starts the download for the first time, or restarts a download that failed
    * or has been canceled.
    *
    * Calling this method when the download has been completed successfully has
    * no effect, and the method returns a resolved promise.  If the download is
    * in progress, the method returns the same promise as the previous call.
    *
    * If the "cancel" method was called but the cancellation process has not
    * finished yet, this method waits for the cancellation to finish, then
    * restarts the download immediately.
    *
    * @note If you need to start a new download from the same source, rather than
    *       restarting a failed or canceled one, you should create a separate
    *       Download object with the same source as the current one.
    *
    * @return {Promise}
    * @resolves When the download has finished successfully.
    * @rejects JavaScript exception if the download failed.
    */
   start: function D_start()
   {
     // If the download succeeded, it's the final state, we have nothing to do.
     if (this.succeeded) {
       return Promise.resolve();
     }
     // If the download already started and hasn't failed or hasn't been
     // canceled, return the same promise as the previous call, allowing the
     // caller to wait for the current attempt to finish.
     if (this._currentAttempt) {
       return this._currentAttempt;
     }
     // While shutting down or disposing of this object, we prevent the download
     // from returning to be in progress.
     if (this._finalized) {
       return Promise.reject(new DownloadError({
                                 message: "Cannot start after finalization."}));
     }
     // Initialize all the status properties for a new or restarted download.
     this.stopped = false;
     this.canceled = false;
     this.error = null;
     this.hasProgress = false;
     this.progress = 0;
     this.totalBytes = 0;
     this.currentBytes = 0;
     this.startTime = new Date();
     // Create a new deferred object and an associated promise before starting
     // the actual download.  We store it on the download as the current attempt.
     let deferAttempt = Promise.defer();
     let currentAttempt = deferAttempt.promise;
     this._currentAttempt = currentAttempt;
     // Restart the progress and speed calculations from scratch.
     this._lastProgressTimeMs = 0;
     // This function propagates progress from the DownloadSaver object, unless
     // it comes in late from a download attempt that was replaced by a new one.
     // If the cancellation process for the download has started, then the update
     // is ignored.
     function DS_setProgressBytes(aCurrentBytes, aTotalBytes, aHasPartialData)
     {
       if (this._currentAttempt == currentAttempt) {
         this._setBytes(aCurrentBytes, aTotalBytes, aHasPartialData);
       }
     }
     // This function propagates download properties from the DownloadSaver
     // object, unless it comes in late from a download attempt that was
     // replaced by a new one.  If the cancellation process for the download has
     // started, then the update is ignored.
     function DS_setProperties(aOptions)
     {
       if (this._currentAttempt != currentAttempt) {
         return;
       }
       let changeMade = false;
       if ("contentType" in aOptions &&
           this.contentType != aOptions.contentType) {
         this.contentType = aOptions.contentType;
         changeMade = true;
       }
       if (changeMade) {
         this._notifyChange();
       }
     }
     // Now that we stored the promise in the download object, we can start the
     // task that will actually execute the download.
     deferAttempt.resolve(Task.spawn(function task_D_start() {
       // Wait upon any pending operation before restarting.
       if (this._promiseCanceled) {
         yield this._promiseCanceled;
       }
       if (this._promiseRemovePartialData) {
         try {
           yield this._promiseRemovePartialData;
         } catch (ex) {
           // Ignore any errors, which are already reported by the original
           // caller of the removePartialData method.
         }
       }
       // In case the download was restarted while cancellation was in progress,
       // but the previous attempt actually succeeded before cancellation could
       // be processed, it is possible that the download has already finished.
       if (this.succeeded) {
         return;
       }
       try {
         // Disallow download if parental controls service restricts it.
         if (yield DownloadIntegration.shouldBlockForParentalControls(this)) {
           throw new DownloadError({ becauseBlockedByParentalControls: true });
         }
         // We should check if we have been canceled in the meantime, after all
         // the previous asynchronous operations have been executed and just
         // before we call the "execute" method of the saver.
         if (this._promiseCanceled) {
           // The exception will become a cancellation in the "catch" block.
           throw undefined;
         }
         // Execute the actual download through the saver object.
         this._saverExecuting = true;
         yield this.saver.execute(DS_setProgressBytes.bind(this),
                                  DS_setProperties.bind(this));
         // Check for application reputation, which requires the entire file to
         // be downloaded.  After that, check for the last time if the download
         // has been canceled.  Both cases require the target file to be deleted,
         // thus we process both in the same block of code.
         if ((yield DownloadIntegration.shouldBlockForReputationCheck(this)) ||
             this._promiseCanceled) {
           try {
             yield OS.File.remove(this.target.path);
           } catch (ex) {
             Cu.reportError(ex);
           }
           // If this is actually a cancellation, this exception will be changed
           // in the catch block below.
           throw new DownloadError({ becauseBlockedByReputationCheck: true });
         }
         // Update the status properties for a successful download.
         this.progress = 100;
         this.succeeded = true;
         this.hasPartialData = false;
       } catch (ex) {
         // Fail with a generic status code on cancellation, so that the caller
         // is forced to actually check the status properties to see if the
         // download was canceled or failed because of other reasons.
         if (this._promiseCanceled) {
           throw new DownloadError({ message: "Download canceled." });
         }
         // An HTTP 450 error code is used by Windows to indicate that a uri is
         // blocked by parental controls. This will prevent the download from
         // occuring, so an error needs to be raised. This is not performed
         // during the parental controls check above as it requires the request
         // to start.
         if (this._blockedByParentalControls) {
           ex = new DownloadError({ becauseBlockedByParentalControls: true });
         }
         // Update the download error, unless a new attempt already started. The
         // change in the status property is notified in the finally block.
         if (this._currentAttempt == currentAttempt || !this._currentAttempt) {
           this.error = ex;
         }
         throw ex;
       } finally {
         // Any cancellation request has now been processed.
         this._saverExecuting = false;
         this._promiseCanceled = null;
         // Update the status properties, unless a new attempt already started.
         if (this._currentAttempt == currentAttempt || !this._currentAttempt) {
           this._currentAttempt = null;
           this.stopped = true;
           this.speed = 0;
           this._notifyChange();
           if (this.succeeded) {
             yield DownloadIntegration.downloadDone(this);
             this._deferSucceeded.resolve();
             if (this.launchWhenSucceeded) {
               this.launch().then(null, Cu.reportError);
               // Always schedule files to be deleted at the end of the private browsing
               // mode, regardless of the value of the pref.
               if (this.source.isPrivate) {
                 gExternalAppLauncher.deleteTemporaryPrivateFileWhenPossible(
                                      new FileUtils.File(this.target.path));
               } else if (Services.prefs.getBoolPref(
                           "browser.helperApps.deleteTempFileOnExit")) {
                 gExternalAppLauncher.deleteTemporaryFileOnExit(
                                      new FileUtils.File(this.target.path));
               }
             }
           }
         }
       }
     }.bind(this)));
     // Notify the new download state before returning.
     this._notifyChange();
     return currentAttempt;
   },
   /*
    * Launches the file after download has completed. This can open
    * the file with the default application for the target MIME type
    * or file extension, or with a custom application if launcherPath
    * is set.
    *
    * @return {Promise}
    * @resolves When the instruction to launch the file has been
    *           successfully given to the operating system. Note that
    *           the OS might still take a while until the file is actually
    *           launched.
    * @rejects  JavaScript exception if there was an error trying to launch
    *           the file.
    */
   launch: function() {
     if (!this.succeeded) {
       return Promise.reject(
         new Error("launch can only be called if the download succeeded")
       );
     }
     return DownloadIntegration.launchDownload(this);
   },
   /*
    * Shows the folder containing the target file, or where the target file
    * will be saved. This may be called at any time, even if the download
    * failed or is currently in progress.
    *
    * @return {Promise}
    * @resolves When the instruction to open the containing folder has been
    *           successfully given to the operating system. Note that
    *           the OS might still take a while until the folder is actually
    *           opened.
    * @rejects  JavaScript exception if there was an error trying to open
    *           the containing folder.
    */
   showContainingDirectory: function D_showContainingDirectory() {
     return DownloadIntegration.showContainingDirectory(this.target.path);
   },
   /**
    * When a request to cancel the download is received, contains a promise that
    * will be resolved when the cancellation request is processed.  When the
    * request is processed, this property becomes null again.
    */
   _promiseCanceled: null,
   /**
    * True between the call to the "execute" method of the saver and the
    * completion of the current download attempt.
    */
   _saverExecuting: false,
   /**
    * Cancels the download.
    *
    * The cancellation request is asynchronous.  Until the cancellation process
    * finishes, temporary files or part files may still exist even if they are
    * expected to be deleted.
    *
    * In case the download completes successfully before the cancellation request
    * could be processed, this method has no effect, and it returns a resolved
    * promise.  You should check the properties of the download at the time the
    * returned promise is resolved to determine if the download was cancelled.
    *
    * Calling this method when the download has been completed successfully,
    * failed, or has been canceled has no effect, and the method returns a
    * resolved promise.  This behavior is designed for the case where the call
    * to "cancel" happens asynchronously, and is consistent with the case where
    * the cancellation request could not be processed in time.
    *
    * @return {Promise}
    * @resolves When the cancellation process has finished.
    * @rejects Never.
    */
   cancel: function D_cancel()
   {
     // If the download is currently stopped, we have nothing to do.
     if (this.stopped) {
       return Promise.resolve();
     }
     if (!this._promiseCanceled) {
       // Start a new cancellation request.
       let deferCanceled = Promise.defer();
       this._currentAttempt.then(function () deferCanceled.resolve(),
                                 function () deferCanceled.resolve());
       this._promiseCanceled = deferCanceled.promise;
       // The download can already be restarted.
       this._currentAttempt = null;
       // Notify that the cancellation request was received.
       this.canceled = true;
       this._notifyChange();
       // Execute the actual cancellation through the saver object, in case it
       // has already started.  Otherwise, the cancellation will be handled just
       // before the saver is started.
       if (this._saverExecuting) {
         this.saver.cancel();
       }
     }
     return this._promiseCanceled;
   },
   /**
    * Indicates whether any partially downloaded data should be retained, to use
    * when restarting a failed or canceled download.  The default is false.
    *
    * Whether partial data can actually be retained depends on the saver and the
    * download source, and may not be known before the download is started.
    *
    * To have any effect, this property must be set before starting the download.
    * Resetting this property to false after the download has already started
    * will not remove any partial data.
    *
    * If this property is set to true, care should be taken that partial data is
    * removed before the reference to the download is discarded.  This can be
    * done using the removePartialData or the "finalize" methods.
    */
   tryToKeepPartialData: false,
   /**
    * When a request to remove partially downloaded data is received, contains a
    * promise that will be resolved when the removal request is processed.  When
    * the request is processed, this property becomes null again.
    */
   _promiseRemovePartialData: null,
   /**
    * Removes any partial data kept as part of a canceled or failed download.
    *
    * If the download is not canceled or failed, this method has no effect, and
    * it returns a resolved promise.  If the "cancel" method was called but the
    * cancellation process has not finished yet, this method waits for the
    * cancellation to finish, then removes the partial data.
    *
    * After this method has been called, if the tryToKeepPartialData property is
    * still true when the download is restarted, partial data will be retained
    * during the new download attempt.
    *
    * @return {Promise}
    * @resolves When the partial data has been successfully removed.
    * @rejects JavaScript exception if the operation could not be completed.
    */
   removePartialData: function ()
   {
     if (!this.canceled && !this.error) {
       return Promise.resolve();
     }
     let promiseRemovePartialData = this._promiseRemovePartialData;
     if (!promiseRemovePartialData) {
       let deferRemovePartialData = Promise.defer();
       promiseRemovePartialData = deferRemovePartialData.promise;
       this._promiseRemovePartialData = promiseRemovePartialData;
       deferRemovePartialData.resolve(
         Task.spawn(function task_D_removePartialData() {
           try {
             // Wait upon any pending cancellation request.
             if (this._promiseCanceled) {
               yield this._promiseCanceled;
             }
             // Ask the saver object to remove any partial data.
             yield this.saver.removePartialData();
             // For completeness, clear the number of bytes transferred.
             if (this.currentBytes != 0 || this.hasPartialData) {
               this.currentBytes = 0;
               this.hasPartialData = false;
               this._notifyChange();
             }
           } finally {
             this._promiseRemovePartialData = null;
           }
         }.bind(this)));
     }
     return promiseRemovePartialData;
   },
   /**
    * This deferred object contains a promise that is resolved as soon as this
    * download finishes successfully, and is never rejected.  This property is
    * initialized when the download is created, and never changes.
    */
   _deferSucceeded: null,
   /**
    * Returns a promise that is resolved as soon as this download finishes
    * successfully, even if the download was stopped and restarted meanwhile.
    *
    * You can use this property for scheduling download completion actions in the
    * current session, for downloads that are controlled interactively.  If the
    * download is not controlled interactively, you should use the promise
    * returned by the "start" method instead, to check for success or failure.
    *
    * @return {Promise}
    * @resolves When the download has finished successfully.
    * @rejects Never.
    */
   whenSucceeded: function D_whenSucceeded()
   {
     return this._deferSucceeded.promise;
   },
   /**
    * Updates the state of a finished, failed, or canceled download based on the
    * current state in the file system.  If the download is in progress or it has
    * been finalized, this method has no effect, and it returns a resolved
    * promise.
    *
    * This allows the properties of the download to be updated in case the user
    * moved or deleted the target file or its associated ".part" file.
    *
    * @return {Promise}
    * @resolves When the operation has completed.
    * @rejects Never.
    */
   refresh: function ()
   {
     return Task.spawn(function () {
       if (!this.stopped || this._finalized) {
         return;
       }
       // Update the current progress from disk if we retained partial data.
       if (this.hasPartialData && this.target.partFilePath) {
         let stat = yield OS.File.stat(this.target.partFilePath);
         // Ignore the result if the state has changed meanwhile.
         if (!this.stopped || this._finalized) {
           return;
         }
         // Update the bytes transferred and the related progress properties.
         this.currentBytes = stat.size;
         if (this.totalBytes > 0) {
           this.hasProgress = true;
           this.progress = Math.floor(this.currentBytes /
                                          this.totalBytes * 100);
         }
         this._notifyChange();
       }
     }.bind(this)).then(null, Cu.reportError);
   },
   /**
    * True if the "finalize" method has been called.  This prevents the download
    * from starting again after having been stopped.
    */
   _finalized: false,
   /**
    * Ensures that the download is stopped, and optionally removes any partial
    * data kept as part of a canceled or failed download.  After this method has
    * been called, the download cannot be started again.
    *
    * This method should be used in place of "cancel" and removePartialData while
    * shutting down or disposing of the download object, to prevent other callers
    * from interfering with the operation.  This is required because cancellation
    * and other operations are asynchronous.
    *
    * @param aRemovePartialData
    *        Whether any partially downloaded data should be removed after the
    *        download has been stopped.
    *
    * @return {Promise}
    * @resolves When the operation has finished successfully.
    * @rejects JavaScript exception if an error occurred while removing the
    *          partially downloaded data.
    */
   finalize: function (aRemovePartialData)
   {
     // Prevents the download from starting again after having been stopped.
     this._finalized = true;
     if (aRemovePartialData) {
       // Cancel the download, in case it is currently in progress, then remove
       // any partially downloaded data.  The removal operation waits for
       // cancellation to be completed before resolving the promise it returns.
       this.cancel();
       return this.removePartialData();
     } else {
       // Just cancel the download, in case it is currently in progress.
       return this.cancel();
     }
   },
   /**
    * Indicates the time of the last progress notification, expressed as the
    * number of milliseconds since January 1, 1970, 00:00:00 UTC.  This is zero
    * until some bytes have actually been transferred.
    */
   _lastProgressTimeMs: 0,
   /**
    * Updates progress notifications based on the number of bytes transferred.
    *
    * The number of bytes transferred is not updated unless enough time passed
    * since this function was last called.  This limits the computation load, in
    * particular when the listeners update the user interface in response.
    *
    * @param aCurrentBytes
    *        Number of bytes transferred until now.
    * @param aTotalBytes
    *        Total number of bytes to be transferred, or -1 if unknown.
    * @param aHasPartialData
    *        Indicates whether the partially downloaded data can be used when
    *        restarting the download if it fails or is canceled.
    */
   _setBytes: function D_setBytes(aCurrentBytes, aTotalBytes, aHasPartialData) {
     let changeMade = (this.hasPartialData != aHasPartialData);
     this.hasPartialData = aHasPartialData;
     // Unless aTotalBytes is -1, we can report partial download progress.  In
     // this case, notify when the related properties changed since last time.
     if (aTotalBytes != -1 && (!this.hasProgress ||
                               this.totalBytes != aTotalBytes)) {
       this.hasProgress = true;
       this.totalBytes = aTotalBytes;
       changeMade = true;
     }
     // Updating the progress and computing the speed require that enough time
     // passed since the last update, or that we haven't started throttling yet.
     let currentTimeMs = Date.now();
     let intervalMs = currentTimeMs - this._lastProgressTimeMs;
     if (intervalMs >= kProgressUpdateIntervalMs) {
       // Don't compute the speed unless we started throttling notifications.
       if (this._lastProgressTimeMs != 0) {
         // Calculate the speed in bytes per second.
         let rawSpeed = (aCurrentBytes - this.currentBytes) / intervalMs * 1000;
         if (this.speed == 0) {
           // When the previous speed is exactly zero instead of a fractional
           // number, this can be considered the first element of the series.
           this.speed = rawSpeed;
         } else {
           // Apply exponential smoothing, with a smoothing factor of 0.1.
           this.speed = rawSpeed * 0.1 + this.speed * 0.9;
         }
       }
       // Start throttling notifications only when we have actually received some
       // bytes for the first time.  The timing of the first part of the download
       // is not reliable, due to possible latency in the initial notifications.
       // This also allows automated tests to receive and verify the number of
       // bytes initially transferred.
       if (aCurrentBytes > 0) {
         this._lastProgressTimeMs = currentTimeMs;
         // Update the progress now that we don't need its previous value.
         this.currentBytes = aCurrentBytes;
         if (this.totalBytes > 0) {
           this.progress = Math.floor(this.currentBytes / this.totalBytes * 100);
         }
         changeMade = true;
       }
     }
     if (changeMade) {
       this._notifyChange();
     }
   },
   /**
    * Returns a static representation of the current object state.
    *
    * @return A JavaScript object that can be serialized to JSON.
    */
   toSerializable: function ()
   {
     let serializable = {
       source: this.source.toSerializable(),
       target: this.target.toSerializable(),
     };
     // Simplify the representation for the most common saver type.  If the saver
     // is an object instead of a simple string, we can't simplify it because we
     // need to persist all its properties, not only "type".  This may happen for
     // savers of type "copy" as well as other types.
     let saver = this.saver.toSerializable();
     if (saver !== "copy") {
       serializable.saver = saver;
     }
     if (this.error && ("message" in this.error)) {
       serializable.error = { message: this.error.message };
     }
     if (this.startTime) {
       serializable.startTime = this.startTime.toJSON();
     }
     // These are serialized unless they are false, null, or empty strings.
     for (let property of kSerializableDownloadProperties) {
       if (property != "error" && property != "startTime" && this[property]) {
         serializable[property] = this[property];
       }
     }
     serializeUnknownProperties(this, serializable);
     return serializable;
   },
   /**
    * Returns a value that changes only when one of the properties of a Download
    * object that should be saved into a file also change.  This excludes
    * properties whose value doesn't usually change during the download lifetime.
    *
    * This function is used to determine whether the download should be
    * serialized after a property change notification has been received.
    *
    * @return String representing the relevant download state.
    */
   getSerializationHash: function ()
   {
     // The "succeeded", "canceled", "error", and startTime properties are not
     // taken into account because they all change before the "stopped" property
     // changes, and are not altered in other cases.
     return this.stopped + "," + this.totalBytes + "," + this.hasPartialData +
            "," + this.contentType;
   },
 };
 /**
  * Defines which properties of the Download object are serializable.
  */
 const kSerializableDownloadProperties = [
   "succeeded",
   "canceled",
   "error",
   "totalBytes",
   "hasPartialData",
   "tryToKeepPartialData",
   "launcherPath",
   "launchWhenSucceeded",
   "contentType",
 ];
 /**
  * Creates a new Download object from a serializable representation.  This
  * function is used by the createDownload method of Downloads.jsm when a new
  * Download object is requested, thus some properties may refer to live objects
  * in place of their serializable representations.
  *
  * @param aSerializable
  *        An object with the following fields:
  *        {
  *          source: DownloadSource object, or its serializable representation.
  *                  See DownloadSource.fromSerializable for details.
  *          target: DownloadTarget object, or its serializable representation.
  *                  See DownloadTarget.fromSerializable for details.
  *          saver: Serializable representation of a DownloadSaver object.  See
  *                 DownloadSaver.fromSerializable for details.  If omitted,
  *                 defaults to "copy".
  *        }
  *
  * @return The newly created Download object.
  */
 Download.fromSerializable = function (aSerializable) {
   let download = new Download();
   if (aSerializable.source instanceof DownloadSource) {
     download.source = aSerializable.source;
   } else {
     download.source = DownloadSource.fromSerializable(aSerializable.source);
   }
   if (aSerializable.target instanceof DownloadTarget) {
     download.target = aSerializable.target;
   } else {
     download.target = DownloadTarget.fromSerializable(aSerializable.target);
   }
   if ("saver" in aSerializable) {
     download.saver = DownloadSaver.fromSerializable(aSerializable.saver);
   } else {
     download.saver = DownloadSaver.fromSerializable("copy");
   }
   download.saver.download = download;
   if ("startTime" in aSerializable) {
     let time = aSerializable.startTime.getTime
              ? aSerializable.startTime.getTime()
              : aSerializable.startTime;
     download.startTime = new Date(time);
   }
   for (let property of kSerializableDownloadProperties) {
     if (property in aSerializable) {
       download[property] = aSerializable[property];
     }
   }
   deserializeUnknownProperties(download, aSerializable, property =>
     kSerializableDownloadProperties.indexOf(property) == -1 &&
     property != "startTime" &&
     property != "source" &&
     property != "target" &&
     property != "saver");
   return download;
 };
 ////////////////////////////////////////////////////////////////////////////////
 //// DownloadSource
 /**
  * Represents the source of a download, for example a document or an URI.
  */
 this.DownloadSource = function () {}
 this.DownloadSource.prototype = {
   /**
    * String containing the URI for the download source.
    */
   url: null,
   /**
    * Indicates whether the download originated from a private window.  This
    * determines the context of the network request that is made to retrieve the
    * resource.
    */
   isPrivate: false,
   /**
    * String containing the referrer URI of the download source, or null if no
    * referrer should be sent or the download source is not HTTP.
    */
   referrer: null,
   /**
    * Returns a static representation of the current object state.
    *
    * @return A JavaScript object that can be serialized to JSON.
    */
   toSerializable: function ()
   {
     // Simplify the representation if we don't have other details.
     if (!this.isPrivate && !this.referrer && !this._unknownProperties) {
       return this.url;
     }
     let serializable = { url: this.url };
     if (this.isPrivate) {
       serializable.isPrivate = true;
     }
     if (this.referrer) {
       serializable.referrer = this.referrer;
     }
     serializeUnknownProperties(this, serializable);
     return serializable;
   },
 };
 /**
  * Creates a new DownloadSource object from its serializable representation.
  *
  * @param aSerializable
  *        Serializable representation of a DownloadSource object.  This may be a
  *        string containing the URI for the download source, an nsIURI, or an
  *        object with the following properties:
  *        {
  *          url: String containing the URI for the download source.
  *          isPrivate: Indicates whether the download originated from a private
  *                     window.  If omitted, the download is public.
  *          referrer: String containing the referrer URI of the download source.
  *                    Can be omitted or null if no referrer should be sent or
  *                    the download source is not HTTP.
  *        }
  *
  * @return The newly created DownloadSource object.
  */
 this.DownloadSource.fromSerializable = function (aSerializable) {
   let source = new DownloadSource();
   if (isString(aSerializable)) {
     // Convert String objects to primitive strings at this point.
     source.url = aSerializable.toString();
   } else if (aSerializable instanceof Ci.nsIURI) {
     source.url = aSerializable.spec;
   } else {
     // Convert String objects to primitive strings at this point.
     source.url = aSerializable.url.toString();
     if ("isPrivate" in aSerializable) {
       source.isPrivate = aSerializable.isPrivate;
     }
     if ("referrer" in aSerializable) {
       source.referrer = aSerializable.referrer;
     }
     deserializeUnknownProperties(source, aSerializable, property =>
       property != "url" && property != "isPrivate" && property != "referrer");
   }
   return source;
 };
 ////////////////////////////////////////////////////////////////////////////////
 //// DownloadTarget
 /**
  * Represents the target of a download, for example a file in the global
  * downloads directory, or a file in the system temporary directory.
  */
 this.DownloadTarget = function () {}
 this.DownloadTarget.prototype = {
   /**
    * String containing the path of the target file.
    */
   path: null,
   /**
    * String containing the path of the ".part" file containing the data
    * downloaded so far, or null to disable the use of a ".part" file to keep
    * partially downloaded data.
    */
   partFilePath: null,
   /**
    * Returns a static representation of the current object state.
    *
    * @return A JavaScript object that can be serialized to JSON.
    */
   toSerializable: function ()
   {
     // Simplify the representation if we don't have other details.
     if (!this.partFilePath && !this._unknownProperties) {
       return this.path;
     }
     let serializable = { path: this.path,
                          partFilePath: this.partFilePath };
     serializeUnknownProperties(this, serializable);
     return serializable;
   },
 };
 /**
  * Creates a new DownloadTarget object from its serializable representation.
  *
  * @param aSerializable
  *        Serializable representation of a DownloadTarget object.  This may be a
  *        string containing the path of the target file, an nsIFile, or an
  *        object with the following properties:
  *        {
  *          path: String containing the path of the target file.
  *          partFilePath: optional string containing the part file path.
  *        }
  *
  * @return The newly created DownloadTarget object.
  */
 this.DownloadTarget.fromSerializable = function (aSerializable) {
   let target = new DownloadTarget();
   if (isString(aSerializable)) {
     // Convert String objects to primitive strings at this point.
     target.path = aSerializable.toString();
   } else if (aSerializable instanceof Ci.nsIFile) {
     // Read the "path" property of nsIFile after checking the object type.
     target.path = aSerializable.path;
   } else {
     // Read the "path" property of the serializable DownloadTarget
     // representation, converting String objects to primitive strings.
     target.path = aSerializable.path.toString();
     if ("partFilePath" in aSerializable) {
       target.partFilePath = aSerializable.partFilePath;
     }
     deserializeUnknownProperties(target, aSerializable, property =>
       property != "path" && property != "partFilePath");
   }
   return target;
 };
 ////////////////////////////////////////////////////////////////////////////////
 //// DownloadError
 /**
  * Provides detailed information about a download failure.
  *
  * @param aProperties
  *        Object which may contain any of the following properties:
  *          {
  *            result: Result error code, defaulting to Cr.NS_ERROR_FAILURE
  *            message: String error message to be displayed, or null to use the
  *                     message associated with the result code.
  *            inferCause: If true, attempts to determine if the cause of the
  *                        download is a network failure or a local file failure,
  *                        based on a set of known values of the result code.
  *                        This is useful when the error is received by a
  *                        component that handles both aspects of the download.
  *          }
  *        The properties object may also contain any of the DownloadError's
  *        because properties, which will be set accordingly in the error object.
  */
 this.DownloadError = function (aProperties)
 {
   const NS_ERROR_MODULE_BASE_OFFSET = 0x45;
   const NS_ERROR_MODULE_NETWORK = 6;
   const NS_ERROR_MODULE_FILES = 13;
   // Set the error name used by the Error object prototype first.
   this.name = "DownloadError";
   this.result = aProperties.result || Cr.NS_ERROR_FAILURE;
   if (aProperties.message) {
     this.message = aProperties.message;
   } else if (aProperties.becauseBlocked ||
              aProperties.becauseBlockedByParentalControls ||
              aProperties.becauseBlockedByReputationCheck) {
     this.message = "Download blocked.";
   } else {
     let exception = new Components.Exception("", this.result);
     this.message = exception.toString();
   }
   if (aProperties.inferCause) {
     let module = ((this.result & 0x7FFF0000) >> 16) -
                  NS_ERROR_MODULE_BASE_OFFSET;
     this.becauseSourceFailed = (module == NS_ERROR_MODULE_NETWORK);
     this.becauseTargetFailed = (module == NS_ERROR_MODULE_FILES);
   }
   else {
     if (aProperties.becauseSourceFailed) {
       this.becauseSourceFailed = true;
     }
     if (aProperties.becauseTargetFailed) {
       this.becauseTargetFailed = true;
     }
   }
   if (aProperties.becauseBlockedByParentalControls) {
     this.becauseBlocked = true;
     this.becauseBlockedByParentalControls = true;
   } else if (aProperties.becauseBlockedByReputationCheck) {
     this.becauseBlocked = true;
     this.becauseBlockedByReputationCheck = true;
   } else if (aProperties.becauseBlocked) {
     this.becauseBlocked = true;
   }
   this.stack = new Error().stack;
 }
 this.DownloadError.prototype = {
   __proto__: Error.prototype,
   /**
    * The result code associated with this error.
    */
   result: false,
   /**
    * Indicates an error occurred while reading from the remote location.
    */
   becauseSourceFailed: false,
   /**
    * Indicates an error occurred while writing to the local target.
    */
   becauseTargetFailed: false,
   /**
    * Indicates the download failed because it was blocked.  If the reason for
    * blocking is known, the corresponding property will be also set.
    */
   becauseBlocked: false,
   /**
    * Indicates the download was blocked because downloads are globally
    * disallowed by the Parental Controls or Family Safety features on Windows.
    */
   becauseBlockedByParentalControls: false,
   /**
    * Indicates the download was blocked because it failed the reputation check
    * and may be malware.
    */
   becauseBlockedByReputationCheck: false,
 };
 ////////////////////////////////////////////////////////////////////////////////
 //// DownloadSaver
 /**
  * Template for an object that actually transfers the data for the download.
  */
 this.DownloadSaver = function () {}
 this.DownloadSaver.prototype = {
   /**
    * Download object for raising notifications and reading properties.
    *
    * If the tryToKeepPartialData property of the download object is false, the
    * saver should never try to keep partially downloaded data if the download
    * fails.
    */
   download: null,
   /**
    * Executes the download.
    *
    * @param aSetProgressBytesFn
    *        This function may be called by the saver to report progress. It
    *        takes three arguments: the first is the number of bytes transferred
    *        until now, the second is the total number of bytes to be
    *        transferred (or -1 if unknown), the third indicates whether the
    *        partially downloaded data can be used when restarting the download
    *        if it fails or is canceled.
    * @param aSetPropertiesFn
    *        This function may be called by the saver to report information
    *        about new download properties discovered by the saver during the
    *        download process. It takes an object where the keys represents
    *        the names of the properties to set, and the value represents the
    *        value to set.
    *
    * @return {Promise}
    * @resolves When the download has finished successfully.
    * @rejects JavaScript exception if the download failed.
    */
   execute: function DS_execute(aSetProgressBytesFn, aSetPropertiesFn)
   {
     throw new Error("Not implemented.");
   },
   /**
    * Cancels the download.
    */
   cancel: function DS_cancel()
   {
     throw new Error("Not implemented.");
   },
   /**
    * Removes any partial data kept as part of a canceled or failed download.
    *
    * This method is never called until the promise returned by "execute" is
    * either resolved or rejected, and the "execute" method is not called again
    * until the promise returned by this method is resolved or rejected.
    *
    * @return {Promise}
    * @resolves When the operation has finished successfully.
    * @rejects JavaScript exception.
    */
   removePartialData: function DS_removePartialData()
   {
     return Promise.resolve();
   },
   /**
    * This can be called by the saver implementation when the download is already
    * started, to add it to the browsing history.  This method has no effect if
    * the download is private.
    */
   addToHistory: function ()
   {
     if (this.download.source.isPrivate) {
       return;
     }
     let sourceUri = NetUtil.newURI(this.download.source.url);
     let referrer = this.download.source.referrer;
     let referrerUri = referrer ? NetUtil.newURI(referrer) : null;
     let targetUri = NetUtil.newURI(new FileUtils.File(
                                        this.download.target.path));
     // The start time is always available when we reach this point.
     let startPRTime = this.download.startTime.getTime() * 1000;
     gDownloadHistory.addDownload(sourceUri, referrerUri, startPRTime,
                                  targetUri);
   },
   /**
    * Returns a static representation of the current object state.
    *
    * @return A JavaScript object that can be serialized to JSON.
    */
   toSerializable: function ()
   {
     throw new Error("Not implemented.");
   },
   /**
    * Returns the SHA-256 hash of the downloaded file, if it exists.
    */
   getSha256Hash: function ()
   {
     throw new Error("Not implemented.");
   },
   getSignatureInfo: function ()
   {
     throw new Error("Not implemented.");
   },
 }; // DownloadSaver
 /**
  * Creates a new DownloadSaver object from its serializable representation.
  *
  * @param aSerializable
  *        Serializable representation of a DownloadSaver object.  If no initial
  *        state information for the saver object is needed, can be a string
  *        representing the class of the download operation, for example "copy".
  *
  * @return The newly created DownloadSaver object.
  */
 this.DownloadSaver.fromSerializable = function (aSerializable) {
   let serializable = isString(aSerializable) ? { type: aSerializable }
                                              : aSerializable;
   let saver;
   switch (serializable.type) {
     case "copy":
       saver = DownloadCopySaver.fromSerializable(serializable);
       break;
     case "legacy":
       saver = DownloadLegacySaver.fromSerializable(serializable);
       break;
     default:
       throw new Error("Unrecoginzed download saver type.");
   }
   return saver;
 };
 ////////////////////////////////////////////////////////////////////////////////
 //// DownloadCopySaver
 /**
  * Saver object that simply copies the entire source file to the target.
  */
 this.DownloadCopySaver = function () {}
 this.DownloadCopySaver.prototype = {
   __proto__: DownloadSaver.prototype,
   /**
    * BackgroundFileSaver object currently handling the download.
    */
   _backgroundFileSaver: null,
   /**
    * Indicates whether the "cancel" method has been called.  This is used to
    * prevent the request from starting in case the operation is canceled before
    * the BackgroundFileSaver instance has been created.
    */
   _canceled: false,
   /**
    * Save the SHA-256 hash in raw bytes of the downloaded file. This is null
    * unless BackgroundFileSaver has successfully completed saving the file.
    */
   _sha256Hash: null,
   /**
    * Save the signature info as an nsIArray of nsIX509CertList of nsIX509Cert
    * if the file is signed. This is empty if the file is unsigned, and null
    * unless BackgroundFileSaver has successfully completed saving the file.
    */
   _signatureInfo: null,
   /**
    * True if the associated download has already been added to browsing history.
    */
   alreadyAddedToHistory: false,
   /**
    * String corresponding to the entityID property of the nsIResumableChannel
    * used to execute the download, or null if the channel was not resumable or
    * the saver was instructed not to keep partially downloaded data.
    */
   entityID: null,
   /**
    * Implements "DownloadSaver.execute".
    */
   execute: function DCS_execute(aSetProgressBytesFn, aSetPropertiesFn)
   {
     let copySaver = this;
     this._canceled = false;
     let download = this.download;
     let targetPath = download.target.path;
     let partFilePath = download.target.partFilePath;
     let keepPartialData = download.tryToKeepPartialData;
     return Task.spawn(function task_DCS_execute() {
       // Add the download to history the first time it is started in this
       // session.  If the download is restarted in a different session, a new
       // history visit will be added.  We do this just to avoid the complexity
       // of serializing this state between sessions, since adding a new visit
       // does not have any noticeable side effect.
       if (!this.alreadyAddedToHistory) {
         this.addToHistory();
         this.alreadyAddedToHistory = true;
       }
       // To reduce the chance that other downloads reuse the same final target
       // file name, we should create a placeholder as soon as possible, before
       // starting the network request.  The placeholder is also required in case
       // we are using a ".part" file instead of the final target while the
       // download is in progress.
       try {
         // If the file already exists, don't delete its contents yet.
         let file = yield OS.File.open(targetPath, { write: true });
         yield file.close();
       } catch (ex if ex instanceof OS.File.Error) {
         // Throw a DownloadError indicating that the operation failed because of
         // the target file.  We cannot translate this into a specific result
         // code, but we preserve the original message using the toString method.
         let error = new DownloadError({ message: ex.toString() });
         error.becauseTargetFailed = true;
         throw error;
       }
       try {
         let deferSaveComplete = Promise.defer();
         if (this._canceled) {
           // Don't create the BackgroundFileSaver object if we have been
           // canceled meanwhile.
           throw new DownloadError({ message: "Saver canceled." });
         }
         // Create the object that will save the file in a background thread.
         let backgroundFileSaver = new BackgroundFileSaverStreamListener();
         try {
           // When the operation completes, reflect the status in the promise
           // returned by this download execution function.
           backgroundFileSaver.observer = {
             onTargetChange: function () { },
             onSaveComplete: (aSaver, aStatus) => {
               // Send notifications now that we can restart if needed.
               if (Components.isSuccessCode(aStatus)) {
                 // Save the hash before freeing backgroundFileSaver.
                 this._sha256Hash = aSaver.sha256Hash;
                 this._signatureInfo = aSaver.signatureInfo;
                 deferSaveComplete.resolve();
               } else {
                 // Infer the origin of the error from the failure code, because
                 // BackgroundFileSaver does not provide more specific data.
                 let properties = { result: aStatus, inferCause: true };
                 deferSaveComplete.reject(new DownloadError(properties));
               }
               // Free the reference cycle, to release resources earlier.
               backgroundFileSaver.observer = null;
               this._backgroundFileSaver = null;
             },
           };
           // Create a channel from the source, and listen to progress
           // notifications.
           let channel = NetUtil.newChannel(NetUtil.newURI(download.source.url));
           if (channel instanceof Ci.nsIPrivateBrowsingChannel) {
             channel.setPrivate(download.source.isPrivate);
           }
           if (channel instanceof Ci.nsIHttpChannel &&
               download.source.referrer) {
             channel.referrer = NetUtil.newURI(download.source.referrer);
           }
           // If we have data that we can use to resume the download from where
           // it stopped, try to use it.
           let resumeAttempted = false;
           let resumeFromBytes = 0;
           if (channel instanceof Ci.nsIResumableChannel && this.entityID &&
               partFilePath && keepPartialData) {
             try {
               let stat = yield OS.File.stat(partFilePath);
               channel.resumeAt(stat.size, this.entityID);
               resumeAttempted = true;
               resumeFromBytes = stat.size;
             } catch (ex if ex instanceof OS.File.Error &&
                            ex.becauseNoSuchFile) { }
           }
           channel.notificationCallbacks = {
             QueryInterface: XPCOMUtils.generateQI([Ci.nsIInterfaceRequestor]),
             getInterface: XPCOMUtils.generateQI([Ci.nsIProgressEventSink]),
             onProgress: function DCSE_onProgress(aRequest, aContext, aProgress,
                                                  aProgressMax)
             {
               let currentBytes = resumeFromBytes + aProgress;
               let totalBytes = aProgressMax == -1 ? -1 : (resumeFromBytes +
                                                           aProgressMax);
               aSetProgressBytesFn(currentBytes, totalBytes, aProgress > 0 &&
                                   partFilePath && keepPartialData);
             },
             onStatus: function () { },
           };
           // Open the channel, directing output to the background file saver.
           backgroundFileSaver.QueryInterface(Ci.nsIStreamListener);
           channel.asyncOpen({
             onStartRequest: function (aRequest, aContext) {
               backgroundFileSaver.onStartRequest(aRequest, aContext);
               // Check if the request's response has been blocked by Windows
               // Parental Controls with an HTTP 450 error code.
               if (aRequest instanceof Ci.nsIHttpChannel &&
                   aRequest.responseStatus == 450) {
                 // Set a flag that can be retrieved later when handling the
                 // cancellation so that the proper error can be thrown.
                 this.download._blockedByParentalControls = true;
                 aRequest.cancel(Cr.NS_BINDING_ABORTED);
                 return;
               }
               aSetPropertiesFn({ contentType: channel.contentType });
               // Ensure we report the value of "Content-Length", if available,
               // even if the download doesn't generate any progress events
               // later.
               if (channel.contentLength >= 0) {
                 aSetProgressBytesFn(0, channel.contentLength);
               }
               // If the URL we are downloading from includes a file extension
               // that matches the "Content-Encoding" header, for example ".gz"
               // with a "gzip" encoding, we should save the file in its encoded
               // form.  In all other cases, we decode the body while saving.
               if (channel instanceof Ci.nsIEncodedChannel &&
                   channel.contentEncodings) {
                 let uri = channel.URI;
                 if (uri instanceof Ci.nsIURL && uri.fileExtension) {
                   // Only the first, outermost encoding is considered.
                   let encoding = channel.contentEncodings.getNext();
                   if (encoding) {
                     channel.applyConversion =
                       gExternalHelperAppService.applyDecodingForExtension(
                                                 uri.fileExtension, encoding);
                   }
                 }
               }
               if (keepPartialData) {
                 // If the source is not resumable, don't keep partial data even
                 // if we were asked to try and do it.
                 if (aRequest instanceof Ci.nsIResumableChannel) {
                   try {
                     // If reading the ID succeeds, the source is resumable.
                     this.entityID = aRequest.entityID;
                   } catch (ex if ex instanceof Components.Exception &&
                                  ex.result == Cr.NS_ERROR_NOT_RESUMABLE) {
                     keepPartialData = false;
                   }
                 } else {
                   keepPartialData = false;
                 }
               }
               // Enable hashing and signature verification before setting the
               // target.
               backgroundFileSaver.enableSha256();
               backgroundFileSaver.enableSignatureInfo();
               if (partFilePath) {
                 // If we actually resumed a request, append to the partial data.
                 if (resumeAttempted) {
                   // TODO: Handle Cr.NS_ERROR_ENTITY_CHANGED
                   backgroundFileSaver.enableAppend();
                 }
                 // Use a part file, determining if we should keep it on failure.
                 backgroundFileSaver.setTarget(new FileUtils.File(partFilePath),
                                               keepPartialData);
               } else {
                 // Set the final target file, and delete it on failure.
                 backgroundFileSaver.setTarget(new FileUtils.File(targetPath),
                                               false);
               }
             }.bind(copySaver),
             onStopRequest: function (aRequest, aContext, aStatusCode) {
               try {
                 backgroundFileSaver.onStopRequest(aRequest, aContext,
                                                   aStatusCode);
               } finally {
                 // If the data transfer completed successfully, indicate to the
                 // background file saver that the operation can finish.  If the
                 // data transfer failed, the saver has been already stopped.
                 if (Components.isSuccessCode(aStatusCode)) {
                   if (partFilePath) {
                     // Move to the final target if we were using a part file.
                     backgroundFileSaver.setTarget(
                                         new FileUtils.File(targetPath), false);
                   }
                   backgroundFileSaver.finish(Cr.NS_OK);
                 }
               }
             }.bind(copySaver),
             onDataAvailable: function (aRequest, aContext, aInputStream,
                                        aOffset, aCount) {
               backgroundFileSaver.onDataAvailable(aRequest, aContext,
                                                   aInputStream, aOffset,
                                                   aCount);
             }.bind(copySaver),
           }, null);
           // We should check if we have been canceled in the meantime, after
           // all the previous asynchronous operations have been executed and
           // just before we set the _backgroundFileSaver property.
           if (this._canceled) {
             throw new DownloadError({ message: "Saver canceled." });
           }
           // If the operation succeeded, store the object to allow cancellation.
           this._backgroundFileSaver = backgroundFileSaver;
         } catch (ex) {
           // In case an error occurs while setting up the chain of objects for
           // the download, ensure that we release the resources of the saver.
           backgroundFileSaver.finish(Cr.NS_ERROR_FAILURE);
           throw ex;
         }
         // We will wait on this promise in case no error occurred while setting
         // up the chain of objects for the download.
         yield deferSaveComplete.promise;
       } catch (ex) {
         // Ensure we always remove the placeholder for the final target file on
         // failure, independently of which code path failed.  In some cases, the
         // background file saver may have already removed the file.
         try {
           yield OS.File.remove(targetPath);
         } catch (e2) {
           // If we failed during the operation, we report the error but use the
           // original one as the failure reason of the download.  Note that on
           // Windows we may get an access denied error instead of a no such file
           // error if the file existed before, and was recently deleted.
           if (!(e2 instanceof OS.File.Error &&
                 (e2.becauseNoSuchFile || e2.becauseAccessDenied))) {
             Cu.reportError(e2);
           }
         }
         throw ex;
       }
     }.bind(this));
   },
   /**
    * Implements "DownloadSaver.cancel".
    */
   cancel: function DCS_cancel()
   {
     this._canceled = true;
     if (this._backgroundFileSaver) {
       this._backgroundFileSaver.finish(Cr.NS_ERROR_FAILURE);
       this._backgroundFileSaver = null;
     }
   },
   /**
    * Implements "DownloadSaver.removePartialData".
    */
   removePartialData: function ()
   {
     return Task.spawn(function task_DCS_removePartialData() {
       if (this.download.target.partFilePath) {
         try {
           yield OS.File.remove(this.download.target.partFilePath);
         } catch (ex if ex instanceof OS.File.Error && ex.becauseNoSuchFile) { }
       }
     }.bind(this));
   },
   /**
    * Implements "DownloadSaver.toSerializable".
    */
   toSerializable: function ()
   {
     // Simplify the representation if we don't have other details.
     if (!this.entityID && !this._unknownProperties) {
       return "copy";
     }
     let serializable = { type: "copy",
                          entityID: this.entityID };
     serializeUnknownProperties(this, serializable);
     return serializable;
   },
   /**
    * Implements "DownloadSaver.getSha256Hash"
    */
   getSha256Hash: function ()
   {
     return this._sha256Hash;
   },
   /*
    * Implements DownloadSaver.getSignatureInfo.
    */
   getSignatureInfo: function ()
   {
     return this._signatureInfo;
   }
 };
 /**
  * Creates a new DownloadCopySaver object, with its initial state derived from
  * its serializable representation.
  *
  * @param aSerializable
  *        Serializable representation of a DownloadCopySaver object.
  *
  * @return The newly created DownloadCopySaver object.
  */
 this.DownloadCopySaver.fromSerializable = function (aSerializable) {
   let saver = new DownloadCopySaver();
   if ("entityID" in aSerializable) {
     saver.entityID = aSerializable.entityID;
   }
   deserializeUnknownProperties(saver, aSerializable, property =>
     property != "entityID" && property != "type");
   return saver;
 };
 ////////////////////////////////////////////////////////////////////////////////
 //// DownloadLegacySaver
 /**
  * Saver object that integrates with the legacy nsITransfer interface.
  *
  * For more background on the process, see the DownloadLegacyTransfer object.
  */
 this.DownloadLegacySaver = function()
 {
   this.deferExecuted = Promise.defer();
   this.deferCanceled = Promise.defer();
 }
 this.DownloadLegacySaver.prototype = {
   __proto__: DownloadSaver.prototype,
   /**
    * Save the SHA-256 hash in raw bytes of the downloaded file. This may be
    * null when nsExternalHelperAppService (and thus BackgroundFileSaver) is not
    * invoked.
    */
   _sha256Hash: null,
   /**
    * Save the signature info as an nsIArray of nsIX509CertList of nsIX509Cert
    * if the file is signed. This is empty if the file is unsigned, and null
    * unless BackgroundFileSaver has successfully completed saving the file.
    */
   _signatureInfo: null,
   /**
    * nsIRequest object associated to the status and progress updates we
    * received.  This object is null before we receive the first status and
    * progress update, and is also reset to null when the download is stopped.
    */
   request: null,
   /**
    * This deferred object contains a promise that is resolved as soon as this
    * download finishes successfully, and is rejected in case the download is
    * canceled or receives a failure notification through nsITransfer.
    */
   deferExecuted: null,
   /**
    * This deferred object contains a promise that is resolved if the download
    * receives a cancellation request through the "cancel" method, and is never
    * rejected.  The nsITransfer implementation will register a handler that
    * actually causes the download cancellation.
    */
   deferCanceled: null,
   /**
    * This is populated with the value of the aSetProgressBytesFn argument of the
    * "execute" method, and is null before the method is called.
    */
   setProgressBytesFn: null,
   /**
    * Called by the nsITransfer implementation while the download progresses.
    *
    * @param aCurrentBytes
    *        Number of bytes transferred until now.
    * @param aTotalBytes
    *        Total number of bytes to be transferred, or -1 if unknown.
    */
   onProgressBytes: function DLS_onProgressBytes(aCurrentBytes, aTotalBytes)
   {
     // Ignore progress notifications until we are ready to process them.
     if (!this.setProgressBytesFn) {
       return;
     }
     let hasPartFile = !!this.download.target.partFilePath;
     this.progressWasNotified = true;
     this.setProgressBytesFn(aCurrentBytes, aTotalBytes,
                             aCurrentBytes > 0 && hasPartFile);
   },
   /**
    * Whether the onProgressBytes function has been called at least once.
    */
   progressWasNotified: false,
   /**
    * Called by the nsITransfer implementation when the request has started.
    *
    * @param aRequest
    *        nsIRequest associated to the status update.
    * @param aAlreadyAddedToHistory
    *        Indicates that the nsIExternalHelperAppService component already
    *        added the download to the browsing history, unless it was started
    *        from a private browsing window.  When this parameter is false, the
    *        download is added to the browsing history here.  Private downloads
    *        are never added to history even if this parameter is false.
    */
   onTransferStarted: function (aRequest, aAlreadyAddedToHistory)
   {
     // Store the entity ID to use for resuming if required.
     if (this.download.tryToKeepPartialData &&
         aRequest instanceof Ci.nsIResumableChannel) {
       try {
         // If reading the ID succeeds, the source is resumable.
         this.entityID = aRequest.entityID;
       } catch (ex if ex instanceof Components.Exception &&
                      ex.result == Cr.NS_ERROR_NOT_RESUMABLE) { }
     }
     // For legacy downloads, we must update the referrer at this time.
     if (aRequest instanceof Ci.nsIHttpChannel && aRequest.referrer) {
       this.download.source.referrer = aRequest.referrer.spec;
     }
     if (!aAlreadyAddedToHistory) {
       this.addToHistory();
     }
   },
   /**
    * Called by the nsITransfer implementation when the request has finished.
    *
    * @param aRequest
    *        nsIRequest associated to the status update.
    * @param aStatus
    *        Status code received by the nsITransfer implementation.
    */
   onTransferFinished: function DLS_onTransferFinished(aRequest, aStatus)
   {
     // Store a reference to the request, used when handling completion.
     this.request = aRequest;
     if (Components.isSuccessCode(aStatus)) {
       this.deferExecuted.resolve();
     } else {
       // Infer the origin of the error from the failure code, because more
       // specific data is not available through the nsITransfer implementation.
       let properties = { result: aStatus, inferCause: true };
       this.deferExecuted.reject(new DownloadError(properties));
     }
   },
   /**
    * When the first execution of the download finished, it can be restarted by
    * using a DownloadCopySaver object instead of the original legacy component
    * that executed the download.
    */
   firstExecutionFinished: false,
   /**
    * In case the download is restarted after the first execution finished, this
    * property contains a reference to the DownloadCopySaver that is executing
    * the new download attempt.
    */
   copySaver: null,
   /**
    * String corresponding to the entityID property of the nsIResumableChannel
    * used to execute the download, or null if the channel was not resumable or
    * the saver was instructed not to keep partially downloaded data.
    */
   entityID: null,
   /**
    * Implements "DownloadSaver.execute".
    */
   execute: function DLS_execute(aSetProgressBytesFn)
   {
     // Check if this is not the first execution of the download.  The Download
     // object guarantees that this function is not re-entered during execution.
     if (this.firstExecutionFinished) {
       if (!this.copySaver) {
         this.copySaver = new DownloadCopySaver();
         this.copySaver.download = this.download;
         this.copySaver.entityID = this.entityID;
         this.copySaver.alreadyAddedToHistory = true;
       }
       return this.copySaver.execute.apply(this.copySaver, arguments);
     }
     this.setProgressBytesFn = aSetProgressBytesFn;
     return Task.spawn(function task_DLS_execute() {
       try {
         // Wait for the component that executes the download to finish.
         yield this.deferExecuted.promise;
         // At this point, the "request" property has been populated.  Ensure we
         // report the value of "Content-Length", if available, even if the
         // download didn't generate any progress events.
         if (!this.progressWasNotified &&
             this.request instanceof Ci.nsIChannel &&
             this.request.contentLength >= 0) {
           aSetProgressBytesFn(0, this.request.contentLength);
         }
         // If the component executing the download provides the path of a
         // ".part" file, it means that it expects the listener to move the file
         // to its final target path when the download succeeds.  In this case,
         // an empty ".part" file is created even if no data was received from
         // the source.
         if (this.download.target.partFilePath) {
           yield OS.File.move(this.download.target.partFilePath,
                              this.download.target.path);
         } else {
           // The download implementation may not have created the target file if
           // no data was received from the source.  In this case, ensure that an
           // empty file is created as expected.
           try {
             // This atomic operation is more efficient than an existence check.
             let file = yield OS.File.open(this.download.target.path,
                                           { create: true });
             yield file.close();
           } catch (ex if ex instanceof OS.File.Error && ex.becauseExists) { }
         }
       } catch (ex) {
         // Ensure we always remove the final target file on failure,
         // independently of which code path failed.  In some cases, the
         // component executing the download may have already removed the file.
         try {
           yield OS.File.remove(this.download.target.path);
         } catch (e2) {
           // If we failed during the operation, we report the error but use the
           // original one as the failure reason of the download.  Note that on
           // Windows we may get an access denied error instead of a no such file
           // error if the file existed before, and was recently deleted.
           if (!(e2 instanceof OS.File.Error &&
                 (e2.becauseNoSuchFile || e2.becauseAccessDenied))) {
             Cu.reportError(e2);
           }
         }
         // In case the operation failed, ensure we stop downloading data.  Since
         // we never re-enter this function, deferCanceled is always available.
         this.deferCanceled.resolve();
         throw ex;
       } finally {
         // We don't need the reference to the request anymore.  We must also set
         // deferCanceled to null in order to free any indirect references it
         // may hold to the request.
         this.request = null;
         this.deferCanceled = null;
         // Allow the download to restart through a DownloadCopySaver.
         this.firstExecutionFinished = true;
       }
     }.bind(this));
   },
   /**
    * Implements "DownloadSaver.cancel".
    */
   cancel: function DLS_cancel()
   {
     // We may be using a DownloadCopySaver to handle resuming.
     if (this.copySaver) {
       return this.copySaver.cancel.apply(this.copySaver, arguments);
     }
     // If the download hasn't stopped already, resolve deferCanceled so that the
     // operation is canceled as soon as a cancellation handler is registered.
     // Note that the handler might not have been registered yet.
     if (this.deferCanceled) {
       this.deferCanceled.resolve();
     }
   },
   /**
    * Implements "DownloadSaver.removePartialData".
    */
   removePartialData: function ()
   {
     // DownloadCopySaver and DownloadLeagcySaver use the same logic for removing
     // partially downloaded data, though this implementation isn't shared by
     // other saver types, thus it isn't found on their shared prototype.
     return DownloadCopySaver.prototype.removePartialData.call(this);
   },
   /**
    * Implements "DownloadSaver.toSerializable".
    */
   toSerializable: function ()
   {
     // This object depends on legacy components that are created externally,
     // thus it cannot be rebuilt during deserialization.  To support resuming
     // across different browser sessions, this object is transformed into a
     // DownloadCopySaver for the purpose of serialization.
     return DownloadCopySaver.prototype.toSerializable.call(this);
   },
   /**
    * Implements "DownloadSaver.getSha256Hash".
    */
   getSha256Hash: function ()
   {
     if (this.copySaver) {
       return this.copySaver.getSha256Hash();
     }
     return this._sha256Hash;
   },
   /**
    * Called by the nsITransfer implementation when the hash is available.
    */
   setSha256Hash: function (hash)
   {
     this._sha256Hash = hash;
   },
   /**
    * Implements "DownloadSaver.getSignatureInfo".
    */
   getSignatureInfo: function ()
   {
     if (this.copySaver) {
       return this.copySaver.getSignatureInfo();
     }
     return this._signatureInfo;
   },
   /**
    * Called by the nsITransfer implementation when the hash is available.
    */
   setSignatureInfo: function (signatureInfo)
   {
     this._signatureInfo = signatureInfo;
   },
 };
 /**
  * Returns a new DownloadLegacySaver object.  This saver type has a
  * deserializable form only when creating a new object in memory, because it
  * cannot be serialized to disk.
  */
 this.DownloadLegacySaver.fromSerializable = function () {
   return new DownloadLegacySaver();
 };

The Tor Browser / annotate

toolkit/components/jsdownloads/src/DownloadCore.jsm@b8a032363ba2 (annotated)

toolkit/components/jsdownloads/src/DownloadCore.jsm