The Tor Browser / file revision

 /* -*- 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();

 };