CefDownloadHandler

Header: cef_download_handler.h
Interfaces: CefBeforeDownloadCallback, CefDownloadItemCallback, CefDownloadHandler
Category: Browser Handlers

Overview

User-implemented handler interfaces returned from CefClient and registered with CefBrowserHost.

CefBeforeDownloadCallback

Source File: include/cef_download_handler.h

Process / Thread Context: Browser process / UI thread (originating OnBeforeDownload is UI thread). USER-CALLED (source=library).

Purpose: Async continuation for download initiation.

Methods

void Continue(const CefString& download_path, bool show_dialog)

Parameters:

• download_path: Full file path including name; leave blank to use the suggested name and default temp directory.
• show_dialog: true to show the default "Save As" dialog.

Return Value: None.

Usage Instruction: Call exactly once to start the download.

Threading Constraint: Threading constraint not specified explicitly per-method; class comment says UI thread.

Usage Example

callback->Continue("C:\\Downloads\\file.pdf", false);

CefDownloadItemCallback

Source File: include/cef_download_handler.h

Process / Thread Context: Browser process / UI thread. USER-CALLED (source=library).

Purpose: Async control of an in-progress download.

Methods

void Cancel()

Return Value: Cancel the download. No parameters, no return.

Threading Constraint: Threading constraint not specified in source.

void Pause()

Return Value: Pause the download. No parameters, no return.

Threading Constraint: Threading constraint not specified in source.

void Resume()

Return Value: Resume the download. No parameters, no return.

Threading Constraint: Threading constraint not specified in source.

Usage Example

// In OnDownloadUpdated, add a Pause button:
if (user_clicked_pause) callback->Pause();

CefDownloadHandler

Source File: include/cef_download_handler.h

Process / Thread Context: Browser process / UI thread. USER-IMPLEMENTED (source=client); returned from CefClient::GetDownloadHandler(). Note: if no CefDownloadHandler is returned from CefClient, "downloads will not be allowed."

Purpose: Handle file downloads — gate which downloads proceed, set the initial path, and receive progress updates.

Methods

bool CanDownload(CefRefPtr<CefBrowser> browser, const CefString& url, const CefString& request_method)

Parameters:

• browser: The browser.
• url: The target download URL.
• request_method: GET, POST, etc.

Return Value: true = proceed; false = cancel. Default is true.

Usage Instruction: Called in response to user-initiated actions (Alt+click, link click with Content-Disposition: attachment).

Threading Constraint: UI thread per class comment ("methods of this class will called on the browser process UI thread").

bool OnBeforeDownload(CefRefPtr<CefBrowser> browser, CefRefPtr<CefDownloadItem> download_item, const CefString& suggested_name, CefRefPtr<CefBeforeDownloadCallback> callback)

Parameters:

• browser: The browser.
• download_item: Current state; do not keep a reference past this method.
• suggested_name: Suggested filename.
• callback: Call Continue(path, show_dialog) to start the download.

Return Value: true = app handles and will execute callback; false = default (Alloy: cancel; Chrome: download shelf).

Usage Instruction: Provide a download prompt or auto-path.

Threading Constraint: UI thread per class comment.

void OnDownloadUpdated(CefRefPtr<CefBrowser> browser, CefRefPtr<CefDownloadItem> download_item, CefRefPtr<CefDownloadItemCallback> callback)

Parameters:

• browser: The browser.
• download_item: Current state; do not keep a reference past this method.
• callback: Use to cancel/pause/resume if desired.

Return Value: None.

Usage Instruction: May be called multiple times before and after OnBeforeDownload. Update UI / progress bars.

Threading Constraint: UI thread per class comment.

Usage Example

class MyDownloadHandler : public CefDownloadHandler {
 public:
  bool CanDownload(CefRefPtr<CefBrowser>, const CefString& url,
                   const CefString&) override {
    return url.ToString().rfind("https://", 0) == 0;
  }
  bool OnBeforeDownload(CefRefPtr<CefBrowser>, CefRefPtr<CefDownloadItem> item,
                        const CefString& name,
                        CefRefPtr<CefBeforeDownloadCallback> cb) override {
    cb->Continue("C:\\Downloads\\" + name, false);
    return true;
  }
  void OnDownloadUpdated(CefRefPtr<CefBrowser>, CefRefPtr<CefDownloadItem> item,
                          CefRefPtr<CefDownloadItemCallback> cb) override {
    if (item->IsComplete() || item->IsCanceled()) return;
    // update UI: item->GetPercentComplete(), item->GetCurrentSpeed(), etc.
  }
  IMPLEMENT_REFCOUNTING(MyDownloadHandler);
};

// MyClient::GetDownloadHandler() returns this.