/* 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/. */ /** * Provides collections of Download objects and aggregate views on them. */ const FILE_EXTENSIONS = [ "aac", "adt", "adts", "accdb", "accde", "accdr", "accdt", "aif", "aifc", "aiff", "apng", "aspx", "avi", "avif", "bat", "bin", "bmp", "cab", "cda", "csv", "dif", "dll", "doc", "docm", "docx", "dot", "dotx", "eml", "eps", "exe", "flac", "flv", "gif", "htm", "html", "ico", "ini", "iso", "jar", "jfif", "jpg", "jpeg", "json", "m4a", "mdb", "mid", "midi", "mov", "mp3", "mp4", "mpeg", "mpg", "msi", "mui", "oga", "ogg", "ogv", "opus", "pdf", "pjpeg", "pjp", "png", "pot", "potm", "potx", "ppam", "pps", "ppsm", "ppsx", "ppt", "pptm", "pptx", "psd", "pst", "pub", "rar", "rdf", "rtf", "shtml", "sldm", "sldx", "svg", "swf", "sys", "tif", "tiff", "tmp", "txt", "vob", "vsd", "vsdm", "vsdx", "vss", "vssm", "vst", "vstm", "vstx", "wav", "wbk", "webm", "webp", "wks", "wma", "wmd", "wmv", "wmz", "wms", "wpd", "wp5", "xht", "xhtml", "xla", "xlam", "xll", "xlm", "xls", "xlsm", "xlsx", "xlt", "xltm", "xltx", "xml", "zip", ]; const TELEMETRY_EVENT_CATEGORY = "downloads"; /** * Represents a collection of Download objects that can be viewed and managed by * the user interface, and persisted across sessions. */ export class DownloadList { constructor() { /** * Array of Download objects currently in the list. */ this._downloads = []; /** * Set of currently registered views. */ this._views = new Set(); } /** * Retrieves a snapshot of the downloads that are currently in the list. The * returned array does not change when downloads are added or removed, though * the Download objects it contains are still updated in real time. * * @return {Promise} * @resolves An array of Download objects. * @rejects JavaScript exception. */ async getAll() { return Array.from(this._downloads); } /** * Adds a new download to the end of the items list. * * @note When a download is added to the list, its "onchange" event is * registered by the list, thus it cannot be used to monitor the * download. To receive change notifications for downloads that are * added to the list, use the addView method to register for * onDownloadChanged notifications. * * @param download * The Download object to add. * * @return {Promise} * @resolves When the download has been added. * @rejects JavaScript exception. */ async add(download) { this._downloads.push(download); download.onchange = this._change.bind(this, download); this._notifyAllViews("onDownloadAdded", download); } /** * Removes a download from the list. If the download was already removed, * this method has no effect. * * This method does not change the state of the download, to allow adding it * to another list, or control it directly. If you want to dispose of the * download object, you should cancel it afterwards, and remove any partially * downloaded data if needed. * * @param download * The Download object to remove. * * @return {Promise} * @resolves When the download has been removed. * @rejects JavaScript exception. */ async remove(download) { let index = this._downloads.indexOf(download); if (index != -1) { this._downloads.splice(index, 1); download.onchange = null; this._notifyAllViews("onDownloadRemoved", download); } } /** * This function is called when "onchange" events of downloads occur. * * @param download * The Download object that changed. */ _change(download) { this._notifyAllViews("onDownloadChanged", download); } /** * Adds a view that will be notified of changes to downloads. The newly added * view will receive onDownloadAdded notifications for all the downloads that * are already in the list. * * @param view * The view object to add. The following methods may be defined: * { * onDownloadAdded: function (download) { * // Called after download is added to the end of the list. * }, * onDownloadChanged: function (download) { * // Called after the properties of download change. * }, * onDownloadRemoved: function (download) { * // Called after download is removed from the list. * }, * onDownloadBatchStarting: function () { * // Called before multiple changes are made at the same time. * }, * onDownloadBatchEnded: function () { * // Called after all the changes have been made. * }, * } * * @return {Promise} * @resolves When the view has been registered and all the onDownloadAdded * notifications for the existing downloads have been sent. * @rejects JavaScript exception. */ async addView(view) { this._views.add(view); if ("onDownloadAdded" in view) { this._notifyAllViews("onDownloadBatchStarting"); for (let download of this._downloads) { try { view.onDownloadAdded(download); } catch (ex) { console.error(ex); } } this._notifyAllViews("onDownloadBatchEnded"); } } /** * Removes a view that was previously added using addView. * * @param view * The view object to remove. * * @return {Promise} * @resolves When the view has been removed. At this point, the removed view * will not receive any more notifications. * @rejects JavaScript exception. */ async removeView(view) { this._views.delete(view); } /** * Notifies all the views of a download addition, change, removal, or other * event. The additional arguments are passed to the called method. * * @param methodName * String containing the name of the method to call on the view. */ _notifyAllViews(methodName, ...args) { for (let view of this._views) { try { if (methodName in view) { view[methodName](...args); } } catch (ex) { console.error(ex); } } } /** * Removes downloads from the list that have finished, have failed, or have * been canceled without keeping partial data. A filter function may be * specified to remove only a subset of those downloads. * * This method finalizes each removed download, ensuring that any partially * downloaded data associated with it is also removed. * * @param filterFn * The filter function is called with each download as its only * argument, and should return true to remove the download and false * to keep it. This parameter may be null or omitted to have no * additional filter. */ removeFinished(filterFn) { (async () => { let list = await this.getAll(); for (let download of list) { // Remove downloads that have been canceled, even if the cancellation // operation hasn't completed yet so we don't check "stopped" here. // Failed downloads with partial data are also removed. if ( download.stopped && (!download.hasPartialData || download.error) && (!filterFn || filterFn(download)) ) { // Remove the download first, so that the views don't get the change // notifications that may occur during finalization. await this.remove(download); // Find if a file with the same path is also downloading. let sameFileIsDownloading = false; for (let otherDownload of await this.getAll()) { if ( download !== otherDownload && download.target.path == otherDownload.target.path && !otherDownload.error ) { sameFileIsDownloading = true; } } // Ensure that the download is stopped and no partial data is kept. // This works even if the download state has changed meanwhile. We // don't need to wait for the procedure to be complete before // processing the other downloads in the list. let removePartialData = !sameFileIsDownloading; download.finalize(removePartialData).catch(console.error); } } })().catch(console.error); } } /** * Provides a unified, unordered list combining public and private downloads. * * Download objects added to this list are also added to one of the two * underlying lists, based on their "source.isPrivate" property. Views on this * list will receive notifications for both public and private downloads. * * @param publicList * Underlying DownloadList containing public downloads. * @param privateList * Underlying DownloadList containing private downloads. */ export class DownloadCombinedList extends DownloadList { constructor(publicList, privateList) { super(); /** * Underlying DownloadList containing public downloads. */ this._publicList = publicList; /** * Underlying DownloadList containing private downloads. */ this._privateList = privateList; publicList.addView(this).catch(console.error); privateList.addView(this).catch(console.error); } /** * Adds a new download to the end of the items list. * * @note When a download is added to the list, its "onchange" event is * registered by the list, thus it cannot be used to monitor the * download. To receive change notifications for downloads that are * added to the list, use the addView method to register for * onDownloadChanged notifications. * * @param download * The Download object to add. * * @return {Promise} * @resolves When the download has been added. * @rejects JavaScript exception. */ add(download) { let extension = download.target.path.split(".").pop(); if (!FILE_EXTENSIONS.includes(extension)) { extension = "other"; } try { Services.telemetry.recordEvent( TELEMETRY_EVENT_CATEGORY, "added", "fileExtension", extension, {} ); } catch (ex) { console.error( "DownloadsCommon: error recording telemetry event.", ex.message ); } if (download.source.isPrivate) { return this._privateList.add(download); } return this._publicList.add(download); } /** * Removes a download from the list. If the download was already removed, * this method has no effect. * * This method does not change the state of the download, to allow adding it * to another list, or control it directly. If you want to dispose of the * download object, you should cancel it afterwards, and remove any partially * downloaded data if needed. * * @param download * The Download object to remove. * * @return {Promise} * @resolves When the download has been removed. * @rejects JavaScript exception. */ remove(download) { if (download.source.isPrivate) { return this._privateList.remove(download); } return this._publicList.remove(download); } // DownloadList callback onDownloadAdded(download) { this._downloads.push(download); this._notifyAllViews("onDownloadAdded", download); } // DownloadList callback onDownloadChanged(download) { this._notifyAllViews("onDownloadChanged", download); } // DownloadList callback onDownloadRemoved(download) { let index = this._downloads.indexOf(download); if (index != -1) { this._downloads.splice(index, 1); } this._notifyAllViews("onDownloadRemoved", download); } } /** * Provides an aggregated view on the contents of a DownloadList. */ export class DownloadSummary { constructor() { /** * Array of Download objects that are currently part of the summary. */ this._downloads = []; /** * Set of currently registered views. */ this._views = new Set(); } /** * Underlying DownloadList whose contents should be summarized. */ _list = null; /** * Indicates whether all the downloads are currently stopped. */ allHaveStopped = true; /** * Indicates whether whether all downloads have an unknown final size. */ allUnknownSize = true; /** * Indicates the total number of bytes to be transferred before completing all * the downloads that are currently in progress. * * For downloads that do not have a known final size, the number of bytes * currently transferred is reported as part of this property. * * This is zero if no downloads are currently in progress. */ progressTotalBytes = 0; /** * Number of bytes currently transferred as part of all the downloads that are * currently in progress. * * This is zero if no downloads are currently in progress. */ progressCurrentBytes = 0; /** * This method may be called once to bind this object to a DownloadList. * * Views on the summarized data can be registered before this object is bound * to an actual list. This allows the summary to be used without requiring * the initialization of the DownloadList first. * * @param list * Underlying DownloadList whose contents should be summarized. * * @return {Promise} * @resolves When the view on the underlying list has been registered. * @rejects JavaScript exception. */ async bindToList(list) { if (this._list) { throw new Error("bindToList may be called only once."); } await list.addView(this); // Set the list reference only after addView has returned, so that we don't // send a notification to our views for each download that is added. this._list = list; this._onListChanged(); } /** * Adds a view that will be notified of changes to the summary. The newly * added view will receive an initial onSummaryChanged notification. * * @param view * The view object to add. The following methods may be defined: * { * onSummaryChanged: function () { * // Called after any property of the summary has changed. * }, * } * * @return {Promise} * @resolves When the view has been registered and the onSummaryChanged * notification has been sent. * @rejects JavaScript exception. */ async addView(view) { this._views.add(view); if ("onSummaryChanged" in view) { try { view.onSummaryChanged(); } catch (ex) { console.error(ex); } } } /** * Removes a view that was previously added using addView. * * @param view * The view object to remove. * * @return {Promise} * @resolves When the view has been removed. At this point, the removed view * will not receive any more notifications. * @rejects JavaScript exception. */ async removeView(view) { this._views.delete(view); } /** * This function is called when any change in the list of downloads occurs, * and will recalculate the summary and notify the views in case the * aggregated properties are different. */ _onListChanged() { let allHaveStopped = true; let allUnknownSize = true; let progressTotalBytes = 0; let progressCurrentBytes = 0; // Recalculate the aggregated state. See the description of the individual // properties for an explanation of the summarization logic. for (let download of this._downloads) { if (!download.stopped) { allHaveStopped = false; if (download.hasProgress) { allUnknownSize = false; progressTotalBytes += download.totalBytes; } else { progressTotalBytes += download.currentBytes; } progressCurrentBytes += download.currentBytes; } } // Exit now if the properties did not change. if ( this.allHaveStopped == allHaveStopped && this.allUnknownSize == allUnknownSize && this.progressTotalBytes == progressTotalBytes && this.progressCurrentBytes == progressCurrentBytes ) { return; } this.allHaveStopped = allHaveStopped; this.allUnknownSize = allUnknownSize; this.progressTotalBytes = progressTotalBytes; this.progressCurrentBytes = progressCurrentBytes; // Notify all the views that our properties changed. for (let view of this._views) { try { if ("onSummaryChanged" in view) { view.onSummaryChanged(); } } catch (ex) { console.error(ex); } } } // DownloadList callback onDownloadAdded(download) { this._downloads.push(download); if (this._list) { this._onListChanged(); } } // DownloadList callback onDownloadChanged() { this._onListChanged(); } // DownloadList callback onDownloadRemoved(download) { let index = this._downloads.indexOf(download); if (index != -1) { this._downloads.splice(index, 1); } this._onListChanged(); } }