CefStreamReader

Header: cef_stream.h
Interfaces: CefReadHandler, CefStreamReader, CefWriteHandler, CefStreamWriter
Category: System Utilities

Overview

Tasks, threads, parsers, streams, cookies, URL requests, scheme registration, and constant tables.

CefReadHandler

Source File: include/cef_stream.h

Process / Thread Context: Any thread (header: "The methods of this class may be called on any thread.").

Purpose: Interface the client can implement to provide a custom stream reader. Used to back a CefStreamReader created via CefStreamReader::CreateForHandler().

Methods

size_t Read(void* ptr, size_t size, size_t n)

Parameters:

• ptr: Destination buffer.
• size: Size of each element to read.
• n: Number of elements to read.

Return Value: Returns the number of elements actually read (fread-style). A short read indicates end-of-stream or failure.

Usage Instruction: Implement to copy up to size * n bytes from your data source into ptr. Match fread semantics.

Threading Constraint: Any thread.

int Seek(int64_t offset, int whence)

Parameters:

• offset: Byte offset (interpretation depends on whence).
• whence: One of SEEK_CUR, SEEK_END, SEEK_SET.

Return Value: Returns zero on success, non-zero on failure (fseek-style).

Usage Instruction: Implement to support random access. If your source is non-seekable, return non-zero.

Threading Constraint: Any thread.

int64_t Tell()

Parameters:

• None.

Return Value: Returns the current offset position in bytes from the start.

Usage Instruction: Implement to report the current position.

Threading Constraint: Any thread.

int Eof()

Parameters:

• None.

Return Value: Returns non-zero if at end of file, zero otherwise.

Usage Instruction: Implement to allow callers to detect end-of-stream.

Threading Constraint: Any thread.

bool MayBlock()

Parameters:

• None.

Return Value: Returns true if this handler performs work like accessing the file system which may block. Used as a hint for determining the thread to access the handler from.

Usage Instruction: Return true for I/O-bound sources (files, sockets), false for in-memory sources. CEF uses this hint to dispatch reads on an appropriate thread.

Threading Constraint: Any thread.

Usage Example

// === Custom reader that wraps an in-memory std::string ===
class StringReadHandler : public CefReadHandler {
 public:
  explicit StringReadHandler(std::string data) : data_(std::move(data)) {}
  size_t Read(void* ptr, size_t size, size_t n) override {
    size_t want = size * n;
    size_t have = data_.size() - pos_;
    size_t copy = std::min(want, have);
    if (copy) { memcpy(ptr, data_.data() + pos_, copy); pos_ += copy; }
    return size ? copy / size : 0;
  }
  int Seek(int64_t off, int whence) override {
    int64_t base = (whence == SEEK_SET) ? 0 :
                   (whence == SEEK_CUR) ? pos_ :
                   (int64_t)data_.size();
    int64_t np = base + off;
    if (np < 0 || (size_t)np > data_.size()) return -1;
    pos_ = (size_t)np;
    return 0;
  }
  int64_t Tell() override { return (int64_t)pos_; }
  int Eof() override { return pos_ >= data_.size() ? 1 : 0; }
  bool MayBlock() override { return false; }
 private:
  std::string data_;
  size_t pos_ = 0;
  IMPLEMENT_REFCOUNTING(StringReadHandler);
};

// CefRefPtr<CefStreamReader> reader =
//     CefStreamReader::CreateForHandler(new StringReadHandler("hello"));

CefStreamReader

Source File: include/cef_stream.h

Process / Thread Context: Any thread (header: "The methods of this class may be called on any thread.").

Purpose: Class used to read data from a stream. Created from a file path, an in-memory buffer, or a custom CefReadHandler. Used throughout CEF wherever a stream source is needed (e.g. CefBrowser::GetSource via a string visitor, CefZipArchive::Read, custom resource handler bodies).

Methods

static CefRefPtr<CefStreamReader> CreateForFile(const CefString& fileName)

Parameters:

• fileName: Path to a file to open for reading.

Return Value: Returns a new CefStreamReader reading from the file, or nullptr on failure.

Usage Instruction: Use for reading static file resources.

Threading Constraint: Any thread.

static CefRefPtr<CefStreamReader> CreateForData(void* data, size_t size)

Parameters:

• data: Pointer to the in-memory buffer.
• size: Number of valid bytes at data.

Return Value: Returns a new CefStreamReader backed by the supplied buffer.

Usage Instruction: Use for reading from a pre-loaded buffer. CEF takes a reference to the buffer; lifetime is the responsibility of the caller until the reader is destroyed.

Threading Constraint: Any thread.

static CefRefPtr<CefStreamReader> CreateForHandler(CefRefPtr<CefReadHandler> handler)

Parameters:

• handler: A custom CefReadHandler implementation.

Return Value: Returns a new CefStreamReader backed by handler.

Usage Instruction: Use to plug arbitrary data sources into APIs that accept a CefRefPtr<CefStreamReader>.

Threading Constraint: Any thread.

virtual size_t Read(void* ptr, size_t size, size_t n)

Parameters:

• As for CefReadHandler::Read.

Return Value: Returns the number of elements actually read.

Usage Instruction: Read raw binary data through the stream.

Threading Constraint: Any thread.

virtual int Seek(int64_t offset, int whence)

Parameters:

• As for CefReadHandler::Seek.

Return Value: Returns zero on success and non-zero on failure.

Usage Instruction: Random access.

Threading Constraint: Any thread.

virtual int64_t Tell()

Parameters:

• None.

Return Value: Returns the current offset position.

Usage Instruction: Use to record progress for resume logic.

Threading Constraint: Any thread.

virtual int Eof()

Parameters:

• None.

Return Value: Returns non-zero if at end of file.

Usage Instruction: Use to terminate read loops.

Threading Constraint: Any thread.

virtual bool MayBlock()

Parameters:

• None.

Return Value: Returns true if this reader performs work like accessing the file system which may block. Used as a hint for determining the thread to access the reader from.

Usage Instruction: Use to decide whether to dispatch stream operations on a worker thread.

Threading Constraint: Any thread.

Usage Example

// === Three different ways to build a CefStreamReader ===
CefRefPtr<CefStreamReader> file_reader =
    CefStreamReader::CreateForFile("/path/to/resource.dat");

std::vector<uint8_t> buffer = LoadAsset();
CefRefPtr<CefStreamReader> mem_reader =
    CefStreamReader::CreateForData(buffer.data(), buffer.size());

CefRefPtr<CefStreamReader> custom_reader =
    CefStreamReader::CreateForHandler(new StringReadHandler("hello world"));

CefWriteHandler

Source File: include/cef_stream.h

Process / Thread Context: Any thread (header: "The methods of this class may be called on any thread.").

Purpose: Interface the client can implement to provide a custom stream writer. Used to back a CefStreamWriter created via CefStreamWriter::CreateForHandler().

Methods

size_t Write(const void* ptr, size_t size, size_t n)

Parameters:

• ptr: Source buffer.
• size: Size of each element to write.
• n: Number of elements to write.

Return Value: Returns the number of elements actually written (fwrite-style). A short write indicates the destination cannot accept more data.

Usage Instruction: Implement to copy size * n bytes from ptr into your sink.

Threading Constraint: Any thread.

int Seek(int64_t offset, int whence)

Parameters:

• As for CefReadHandler::Seek.

Return Value: Returns zero on success, non-zero on failure.

Usage Instruction: Implement to support random access for seekable sinks.

Threading Constraint: Any thread.

int64_t Tell()

Parameters:

• None.

Return Value: Returns the current offset position.

Usage Instruction: Implement to report the current write position.

Threading Constraint: Any thread.

int Flush()

Parameters:

• None.

Return Value: Returns zero on success, non-zero on failure (fflush-style).

Usage Instruction: Implement to force any buffered data to the underlying sink (e.g. fsync, network flush).

Threading Constraint: Any thread.

bool MayBlock()

Parameters:

• None.

Return Value: Returns true if this handler performs work that may block (e.g. file I/O).

Usage Instruction: Return true for I/O-bound sinks.

Threading Constraint: Any thread.

Usage Example

// === Custom writer that accumulates bytes into a std::string ===
class StringWriteHandler : public CefWriteHandler {
 public:
  size_t Write(const void* ptr, size_t size, size_t n) override {
    size_t bytes = size * n;
    buf_.append(static_cast<const char*>(ptr), bytes);
    return size ? bytes / size : 0;
  }
  int Seek(int64_t, int) override { return -1; }  // not seekable
  int64_t Tell() override { return (int64_t)buf_.size(); }
  int Flush() override { return 0; }
  bool MayBlock() override { return false; }

  const std::string& buffer() const { return buf_; }
 private:
  std::string buf_;
  IMPLEMENT_REFCOUNTING(StringWriteHandler);
};

// CefRefPtr<CefStreamWriter> writer =
//     CefStreamWriter::CreateForHandler(new StringWriteHandler());

CefStreamWriter

Source File: include/cef_stream.h

Process / Thread Context: Any thread (header: "The methods of this class may be called on any thread.").

Purpose: Class used to write data to a stream. Created from a file path or a custom CefWriteHandler. Used by APIs that accept a CefRefPtr<CefStreamWriter> (e.g. CefBrowser::PrintToPDF callback, save-as patterns).

Methods

static CefRefPtr<CefStreamWriter> CreateForFile(const CefString& fileName)

Parameters:

• fileName: Path to a file to open for writing.

Return Value: Returns a new CefStreamWriter writing to the file, or nullptr on failure.

Usage Instruction: Use for writing downloaded or generated content directly to disk.

Threading Constraint: Any thread.

static CefRefPtr<CefStreamWriter> CreateForHandler(CefRefPtr<CefWriteHandler> handler)

Parameters:

• handler: A custom CefWriteHandler implementation.

Return Value: Returns a new CefStreamWriter backed by handler.

Usage Instruction: Use to plug arbitrary sinks (network, in-memory, database) into APIs that accept a CefRefPtr<CefStreamWriter>.

Threading Constraint: Any thread.

virtual size_t Write(const void* ptr, size_t size, size_t n)

Parameters:

• As for CefWriteHandler::Write.

Return Value: Returns the number of elements actually written.

Usage Instruction: Write raw binary data through the stream.

Threading Constraint: Any thread.

virtual int Seek(int64_t offset, int whence)

Parameters:

• As for CefReadHandler::Seek.

Return Value: Returns zero on success and non-zero on failure.

Usage Instruction: Random access for seekable sinks.

Threading Constraint: Any thread.

virtual int64_t Tell()

Parameters:

• None.

Return Value: Returns the current offset position.

Usage Instruction: Use to record the current write position.

Threading Constraint: Any thread.

virtual int Flush()

Parameters:

• None.

Return Value: Returns zero on success, non-zero on failure.

Usage Instruction: Force any buffered data to the underlying sink.

Threading Constraint: Any thread.

virtual bool MayBlock()

Parameters:

• None.

Return Value: Returns true if this writer performs work like accessing the file system which may block.

Usage Instruction: Use to decide whether to dispatch stream operations on a worker thread.

Threading Constraint: Any thread.

Usage Example

// === Write a downloaded file to disk and an in-memory buffer ===
CefRefPtr<CefStreamWriter> disk =
    CefStreamWriter::CreateForFile("/tmp/output.bin");

const char kData[] = "hello";
disk->Write(kData, 1, sizeof(kData));
disk->Flush();

// Use a custom handler to also accumulate the bytes in memory:
CefRefPtr<StringWriteHandler> handler = new StringWriteHandler();
CefRefPtr<CefStreamWriter> mem = CefStreamWriter::CreateForHandler(handler);
mem->Write(kData, 1, sizeof(kData));
// handler->buffer() now contains "hello".