CefRenderProcessHandler

Header: cef_render_process_handler.h
Category: Core APIs

Overview

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

CefRenderProcessHandler

Source File: include/cef_render_process_handler.h

Process / Thread Context: "Class used to implement render process callbacks. The methods of this class will be called on the render process main thread (TID_RENDERER) unless otherwise indicated."

Purpose: Render-process-only callback interface. Implement and return an instance from CefApp::GetRenderProcessHandler(). Provides hooks for WebKit/V8 initialization, browser creation/destruction (in the renderer), V8 context creation/release, uncaught exception notification, focused DOM-node changes, and inter-process message receipt.

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

virtual void OnWebKitInitialized()

Parameters:

• none.

Return Value: void.

Usage Instruction: "Called after WebKit has been initialized." Typical place to register V8 extensions via CefRegisterExtension (see cef_v8.h).

Threading Constraint: Render process main thread (TID_RENDERER).

virtual void OnBrowserCreated(CefRefPtr<CefBrowser> browser, CefRefPtr<CefDictionaryValue> extra_info)

Parameters:

• browser: The newly created browser object (render-side view).
• extra_info: "Optional read-only value originating from CefBrowserHost::CreateBrowser(), CefBrowserHost::CreateBrowserSync(), CefLifeSpanHandler::OnBeforePopup() or CefBrowserView::CreateBrowserView()." May be empty.

Return Value: void.

Usage Instruction: "Called after a browser has been created. When browsing cross-origin a new browser will be created before the old browser with the same identifier is destroyed."

Threading Constraint: Render process main thread (TID_RENDERER).

virtual void OnBrowserDestroyed(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: The browser being destroyed.

Return Value: void.

Usage Instruction: "Called before a browser is destroyed."

Threading Constraint: TID_RENDERER.

virtual CefRefPtr<CefLoadHandler> GetLoadHandler()

Parameters:

• none.

Return Value: "Return the handler for browser load status events." May return nullptr.

Usage Instruction: Return your CefLoadHandler instance for this renderer.

Threading Constraint: TID_RENDERER.

virtual void OnContextCreated(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, CefRefPtr<CefV8Context> context)

Parameters:

• browser: The browser.
• frame: The frame whose V8 context was created.
• context: The V8 context. "To retrieve the JavaScript 'window' object use the CefV8Context::GetGlobal() method." V8 handles can only be accessed from the thread on which they were created; a task runner for posting tasks is available via CefV8Context::GetTaskRunner().

Return Value: void.

Usage Instruction: "Called immediately after the V8 context for a frame has been created." Standard place to install JS bindings, register V8 handlers, attach window.cefQuery-style bridges.

Threading Constraint: TID_RENDERER.

virtual void OnContextReleased(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, CefRefPtr<CefV8Context> context)

Return Value: void.

Usage Instruction: "Called immediately before the V8 context for a frame is released. No references to the context should be kept after this method is called."

Threading Constraint: TID_RENDERER.

virtual void OnUncaughtException(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, CefRefPtr<CefV8Context> context, CefRefPtr<CefV8Exception> exception, CefRefPtr<CefV8StackTrace> stackTrace)

Parameters:

• exception: The uncaught CefV8Exception.
• stackTrace: Associated CefV8StackTrace.

Return Value: void.

Usage Instruction: "Called for global uncaught exceptions in a frame. Execution of this callback is disabled by default. To enable set cef_settings_t.uncaught_exception_stack_size > 0."

Threading Constraint: TID_RENDERER.

virtual void OnFocusedNodeChanged(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, CefRefPtr<CefDOMNode> node)

Parameters:

• browser: The browser.
• frame: Optional — the frame containing the focused node.
• node: Optional — the DOM node that gained focus. "The node object passed to this method represents a snapshot of the DOM at the time this method is executed. DOM objects are only valid for the scope of this method. Do not keep references to or attempt to access any DOM objects outside the scope of this method." May be empty if no specific node gained focus.

Return Value: void.

Usage Instruction: React to focus changes (e.g. to drive IME or accessibility UI). Copy any data you need out of node before returning.

Threading Constraint: TID_RENDERER.

virtual bool OnProcessMessageReceived(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, CefProcessId source_process, CefRefPtr<CefProcessMessage> message)

Parameters:

• browser: The browser the message is for.
• frame: The frame the message is targeted at.
• source_process: The process that sent the message (a CefProcessId enum value, e.g. PID_BROWSER).
• message: The CefProcessMessage payload. "It is safe to keep a reference to |message| outside of this callback."

Return Value: bool. "Return true if the message was handled or false otherwise."

Usage Instruction: Pair with CefFrame::SendProcessMessage(PID_RENDERER, ...) from the browser process (or vice versa). Inspect message->GetName() and read arguments; return true to acknowledge handling.

Threading Constraint: TID_RENDERER.

Usage Example

class MyRenderHandler : public CefRenderProcessHandler {
 public:
  void OnWebKitInitialized() override {
    // Register a JS extension visible to all frames.
    std::string code = "var cef; if (!cef) cef = {};"
                       "cef.ping = function() { native function ping();"
                       " return ping(); };";
    CefRegisterExtension("cef/ext", code, new MyV8Handler());
  }

  void OnContextCreated(CefRefPtr<CefBrowser> b, CefRefPtr<CefFrame> f,
                        CefRefPtr<CefV8Context> ctx) override {
    // Attach a window-level bridge.
    CefRefPtr<CefV8Value> global = ctx->GetGlobal();
    global->SetValue("mybridge",
                      CefV8Value::CreateFunction("mybridge", new MyV8Handler()),
                      V8_PROPERTY_ATTRIBUTE_NONE);
  }

  bool OnProcessMessageReceived(CefRefPtr<CefBrowser> b,
                                CefRefPtr<CefFrame> f,
                                CefProcessId src,
                                CefRefPtr<CefProcessMessage> msg) override {
    if (msg->GetName() == "browser_to_renderer") {
      // handle...
      return true;
    }
    return false;
  }

 private:
  IMPLEMENT_REFCOUNTING(MyRenderHandler);
};

// Wire-up via CefApp:
class MyApp : public CefApp {
  CefRefPtr<CefRenderProcessHandler> GetRenderProcessHandler() override {
    return new MyRenderHandler();
  }
  IMPLEMENT_REFCOUNTING(MyApp);
};