The Tor Browser: comparison toolkit/components/jsdownloads/src/DownloadCore.jsm

--1:000000000000
+:50eb42a2cce4
+/* -*- 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 / file comparison

comparison: toolkit/components/jsdownloads/src/DownloadCore.jsm

toolkit/components/jsdownloads/src/DownloadCore.jsm