Downloads

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

Overview

When the user clicks a link that points to a resource that cannot be displayed in the browser (e.g. ZIP archive) or loads such a resource, the browser will suggest to download it. By default, a native save file dialog will be shown to the user. In this dialog the user can select the directory where the file will be saved or cancel the download.

If you need to download a resource by URL independently whether the browser can display it or not, you can use the following approach:

browser->download("https://example.com/file.zip");

If you prefer to download the file or cancel the download programmatically, without showing the save file dialog to the user, you can use the onStartDownload delegate as described below.

Accepting a download

To handle the download, use the onStartDownload delegate. In this delegate you can programmatically accept the download and specify the target file path:

browser->onStartDownload = [](const StartDownloadArgs& args,
                              StartDownloadAction action) {
  action.download("path/to/directory/" +
                  args.download->target().suggested_file_name);
};

Important: Make sure that the application has sufficient permissions to save the file. If the target file already exists, the application will overwrite it. We recommend checking the permissions before accepting the file download.

To let the user decide whether to accept the download or not, use the default approach that shows the native save file dialog:

browser->onStartDownload = [](const StartDownloadArgs& args,
                              StartDownloadAction action) {
  action.prompt();
};

Controlling the download

In the onStartDownload delegate you can access the Download instance and use it to control the download process:

browser->onStartDownload = [](const StartDownloadArgs& args,
                              StartDownloadAction action) {
  auto download = args.download;
  action.download("path/to/directory/" + 
                  args.download->target().suggested_file_name);
};

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

download->pause();

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

download->resume();

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

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

bool canceled = download->isCanceled();
bool finished = download->isFinished();
bool interrupted = download->isInterrupted();
if (!(canceled || finished || interrupted)) {
    download->cancel();
}

Download events

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

To get notifications when the download has been canceled use the following event:

download->onDownloadCanceled += [](const DownloadCanceled& event) {};

To get notifications when the download has been finished use the following event:

download->onDownloadFinished += [](const DownloadFinished& event) {};

To get notifications when the download has been paused use the following event:

download->onDownloadPaused += [](const DownloadPaused& event) {};

To track the download progress use the following event:

download->onDownloadUpdated += [](const DownloadUpdated& event) {
  int64_t current_speed = event.current_speed;
  int64_t received_bytes = event.received_bytes;
  auto download = event.download;
};

To get notifications when the download has been interrupted for some reason use the following approach:

download->onDownloadInterrupted += [](const DownloadInterrupted& event) {
  if (event.reason == DownloadInterruptReason::kFileNoSpace) {
    // ...
  }
};

Downloads list

To get a list of all downloads, including already completed downloads during this application session and the active downloads, use the following code:

for (auto download : app->profile()->downloads()) {
  std::cout << "Download from: " << download->target().url << std::endl;
}