CefBrowserProcessHandler

Header: cef_browser_process_handler.h
Category: Core APIs

Overview

Foundational interfaces: process bootstrap, browser lifecycle, frames, DOM, requests, and data objects.

CefBrowserProcessHandler

Source File: include/cef_browser_process_handler.h

Process / Thread Context: "Class used to implement browser process callbacks. The methods of this class will be called on the browser process main thread unless otherwise indicated." The browser process main thread corresponds to TID_UI. Several methods specify their own thread context.

Purpose: Browser-process-only callback interface. Implement and return an instance from CefApp::GetBrowserProcessHandler(). It owns hooks for preference registration, post-initialization context, child-process launch customization, app relaunch handling, external message-pump scheduling, and default client/handler provisioning for Chrome-style UI.

Methods

`virtual void OnRegisterCustomPreferences(cef_preferences_type_t type, CefRawPtr<CefPreferenceRegistrar> registrar)`

Parameters:

type: Either CEF_PREFERENCES_TYPE_GLOBAL or CEF_PREFERENCES_TYPE_REQUEST_CONTEXT.
registrar: Raw pointer to a CefPreferenceRegistrar. "Do not keep a reference to the |registrar| object."

Return Value: void.

Usage Instruction: For GLOBAL preferences, register once at startup; access via CefPreferenceManager::GetGlobalPreferences after OnContextInitialized. For REQUEST_CONTEXT, register per CefRequestContext; access via CefRequestContext after CefRequestContextHandler::OnRequestContextInitialized. It is intended but not required that all request contexts share the same registered preferences.

Threading Constraint: "This method is called on the browser process UI thread."

`virtual void OnContextInitialized()`

Parameters:

none.

Return Value: void.

Usage Instruction: "Called on the browser process UI thread immediately after the CEF context has been initialized." Typical place to create the first browser via CefBrowserHost::CreateBrowser.

Threading Constraint: Browser process UI thread.

`virtual void OnBeforeChildProcessLaunch(CefRefPtr<CefCommandLine> command_line)`

Parameters:

command_line: The command line for the child process being launched. "Do not keep a reference to |command_line| outside of this method."

Return Value: void.

Usage Instruction: Modify the child command line (e.g. inject switches for renderer/GPU).

Threading Constraint: "Will be called on the browser process UI thread when launching a render process and on the browser process IO thread when launching a GPU process."

`virtual bool OnAlreadyRunningAppRelaunch(CefRefPtr<CefCommandLine> command_line, const CefString& current_directory)`

Parameters:

command_line: Read-only command line of the relaunch attempt. "Do not keep a reference to |command_line| outside of this method."
current_directory: Working directory of the relaunch attempt (optional parameter).

Return Value: bool. "Return true if the relaunch is handled or false for default relaunch behavior. Default behavior will create a new default styled Chrome window."

Usage Instruction: Implement to provide custom behavior when an already-running app with the same CefSettings.root_cache_path is relaunched — e.g. activate an existing window or open a new one. The header explains the singleton-lock mechanism: on relaunch, the new process forwards args to the running app and exits early; clients must check CefInitialize()'s return for early-exit.

Threading Constraint: "This method will be called on the browser process UI thread."

`virtual void OnScheduleMessagePumpWork(int64_t delay_ms)`

Parameters:

delay_ms: Requested delay in milliseconds. If ≤ 0 the call should happen reasonably soon; if > 0 the call should happen after the specified delay and any currently pending scheduled call should be cancelled.

Return Value: void.

Usage Instruction: Used in combination with cef_settings_t.external_message_pump and CefDoMessageLoopWork(). The implementation must arrange for CefDoMessageLoopWork() to be called on the main (UI) thread at the requested time. See warnings on CefDoMessageLoopWork.

Threading Constraint: "Called from any thread when work has been scheduled for the browser process main (UI) thread."

`virtual CefRefPtr<CefClient> GetDefaultClient()`

Parameters:

none.

Return Value: The default client to use with newly created browser windows, or nullptr. "If null is returned the CefBrowser will be unmanaged (no callbacks will be executed for that CefBrowser) and application shutdown will be blocked until the browser window is closed manually."

Usage Instruction: "This method is currently only used with Chrome style when creating new browser windows via Chrome UI." Return a CefClient subclass that supplies the handlers needed for new Chrome-style browser windows.

Threading Constraint: Not specified per-method; class default is browser-process main thread.

`virtual CefRefPtr<CefRequestContextHandler> GetDefaultRequestContextHandler()`

Parameters:

none.

Return Value: The default handler for new user or incognito profiles (CefRequestContext), or nullptr. "If null is returned the CefRequestContext will be unmanaged (no callbacks will be executed for that CefRequestContext)."

Usage Instruction: Like GetDefaultClient, "currently only used with Chrome style when creating new browser windows via Chrome UI."

Threading Constraint: Not specified per-method; class default applies.

Usage Example

cpp

class MyApp : public CefApp, public CefBrowserProcessHandler {
 public:
  CefRefPtr<CefBrowserProcessHandler> GetBrowserProcessHandler() override {
    return this;
  }

  void OnContextInitialized() override {
    // Create the first browser window now that CEF is ready.
    CefWindowInfo wi;
    CefBrowserSettings settings;
    wi.SetAsTopLevel(/* native parent handle */);
    CefBrowserHost::CreateBrowser(wi, new MyClient(), "https://example.com",
                                  settings, nullptr, nullptr);
  }

  void OnBeforeChildProcessLaunch(CefRefPtr<CefCommandLine> cl) override {
    cl->AppendSwitchWithValue("log-level", "0");
  }

  void OnScheduleMessagePumpWork(int64_t delay_ms) override {
    // External message-pump integration: schedule CefDoMessageLoopWork on the
    // host UI thread after delay_ms.
    HostPostDelayedTask([delay_ms]() { CefDoMessageLoopWork(); }, delay_ms);
  }

 private:
  IMPLEMENT_REFCOUNTING(MyApp);
};

CefBrowserProcessHandler ​

Overview ​