CefLoadHandler

Header: cef_load_handler.h
Category: Browser Handlers

Overview

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

CefLoadHandler

Source File: include/cef_load_handler.h

Process / Thread Context: Browser Process UI thread or Renderer process

Purpose: User-implemented interface to handle events related to browser

Renderer-Process API

This interface fires in the renderer process on the TID_RENDERER thread. It cannot directly call browser-process-only APIs like CefBrowserHost.

Methods

void OnLoadingStateChange(CefRefPtr<CefBrowser> browser, bool isLoading, bool canGoBack, bool canGoForward)

Parameters:

• browser: The browser whose loading state changed.
• isLoading: true when a load has been initiated (programmatic or user action) and false when loading terminates (completion, cancellation, or failure).
• canGoBack: Whether the back-history is non-empty.
• canGoForward: Whether the forward-history is non-empty.

Return Value: None.

Usage Instruction: Called twice per load — once at initiation, once at termination. It is called before any OnLoadStart and after all OnLoadError / OnLoadEnd. Use to update a UI loading spinner and back/forward button state for overall browser load status (rather than per-frame).

Threading Constraint: Browser process UI thread or render process main thread (TID_RENDERER).

void OnLoadStart(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, TransitionType transition_type)

Parameters:

• browser: The browser loading the frame.
• frame: The frame that started loading; never empty. Call IsMain() to test main vs sub-frame.
• transition_type: cef_transition_type_t value describing the navigation source. Accurate value is only available in the browser process.

Return Value: None.

Usage Instruction: Called after navigation commit and before the browser begins loading frame contents. Multiple frames may load simultaneously; sub-frames may start/continue loading after the main frame load has ended. Not called for same-page navigations (fragments, history state) or for navigations that fail/cancel before commit. For overall browser status use OnLoadingStateChange.

Threading Constraint: Browser process UI thread or TID_RENDERER.

void OnLoadEnd(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, int httpStatusCode)

Parameters:

• browser: The browser that finished loading the frame.
• frame: The frame that finished; never empty. Call IsMain() to test main vs sub-frame.
• httpStatusCode: HTTP status code from the response (e.g. 200, 404).

Return Value: None.

Usage Instruction: Called when the browser is done loading a frame. Same caveats as OnLoadStart: not called for same-page navigations or pre-commit cancellations.

Threading Constraint: Browser process UI thread or TID_RENDERER.

void OnLoadError(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, ErrorCode errorCode, const CefString& errorText, const CefString& failedUrl)

Parameters:

• browser: The browser where the failure occurred.
• frame: The frame where the failure occurred.
• errorCode: cef_errorcode_t value (see net/base/net_error_list.h).
• errorText: Human-readable error text (may be empty).
• failedUrl: The URL that failed to load.

Return Value: None.

Usage Instruction: Called when a navigation fails or is canceled. May be called by itself (before commit) or in combination with OnLoadStart/OnLoadEnd (after commit). Use to render a custom error page — typically via frame->LoadString(...) or by navigating to a bundled error page.

Threading Constraint: Browser process UI thread or TID_RENDERER.

Usage Example

#include "include/cef_load_handler.h"
#include "include/cef_client.h"

class MyLoadHandler : public CefLoadHandler {
 public:
  void OnLoadingStateChange(CefRefPtr<CefBrowser> browser,
                            bool isLoading,
                            bool canGoBack,
                            bool canGoForward) override {
    // Update toolbar UI state (spinner, back/forward buttons).
  }

  void OnLoadStart(CefRefPtr<CefBrowser> browser,
                   CefRefPtr<CefFrame> frame,
                   TransitionType transition_type) override {
    if (frame->IsMain()) { /* main frame committed */ }
  }

  void OnLoadEnd(CefRefPtr<CefBrowser> browser,
                 CefRefPtr<CefFrame> frame,
                 int httpStatusCode) override {
    // httpStatusCode == 200 means success.
  }

  void OnLoadError(CefRefPtr<CefBrowser> browser,
                   CefRefPtr<CefFrame> frame,
                   ErrorCode errorCode,
                   const CefString& errorText,
                   const CefString& failedUrl) override {
    if (errorCode == ERR_ABORTED) return;  // user canceled, ignore
    frame->LoadString("Custom error: " + errorText, failedUrl);
  }

  IMPLEMENT_REFCOUNTING(MyLoadHandler);
};

class MyClient : public CefClient {
 public:
  CefRefPtr<CefLoadHandler> GetLoadHandler() override {
    return new MyLoadHandler();
  }
};