Documentation

Version:
8.1.0 7.41.4
List icon Contents
Close
Introduction
Guides

Downloads

This guide describes how to manage file downloads, track a download progress, get a notification when the download has been completed, etc.

Overview

To get a list of all downloads, associated with the specific Profile, including already completed downloads during this application session and the active downloads, use the following approach:

Java
Kotlin
var downloads = profile.downloads().list();

val downloads = profile.downloads().list()

Using Engine.downloads() you will get the download service for the default profile.

Accepting download

Every time a Browser instance needs to download a file the StartDownloadCallback callback is invoked. In this callback you can decide whether the file should be downloaded, or the download request must be canceled.

Java
Kotlin
browser.set(StartDownloadCallback.class, (params, tell) -> tell.cancel());

browser.register(StartDownloadCallback { params, tell ->
    tell.cancel()
})

By default, all download requests are canceled.

To change the default behavior and allow to download a file, use the following approach:

Java
Kotlin
browser.set(StartDownloadCallback.class, (params, tell) -> {
    var download = params.download();
    // Download target details.
    var downloadTarget = download.target();
    // Tell the engine to download and save the file.
    tell.download(Paths.get(downloadTarget.suggestedFileName()));
});

browser.register(StartDownloadCallback { params, tell ->
    val download = params.download()
    // Download target details.
    val downloadTarget = download.target()
    // Tell the engine to download and save the file.
    tell.download(Path(downloadTarget.suggestedFileName()))
})

In the example above we tell the library that the file can be downloaded and saved to a given destination file.

Make sure that the Chromium main process has rights to create files in the given destination directory. If the given directory already has a file with the given name, then the file will be overwritten automatically. We recommend that you check the rights and the file existence before accepting the file download.

Controlling process

To control the download process use the Download instance you can obtain using the StartDownloadCallback.Params.download() method.

For example:

Java
Kotlin
browser.set(StartDownloadCallback.class, (params, tell) -> {
    var download = params.download();
});

browser.register(StartDownloadCallback { params, tell ->
    val download = params.download()
})

Pausing download

To pause the download use the Download.pause() method:

Java
Kotlin
download.pause();

download.pause()

Resuming download

To resume the paused download use the Download.resume() method:

Java
Kotlin
if (download.isPaused()) {
    download.resume();
}

if (download.isPaused) {
    download.resume()
}

Canceling download

You can cancel the download anytime unless the download is in a terminated state. This includes the completed downloads, canceled downloads, and interrupted downloads that cannot be resumed.

To find out whether download is in the terminated state, use the Download.isDone() method.

To cancel the download use the Download.cancel() method:

Java
Kotlin
if (download.state() == DownloadState.IN_PROGRESS) {
    download.cancel();
}

if (download.state() == DownloadState.IN_PROGRESS) {
    download.cancel()
}

Download events

You can track the download progress, get notifications when the download has been canceled, paused, interrupted, or finished.

Download canceled

To get notifications when the Download has been canceled use the DownloadCanceled event:

Java
Kotlin
download.on(DownloadCanceled.class, event -> {});

download.subscribe<DownloadCanceled> { event -> }

Download finished

To get notifications when the Download has been finished use the DownloadFinished event:

Java
Kotlin
download.on(DownloadFinished.class, event -> {});

download.subscribe<DownloadFinished> { event -> }

Download paused

To get notifications when the Download has been paused use the DownloadPaused event:

Java
Kotlin
download.on(DownloadPaused.class, event -> {});

download.subscribe<DownloadPaused> { event -> }

Download updated

To track the download progress use the DownloadUpdated event:

Java
Kotlin
download.on(DownloadUpdated.class, event -> {
    // Print download progress in percents.
    event.progress().ifPresent(progress ->
            System.out.println((int) (progress.value() * 100) + "%"));
    // The current download speed estimate in bytes/second.
    var currentSpeed = event.currentSpeed();
    // The total size of a file in bytes.
    var totalBytes = event.totalBytes();
    // The number or received (downloaded) bytes.
    var receivedBytes = event.receivedBytes();
});

download.subscribe<DownloadUpdated> { event ->
    // Print download progress in percents.
    event.progress().ifPresent { progress ->
        println("${(progress.value() * 100).toInt()}%")
    }
    // The current download speed estimate in bytes/second.
    val currentSpeed = event.currentSpeed()
    // The total size of a file in bytes.
    val totalBytes = event.totalBytes()
    // The number or received (downloaded) bytes.
    val receivedBytes = event.receivedBytes()
}

Download interrupted

To get notifications when the Download has been interrupted for some reason use the DownloadInterrupted event:

Java
Kotlin
download.on(DownloadInterrupted.class, event -> {
    // The interrupt reason such as file access denied, network failed, etc.
    var reason = event.reason();
});

download.subscribe<DownloadInterrupted> { event ->
    // The interrupt reason such as file access denied, network failed, etc.
    val reason = event.reason()
}