CefProcessMessage
Header: cef_process_message.h
Category: V8 & Process Messaging
Overview
JavaScript bridge, value tree, inter-process messages, shared memory regions.
CefProcessMessage
Source File: include/cef_process_message.h
Process / Thread Context: Any process, any thread (header: "Can be used on any process and thread.").
Purpose: Class representing an inter-process message. Created with a name and either an argument list (CefListValue) or a shared memory region; sent between the browser and renderer processes via CefFrame::SendProcessMessage / CefBrowser::SendProcessMessage and received via CefBrowserProcessHandler::OnProcessMessageReceived / CefRenderProcessHandler::OnProcessMessageReceived.
Methods
static CefRefPtr<CefProcessMessage> Create(const CefString& name)
Parameters:
name: The message name. Used by the receiving side to route the message.
Return Value: Returns a new CefProcessMessage instance. Use GetArgumentList() to populate it before sending.
Usage Instruction: Create, fill the argument list (or use CefSharedProcessMessageBuilder for shared memory payloads), then pass to a SendProcessMessage API.
Threading Constraint: Any process, any thread.
virtual bool IsValid()
Parameters:
- None.
Return Value: Returns true if this object is valid. Do not call any other methods if this returns false.
Usage Instruction: Defensive check after receiving a CefRefPtr<CefProcessMessage> from an external source.
Threading Constraint: Any thread.
virtual bool IsReadOnly()
Parameters:
- None.
Return Value: Returns true if the values of this object are read-only. Some APIs may expose read-only objects (e.g. a message received from the other process).
Usage Instruction: Check before attempting to mutate the argument list.
Threading Constraint: Any thread.
virtual CefRefPtr<CefProcessMessage> Copy()
Parameters:
- None.
Return Value: Returns a writable copy of this object. Returns nullptr when the message contains a shared memory region (shared-memory messages are not copyable).
Usage Instruction: Use to obtain a writable clone of a read-only received message before mutating it.
Threading Constraint: Any thread.
virtual CefString GetName()
Parameters:
- None.
Return Value: Returns the message name set at Create() time.
Usage Instruction: Use in OnProcessMessageReceived to dispatch on the message name.
Threading Constraint: Any thread.
virtual CefRefPtr<CefListValue> GetArgumentList()
Parameters:
- None.
Return Value: Returns the list of arguments. Returns nullptr when the message contains a shared memory region (i.e. it was built via CefSharedProcessMessageBuilder).
Usage Instruction: On the send side, use to set the per-message arguments. On the receive side, use to read them. A message has either an argument list or a shared memory region — never both.
Threading Constraint: Any thread.
virtual CefRefPtr<CefSharedMemoryRegion> GetSharedMemoryRegion()
Parameters:
- None.
Return Value: Returns the shared memory region. Returns nullptr when the message contains an argument list.
Usage Instruction: Use on the receive side to obtain a CefSharedMemoryRegion for zero-copy transfer of large payloads (e.g. images, audio buffers).
Threading Constraint: Any thread.
Usage Example
// === Send a simple list-based process message from the renderer ===
// In the render process:
void SendPing(CefRefPtr<CefBrowser> browser, int frame_id) {
CefRefPtr<CefProcessMessage> msg = CefProcessMessage::Create("ping");
CefRefPtr<CefListValue> args = msg->GetArgumentList();
args->SetInt(0, frame_id);
args->SetString(1, "hello from renderer");
browser->SendProcessMessage(PID_BROWSER, msg);
}
// In the browser process, CefBrowserProcessHandler::OnProcessMessageReceived
// (or CefClient::OnProcessMessageReceived):
bool OnProcessMessageReceived(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefFrame> frame,
CefProcessId source_process,
CefRefPtr<CefProcessMessage> msg) override {
if (msg->GetName() == "ping") {
CefRefPtr<CefListValue> args = msg->GetArgumentList();
LOG(INFO) << "frame_id=" << args->GetInt(0)
<< " text=" << args->GetString(1).ToString();
return true;
}
return false;
}