A DownloadList object represents a collection of Download objects that can be viewed and managed by the user interface, and persisted across sessions.

A reference to a DownloadList object can be obtained using the Downloads.getList() function.

Method overview

Promise<Array<Download>> getAll();
Promise add(Download aDownload);
Promise remove(Download aDownload);
Promise addView(Object aView);
Promise removeView(Object aView);
void removeFinished([optional] Function aFilterFn);

Methods

getAll()

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.

Promise<Array<Download>> getAll();
Parameters

None.

Promise resolves to

An array of Download objects.

add()

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.
Promise add(
  Download aDownload
);
Parameters
aDownload
The Download object to add.
Promise resolves to

undefined when the download has been added.

remove()

Removes a download from the list. If the download was already removed, this method has no effect.

Promise remove(
  Download aDownload
);
Parameters
aDownload
The Download object to remove.
Promise resolves to

undefined when the download has been removed.

addView()

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.

Promise addView(
  Object aView
);
Parameters
aView
The view object to add. The following methods may be defined:
Promise resolves to

undefined when the view has been registered and all the onDownloadAdded notifications for the existing downloads have been sent.

removeView()

Removes a view that was previously added using addView().

Promise removeView(
  Object aView
);
Parameters
aView Optional
The view object to remove.
Promise resolves to

undefined when the view has been removed. At this point, the removed view will not receive any more notifications.

removeFinished()

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.

Promise removeFinished(
  Function aFilterFn
);
Parameters
aFilterFn
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.

See also