CefValue

Header: cef_values.h
Interfaces: CefValue, CefBinaryValue, CefDictionaryValue, CefListValue
Category: V8 & Process Messaging

Overview

JavaScript bridge, value tree, inter-process messages, shared memory regions.

CefValue

Source File: include/cef_values.h

Process / Thread Context: Any process / any thread (header explicitly states "Can be used on any process and thread.")

Purpose: A polymorphic scalar-or-container wrapper around a single typed value. Complex types (binary, dictionary, list) are referenced but not owned by the value object — so a CefValue obtained from another object can become invalid when the original owner is modified or destroyed.

Methods

static CefRefPtr<CefValue> Create()

Parameters:

• (none)

Return Value: New standalone CefValue reference (owned by caller). Initial type is VTYPE_NULL (per framework convention).

Usage Instruction: Factory entry point. Allocate fresh values with this before populating them with Set*().

Threading Constraint: Any process / any thread.

virtual bool IsValid()

Parameters:

• (none)

Return Value: true if the underlying data is still valid (always true for simple types). For complex types, becomes false if the parent that owns the data was modified/destroyed.

Usage Instruction: Defensive check before using references obtained from a parent dictionary/list.

Threading Constraint: Any thread.

virtual bool IsOwned()

Parameters:

• (none)

Return Value: true if the underlying data is owned by another object (i.e. this CefValue is a view, not an owner).

Usage Instruction: Decide whether to Copy() before mutation.

Threading Constraint: Any thread.

virtual bool IsReadOnly()

Parameters:

• (none)

Return Value: true when the underlying data is read-only (some APIs expose read-only views).

Usage Instruction: Check before attempting Set*() calls.

Threading Constraint: Any thread.

virtual bool IsSame(CefRefPtr<CefValue> that)

Parameters:

• that: another value reference to compare with.

Return Value: true if both objects share the same underlying data — modifications via one will affect the other.

Usage Instruction: Alias / identity test, not deep equality.

Threading Constraint: Any thread.

virtual bool IsEqual(CefRefPtr<CefValue> that)

Parameters:

• that: another value reference.

Return Value: true if values are equivalent but not necessarily the same object.

Usage Instruction: Deep value comparison (structural equality).

Threading Constraint: Any thread.

virtual CefRefPtr<CefValue> Copy()

Parameters:

• (none)

Return Value: A new CefValue whose underlying data has been duplicated.

Usage Instruction: Produce an independent mutable copy.

Threading Constraint: Any thread.

virtual CefValueType GetType()

Parameters:

• (none)

Return Value: One of VTYPE_INVALID, VTYPE_NULL, VTYPE_BOOL, VTYPE_INT, VTYPE_DOUBLE, VTYPE_STRING, VTYPE_BINARY, VTYPE_DICTIONARY, VTYPE_LIST. Default C-API retval is VTYPE_INVALID.

Usage Instruction: Switch on this before calling Get*() to avoid type-coercion surprises.

Threading Constraint: Any thread.

virtual bool GetBool() / virtual int GetInt() / virtual double GetDouble() / virtual CefString GetString()

Parameters:

• (none)

Return Value: The underlying scalar converted to the requested type (0 / empty string if mismatched).

Usage Instruction: Quick type-coercing accessors for scalar values.

Threading Constraint: Any thread.

virtual CefRefPtr<CefBinaryValue> GetBinary()

Parameters:

• (none)

Return Value: Reference to the underlying binary value, which may become invalid if the value is owned elsewhere or transferred.

Usage Instruction: To retain a stable reference after assigning to a dictionary/list, pass the CefValue (not the binary) via SetValue(); the framework preserves the link.

Threading Constraint: Any thread.

virtual CefRefPtr<CefDictionaryValue> GetDictionary()

Parameters:

• (none)

Return Value: Dictionary reference (same ownership caveat as GetBinary()).

Usage Instruction: Same pattern — keep the CefValue alive if you need long-lived access.

Threading Constraint: Any thread.

virtual CefRefPtr<CefListValue> GetList()

Parameters:

• (none)

Return Value: List reference (same ownership caveat as GetBinary()).

Usage Instruction: Same pattern.

Threading Constraint: Any thread.

virtual bool SetNull() / SetBool(bool) / SetInt(int) / SetDouble(double) / SetString(const CefString&)

Parameters:

• value: scalar to store (SetString accepts an empty string as null due to optional_param).

Return Value: true if the value was set successfully.

Usage Instruction: Replace the underlying value with a scalar of the corresponding type.

Threading Constraint: Any thread.

virtual bool SetBinary(CefRefPtr<CefBinaryValue> value)

Parameters:

• value: binary value to reference (this object keeps a reference; ownership of underlying data unchanged).

Return Value: true on success.

Usage Instruction: Wrap an existing CefBinaryValue without transferring ownership.

Threading Constraint: Any thread.

virtual bool SetDictionary(CefRefPtr<CefDictionaryValue> value)

Parameters:

• value: dictionary to reference (keeps a reference; ownership unchanged).

Return Value: true on success.

Usage Instruction: Wrap an existing dictionary without transferring ownership.

Threading Constraint: Any thread.

virtual bool SetList(CefRefPtr<CefListValue> value)

Parameters:

• value: list to reference (keeps a reference; ownership unchanged).

Return Value: true on success.

Usage Instruction: Wrap an existing list without transferring ownership.

Threading Constraint: Any thread.

Usage Example

// Build a configuration dictionary entirely from CefValue primitives.
CefRefPtr<CefDictionaryValue> config = CefDictionaryValue::Create();
config->SetString("url", "https://example.com");
config->SetInt("timeout_ms", 5000);
config->SetBool("verify_ssl", true);

// Wrap it in a CefValue (used by JSON parser / IPC payloads).
CefRefPtr<CefValue> root = CefValue::Create();
root->SetDictionary(config);

// Serialize to JSON via the parser header (see cef_parser.h).
CefString json = CefWriteJSON(root, JSON_WRITER_DEFAULT);

// Read back: structural equality, then a deep copy before mutating.
CefRefPtr<CefValue> parsed = CefParseJSON(json, JSON_PARSER_RFC);
if (parsed && parsed->GetType() == VTYPE_DICTIONARY) {
  CefRefPtr<CefDictionaryValue> dict = parsed->GetDictionary();
  if (dict->HasKey("timeout_ms")) {
    int ms = dict->GetInt("timeout_ms");
  }
}

// Make an independent mutable copy of the original config.
CefRefPtr<CefValue> clone = root->Copy();
clone->GetDictionary()->SetInt("timeout_ms", 10000);
// 'config' is unaffected because Copy() duplicated the data.

CefBinaryValue

Source File: include/cef_values.h

Process / Thread Context: Any process / any thread ("Can be used on any process and thread.")

Purpose: A reference-counted wrapper around a contiguous byte buffer. The buffer is copied on Create(), but when a CefBinaryValue is stored inside a CefDictionaryValue/CefListValue, ownership transfers to the parent and the original reference becomes invalid.

Methods

static CefRefPtr<CefBinaryValue> Create(const void* data, size_t data_size)

Parameters:

• data: source bytes to copy; data_size: number of bytes.

Return Value: New standalone binary value; the input data is copied.

Usage Instruction: Allocate an owned byte buffer.

Threading Constraint: Any thread.

virtual bool IsValid()

Parameters:

• (none)

Return Value: false once the underlying buffer has been invalidated (e.g. owner destroyed) — caller must not invoke any other method afterwards.

Usage Instruction: Always check after retrieving from a parent that may have been mutated.

Threading Constraint: Any thread.

virtual bool IsOwned()

Parameters:

• (none)

Return Value: true if currently owned by another object (parent dictionary/list).

Usage Instruction: Decide whether to Copy() before mutation.

Threading Constraint: Any thread.

virtual bool IsSame(CefRefPtr<CefBinaryValue> that)

Parameters:

• that: another binary reference.

Return Value: true if both share the same underlying buffer.

Threading Constraint: Any thread.

virtual bool IsEqual(CefRefPtr<CefBinaryValue> that)

Parameters:

• that: another binary reference.

Return Value: true if byte contents are equivalent.

Threading Constraint: Any thread.

virtual CefRefPtr<CefBinaryValue> Copy()

Parameters:

• (none)

Return Value: A new binary value whose data is a deep copy.

Threading Constraint: Any thread.

virtual const void* GetRawData()

Parameters:

• (none)

Return Value: Pointer to the start of the buffer, valid only as long as the CefBinaryValue is alive.

Usage Instruction: Fast zero-copy read for callers that keep the parent reference alive.

Threading Constraint: Any thread.

virtual size_t GetSize()

Parameters:

• (none)

Return Value: Size of the buffer in bytes.

Threading Constraint: Any thread.

virtual size_t GetData(void* buffer, size_t buffer_size, size_t data_offset)

Parameters:

• buffer: destination; buffer_size: capacity of destination; data_offset: starting byte offset in the source.

Return Value: Number of bytes actually copied (≤ min(buffer_size, size-offset)).

Usage Instruction: Range-based read into a caller-supplied buffer.

Threading Constraint: Any thread.

Usage Example

// Decode a base64 string into a binary blob and stream-copy the bytes out.
CefRefPtr<CefBinaryValue> bin = CefBase64Decode("SGVsbG8gd29ybGQ=");
if (bin && bin->IsValid()) {
  std::vector<uint8_t> out(bin->GetSize());
  bin->GetData(out.data(), out.size(), 0);

  // Use the raw pointer for a no-copy hot path:
  const void* raw = bin->GetRawData();  // valid while 'bin' is alive.
}

// Embed binary in a dictionary — note that 'bin' is invalidated by the transfer.
CefRefPtr<CefDictionaryValue> dict = CefDictionaryValue::Create();
CefRefPtr<CefBinaryValue> owned = CefBinaryValue::Create(out.data(), out.size());
dict->SetBinary("payload", owned);  // 'owned' may be invalidated if not already owned.

CefDictionaryValue

Source File: include/cef_values.h

Process / Thread Context: Any process / any thread ("Can be used on any process and thread.")

Purpose: An ordered string-keyed map. Values may be of any CefValueType. Complex children (binary, dictionary, list) are referenced rather than copied when retrieved via the Get*() accessors, so mutations to a retrieved child propagate back to this dictionary.

Methods

static CefRefPtr<CefDictionaryValue> Create()

Parameters:

• (none)

Return Value: New standalone (caller-owned) empty dictionary.

Threading Constraint: Any thread.

virtual bool IsSame(CefRefPtr<CefDictionaryValue> that)

Return Value: true if both share underlying data. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool IsEqual(CefRefPtr<CefDictionaryValue> that)

Return Value: structural equality. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefDictionaryValue> Copy(bool exclude_empty_children)

Parameters:

• exclude_empty_children: if true, empty sub-dictionaries / sub-lists are omitted from the copy.

Return Value: Writable deep copy.

Threading Constraint: Any thread.

virtual size_t GetSize()

Return Value: number of keys. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool Clear()

Return Value: remove all values, returns true on success. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool HasKey(const CefString& key)

Return Value: true if key exists. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool GetKeys(KeyList& keys)

Return Value: fills std::vector<CefString> with all keys. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool Remove(const CefString& key)

Return Value: removes one key, returns true if removed. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefValueType GetType(const CefString& key)

Return Value: type at key or VTYPE_INVALID. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefValue> GetValue(const CefString& key)

Parameters:

• key: dictionary key.

Return Value: A CefValue view of the entry. For simple types the data is copied (mutations do not affect this dictionary); for complex types the data is referenced (mutations do affect this dictionary).

Threading Constraint: Any thread.

virtual bool GetBool(const CefString&) / int GetInt(...) / double GetDouble(...) / CefString GetString(...) / CefRefPtr<CefBinaryValue> GetBinary(...) / CefRefPtr<CefDictionaryValue> GetDictionary(...) / CefRefPtr<CefListValue> GetList(...)

Parameters:

• key whose value to retrieve.

Return Value: The value coerced/typed — complex types share data with this dictionary.

Threading Constraint: Any thread.

virtual bool SetValue(const CefString& key, CefRefPtr<CefValue> value)

Parameters:

• key: entry key; value: a CefValue to store (simple → copied; complex → referenced and shared).

Return Value: true on success.

Threading Constraint: Any thread.

virtual bool SetBinary(const CefString& key, CefRefPtr<CefBinaryValue> value)

Parameters:

• value: binary value. If value is currently owned by another object → it is copied (the reference is unchanged). If value is standalone → ownership transfers and the caller's reference is invalidated.

Return Value: true on success.

Threading Constraint: Any thread.

Usage Example

// Build a nested configuration tree.
CefRefPtr<CefDictionaryValue> root = CefDictionaryValue::Create();
root->SetString("name", "Alice");
root->SetInt("age", 30);

CefRefPtr<CefListValue> tags = CefListValue::Create();
tags->SetString(0, "admin");
tags->SetString(1, "developer");
root->SetList("tags", tags);  // ownership of 'tags' may transfer.

// Iterate keys.
CefDictionaryValue::KeyList keys;
root->GetKeys(keys);
for (const auto& k : keys) {
  CefValueType t = root->GetType(k);
  // ... switch on t, dispatch to GetBool/GetInt/...
}

// Copy without empty sub-containers:
CefRefPtr<CefDictionaryValue> slim = root->Copy(/*exclude_empty_children=*/true);

CefListValue

Source File: include/cef_values.h

Process / Thread Context: Any process / any thread ("Can be used on any process and thread.")

Purpose: An integer-indexed, growable list of CefValue entries. Semantics mirror CefDictionaryValue but with size_t indices instead of string keys; SetSize() expands the list filling new slots with VTYPE_NULL.

Methods

static CefRefPtr<CefListValue> Create()

Return Value: empty standalone list. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefListValue> Copy()

Return Value: writable deep copy (no exclude_empty_children flag here). Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool SetSize(size_t size)

Parameters:

• size: desired length.

Return Value: true on success. New slots are VTYPE_NULL; shrunk slots are dropped.

Threading Constraint: Any thread.

virtual size_t GetSize()

Return Value: current length. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool Clear()

Return Value: remove all entries. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool Remove(size_t index)

Return Value: removes the entry at index. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefValueType GetType(size_t index)

Return Value: type at slot or VTYPE_INVALID. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual CefRefPtr<CefValue> GetValue(size_t index)

Return Value: typed view; simple→copy, complex→reference. Any thread.

Threading Constraint: Threading constraint not specified in source.

virtual bool SetValue(size_t index, CefRefPtr<CefValue> value)

Return Value: store a CefValue (simple copied, complex referenced). Any thread.

Threading Constraint: Threading constraint not specified in source.

Usage Example

// Round-trip an IPC payload through CefListValue.
CefRefPtr<CefListValue> args = CefListValue::Create();
args->SetString(0, "click");
args->SetInt(1, /*x=*/120);
args->SetInt(2, /*y=*/45);
args->SetBool(3, /*shift=*/false);

// Send via a CefProcessMessage (see cef_process_message.h):
CefRefPtr<CefProcessMessage> msg = CefProcessMessage::Create("Input");
msg->GetArgumentList()->SetList(0, args);

// On the receiving side, retrieve and walk:
CefRefPtr<CefListValue> recv = msg->GetArgumentList()->GetList(0);
for (size_t i = 0; i < recv->GetSize(); ++i) {
  switch (recv->GetType(i)) {
    case VTYPE_STRING: /* ... */ break;
    case VTYPE_INT:    /* ... */ break;
    case VTYPE_BOOL:   /* ... */ break;
    default: break;
  }
}