A Download object 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.
A new Download object can be created using the Downloads.createDownload() function.
Method overview
Promise start(); |
Promise launch(); |
Promise showContainingDirectory(); |
Promise cancel(); |
Promise removePartialData(); |
Promise whenSucceeded(); |
Promise finalize([optional] boolean aRemovePartialData); |
Properties
| Attribute | Type | Description |
canceled Read only |
boolean |
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 |
contentType |
string |
The MIME type of the download, for example " This property may be populated or changed while the download is in progress, using the MIME type provided by the server. |
currentBytes Read only |
number |
Number of bytes currently transferred. This value starts at zero, and may be updated regardless of the value of 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, since this value may not be updated after the last piece of data is transferred. |
error Read only |
DownloadError |
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. |
hasPartialData Read only |
boolean |
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 not relevant anymore. 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. |
hasProgress Read only |
boolean |
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. |
launchWhenSucceeded |
boolean |
If this property is true when the download finishes successfully, the target file will be opened or executed automatically. |
launcherPath |
string |
Local file path of the application to be used to launch the target file, or null if the file should be launched with the default application associated with the contentType property or the extension of the target file. |
onchange |
Function |
This can be set to a function that is called after other properties change. Warning: This property cannot be used if the download is part of a |
progress Read only |
number |
Progress percent, from 0 to 100. Intermediate values are reported only if 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 (for example, the
succeeded property) instead. |
saver Read only |
DownloadSaver |
Saver object associated with this download. |
source Read only |
DownloadSource |
Source of this download. |
startTime Read only |
Date |
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. |
stopped Read only |
boolean |
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. |
succeeded Read only |
boolean |
This propery is true if the download has been completed successfully. |
target Read only |
DownloadTarget |
Target of this download. |
totalBytes Read only |
number |
When Note: This property's value may not match the actual final size of the downloaded file if the download is encoded during the network transfer. You can use the When |
tryToKeepPartialData |
boolean |
Indicates whether any partially downloaded data should be retained, to use when restarting a failed or canceled download. The default is 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 Note: 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. |
Methods
start()
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.
Download object with the same source as the current one.Promise start();
Parameters
None.
Promise resolves to
undefined when the download has finished successfully and you can access the target file.
Promise can be rejected with
DownloadError if the download failed.
launch()
Opens or executes the target file after download has completed.
If the launcherPath property is null, the file will be opened with the default application for the MIME type specified in the contentType property. If the content type is not available, an attempt will be made to obtain it from the extension of the target file.
If the launcherPath property is set, the file will be opened with the specified custom application.
Promise launch();
Parameters
None.
Promise resolves to
undefined 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.
showContainingDirectory()
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.
Promise showContainingDirectory();
Parameters
None.
Promise resolves to
undefined 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.
cancel()
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 canceled.
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.
Promise cancel();
Parameters
None.
Promise resolves to
undefined when the cancellation process has finished.
Promise can be rejected with
Never rejected.
removePartialData()
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.
Promise removePartialData();
Parameters
None.
Promise resolves to
undefined when the partial data has been successfully removed.
whenSucceeded()
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.
Promise whenSucceeded();
Parameters
None.
Promise resolves to
undefined when the download has finished successfully and you can access the target file.
Promise can be rejected with
Never rejected.
finalize()
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.
cancel() and removePartialData() methods 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.Promise finalize( boolean aRemovePartialData );
Parameters
aRemovePartialDataOptional- Whether any partially downloaded data should be removed after the download has been stopped. The default is
false.
Promise resolves to
undefined when the operation has finished successfully.