download method

Download a file and return the final TaskStatusUpdate

Different from enqueue, this method returns a Future that completes when the file has been downloaded, or an error has occurred. While it uses the same download mechanism as enqueue, and will execute the download also when the app moves to the background, it is meant for downloads that are awaited while the app is in the foreground.

Optional callbacks for status and progress updates may be added. These function only take a TaskStatus or double argument as the task they refer to is expected to be captured in the closure for this call. For example Downloader.download(task, onStatus: (status) => print('Status for ${task.taskId} is $status);

An optional callback onElapsedTime will be called at regular intervals (defined by elapsedTimeInterval, which defaults to 5 seconds) with a single argument that is the elapsed time since the call to download. This can be used to trigger UI warnings (e.g. 'this is taking rather long') or to cancel the task if it does not complete within a desired time. For performance reasons the elapsedTimeInterval should not be set to a value less than one second. The onElapsedTime callback should not be used to indicate progress. For that, use the onProgress callback.

Use enqueue instead of download if:

• your download/upload is likely to take long and may require running in the background
• you want to monitor tasks centrally, via a listener
• you want more detailed progress information (e.g. file size, network speed, time remaining)

Future<TaskStatusUpdate> download(DownloadTask task,
        {void Function(TaskStatus)? onStatus,
        void Function(double)? onProgress,
        void Function(Duration)? onElapsedTime,
        Duration? elapsedTimeInterval}) =>
    _downloader.enqueueAndAwait(task,
        onStatus: onStatus,
        onProgress: onProgress,
        onElapsedTime: onElapsedTime,
        elapsedTimeInterval: elapsedTimeInterval);