CefClient

Header: cef_client.h
Category: Core APIs

Overview

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

CefClient

Source File: include/cef_client.h

Process / Thread Context: "Implement this interface to provide handler implementations." Used in the browser process; threaded behavior of each handler is governed by its own class comments.

Purpose: The central browser-event aggregator. Every browser created via CefBrowserHost::CreateBrowser is associated with a CefRefPtr<CefClient> that supplies up to 18 optional sub-handlers (audio, commands, context menus, dialogs, display, downloads, drag, find, focus, frame, permission, JS dialogs, keyboard, life span, load, print, render, request). The client also receives inter-process messages directly via OnProcessMessageReceived.

Methods

`virtual CefRefPtr<CefAudioHandler> GetAudioHandler()`

Return Value: "Return the handler for audio rendering events." nullptr opt-out.

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefCommandHandler> GetCommandHandler()`

Return Value: "Return the handler for commands. If no handler is provided the default implementation will be used."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefContextMenuHandler> GetContextMenuHandler()`

Return Value: "Return the handler for context menus. If no handler is provided the default implementation will be used."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefDialogHandler> GetDialogHandler()`

Return Value: "Return the handler for dialogs. If no handler is provided the default implementation will be used."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefDisplayHandler> GetDisplayHandler()`

Return Value: "Return the handler for browser display state events."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefDownloadHandler> GetDownloadHandler()`

Return Value: "Return the handler for download events. If no handler is returned downloads will not be allowed."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefDragHandler> GetDragHandler()`

Return Value: "Return the handler for drag events."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefFindHandler> GetFindHandler()`

Return Value: "Return the handler for find result events."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefFocusHandler> GetFocusHandler()`

Return Value: "Return the handler for focus events."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefFrameHandler> GetFrameHandler()`

Return Value: "Return the handler for events related to CefFrame lifespan. This method will be called once during CefBrowser creation and the result will be cached for performance reasons."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefPermissionHandler> GetPermissionHandler()`

Return Value: "Return the handler for permission requests."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefJSDialogHandler> GetJSDialogHandler()`

Return Value: "Return the handler for JavaScript dialogs. If no handler is provided the default implementation will be used."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefKeyboardHandler> GetKeyboardHandler()`

Return Value: "Return the handler for keyboard events."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefLifeSpanHandler> GetLifeSpanHandler()`

Return Value: "Return the handler for browser life span events."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefLoadHandler> GetLoadHandler()`

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

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefPrintHandler> GetPrintHandler()`

Return Value: "Return the handler for printing on Linux. If a print handler is not provided then printing will not be supported on the Linux platform."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefRenderHandler> GetRenderHandler()`

Return Value: "Return the handler for off-screen rendering events."

Threading Constraint: Threading constraint not specified in source.

`virtual CefRefPtr<CefRequestHandler> GetRequestHandler()`

Return Value: "Return the handler for browser request events."

Threading Constraint: Threading constraint not specified in source.

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

Parameters:

browser: The browser receiving the message.
frame: The frame targeted by the message.
source_process: CefProcessId of the sender (e.g. PID_RENDERER).
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: This is the browser-process counterpart to CefRenderProcessHandler::OnProcessMessageReceived. Inspect message->GetName() and dispatch. Send messages back via CefFrame::SendProcessMessage(PID_RENDERER, ...).

Threading Constraint: "Called when a new message is received from a different process." Per CEF convention, browser-process message handlers run on the IO thread unless explicitly redirected; consult cef_process_message.h for confirmation.

Usage Example

cpp

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

class MyClient : public CefClient,
                 public CefLifeSpanHandler,
                 public CefLoadHandler,
                 public CefDisplayHandler {
 public:
  // --- CefClient getters ---
  CefRefPtr<CefLifeSpanHandler> GetLifeSpanHandler() override { return this; }
  CefRefPtr<CefLoadHandler>    GetLoadHandler()    override { return this; }
  CefRefPtr<CefDisplayHandler> GetDisplayHandler() override { return this; }

  // --- CefLifeSpanHandler ---
  void OnAfterCreated(CefRefPtr<CefBrowser> b) override { browser_ = b; }
  void OnBeforeClose(CefRefPtr<CefBrowser> b) override { browser_ = nullptr; }

  // --- CefLoadHandler ---
  void OnLoadingStateChange(CefRefPtr<CefBrowser> b,
                            bool isLoading, bool canGoBack,
                            bool canGoForward) override {
    // update URL bar
  }

  // --- CefDisplayHandler ---
  void OnTitleChange(CefRefPtr<CefBrowser> b, const CefString& t) override {
    // update window title
  }

  // --- CefClient::OnProcessMessageReceived ---
  bool OnProcessMessageReceived(CefRefPtr<CefBrowser> b,
                                CefRefPtr<CefFrame> f,
                                CefProcessId src,
                                CefRefPtr<CefProcessMessage> m) override {
    if (m->GetName() == "renderer_to_browser") {
      // dispatch...
      return true;
    }
    return false;
  }

 private:
  CefRefPtr<CefBrowser> browser_;
  IMPLEMENT_REFCOUNTING(MyClient);
};

// Wire-up at browser-creation time:
CefBrowserHost::CreateBrowser(windowInfo, new MyClient(), url, settings,
                                /* extra_info */ nullptr,
                                /* request_context */ nullptr);

See Also