CefDevToolsMessageObserver

Header: cef_devtools_message_observer.h
Category: Browser Handlers

Overview

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

CefDevToolsMessageObserver

Source File: include/cef_devtools_message_observer.h

Process / Thread Context: Browser process / UI thread ("methods of this class will be called on the browser process UI thread"). USER-IMPLEMENTED (source=client); not returned from CefClient — instead registered with CefBrowserHost::AddDevToolsMessageObserver(), which returns a CefRegistration that keeps the observer alive until destroyed.

Purpose: Observe DevTools protocol messages — raw message receipt, structured method-result delivery, event delivery, and agent attach/detach lifecycle events.

Methods

bool OnDevToolsMessage(CefRefPtr<CefBrowser> browser, const void* message, size_t message_size)

Parameters:

• browser: Originating browser.
• message: UTF-8 JSON dictionary (method result or event); valid only for the scope of the callback.
• message_size: Size in bytes.

Return Value: true = message handled (skip further dispatch); false = continue to OnDevToolsMethodResult / OnDevToolsEvent as appropriate.

Usage Instruction: Method-result dictionaries contain id (int) and optionally result or error. Event dictionaries contain method (string) and optionally params. Use CefParseJSON if parsing needed; beware performance on >1MB messages.

Threading Constraint: Browser process UI thread per class comment.

void OnDevToolsMethodResult(CefRefPtr<CefBrowser> browser, int message_id, bool success, const void* result, size_t result_size)

Parameters:

• browser: Originating browser.
• message_id: The id of the originating method call from SendDevToolsMessage.
• success: true = result is the JSON result dict; false = result is the JSON error dict.
• result: UTF-8 JSON dictionary bytes; valid only during callback; may be empty. Optional param.
• result_size: Size of result.

Return Value: None.

Usage Instruction: Receive structured results of ExecuteDevToolsMethod / SendDevToolsMessage.

Threading Constraint: Browser process UI thread per class comment.

void OnDevToolsEvent(CefRefPtr<CefBrowser> browser, const CefString& method, const void* params, size_t params_size)

Parameters:

• browser: Originating browser.
• method: The method string from the event dictionary.
• params: UTF-8 JSON params dictionary; valid only during callback; may be empty. Optional.
• params_size: Size of params.

Return Value: None.

Usage Instruction: Receive DevTools events (e.g. Page.frameNavigated).

Threading Constraint: Browser process UI thread per class comment.

void OnDevToolsAgentAttached(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: Originating browser.

Return Value: None.

Usage Instruction: Called when the DevTools agent attaches (generally after the first message sent while detached).

Threading Constraint: Browser process UI thread per class comment.

void OnDevToolsAgentDetached(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: Originating browser.

Return Value: None.

Usage Instruction: Called when the agent detaches; pending method results will not be delivered; active event subscriptions are canceled.

Threading Constraint: Browser process UI thread per class comment.

Usage Example

class MyDevToolsObserver : public CefDevToolsMessageObserver {
 public:
  void OnDevToolsAgentAttached(CefRefPtr<CefBrowser> browser) override {
    // Subscribe to Page events:
    browser->GetHost()->ExecuteDevToolsMethod(
        0, "Page.enable", CefDictionaryValue::Create());
  }
  void OnDevToolsEvent(CefRefPtr<CefBrowser> browser,
                       const CefString& method,
                       const void* params, size_t params_size) override {
    if (method == "Page.frameNavigated") {
      // Parse params, log navigation
    }
  }
  void OnDevToolsAgentDetached(CefRefPtr<CefBrowser>) override {}
  bool OnDevToolsMessage(CefRefPtr<CefBrowser>, const void*, size_t) override {
    return false;  // Continue to OnDevToolsMethodResult/OnDevToolsEvent
  }
  void OnDevToolsMethodResult(CefRefPtr<CefBrowser>, int, bool,
                              const void*, size_t) override {}
  IMPLEMENT_REFCOUNTING(MyDevToolsObserver);
};

// Registration is NOT via CefClient. Instead, after browser creation:
//   CefRefPtr<CefRegistration> reg =
//       browser->GetHost()->AddDevToolsMessageObserver(new MyDevToolsObserver);
// Hold `reg` for the lifetime the observer should remain active; destroying
// `reg` unregisters the observer.