Download

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 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.
contentType string

The MIME type of the download, for example "text/plain", or null if the MIME type is not available.

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 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, 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 DownloadList.
progress Read only number

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 (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 hasProgress is true, this indicates the total number of bytes to be transferred before the download finishes; this value can be zero if the file is empty.

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 DownloadTarget.size property to get the actual size of the completely-downloaded file once the download has succeeded.

When hasProgress is false, this property is always zero.
tryToKeepPartialData boolean

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.

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.

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.
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.

Note: This method should be used in place of the 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
aRemovePartialData Optional
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.

See also