Table of Contents

Bodu.IO.Compound Namespace

Package

Bodu.IO.Compound

Purpose

Bodu.IO.Compound is a reader and writer for the OLE2 / Compound File Binary (CFB) container format - the structured-storage envelope used by legacy Microsoft Office documents (.xls, .doc, .ppt, .msg) and other technologies. It opens existing containers, exposing the embedded storage hierarchy and the raw byte payload of each named stream, and it authors new ones. It carries no application-format knowledge of its own: interpreting a Workbook or WordDocument stream is the caller's job.

A compound file is effectively a small file system embedded in a single file. CompoundFile is the managed counterpart of the COM StgOpenStorage / StgCreateStorageEx entry points: navigation begins at the root storage and descends through nested storages (IStorage) to stream leaves (IStream). The narrow BIFF8 .xls reader in ExcelBinaryWorkbook is the worked example of a format reader layered on top.

The public surface spans three namespaces: Bodu.IO.Compound (the reader, the in-place writer, and the value model), Bodu.IO.Compound.Builders (the detached authoring object model), and Bodu.IO.Compound.PropertySets (the OLE property-set readers and writers).

Static documentation

Key types

Container - Bodu.IO.Compound

  • CompoundFile - the container session. Read factories Open / OpenRead (path / Stream, with a buffered-vs-streaming choice) and IsCompoundFile; write factory Create; instance RootStorage, Access / CanRead / CanWrite / IsDirty, Commit / Revert and the asynchronous CommitAsync / FlushAsync, the TryGetSummaryInformation / TryGetDocumentSummaryInformation property-set readers, and their SetSummaryInformation / SetDocumentSummaryInformation write counterparts.
  • CompoundStorage - a storage node. Read: EnumerateEntries / EnumerateStorages / EnumerateStreams, OpenStorage / OpenStream and their TryOpen… forms, TryOpenPropertySet. Write (on a writable file): CreateStorage, CreateStream, Delete, Rename, WritePropertySet, and the settable entry metadata ClassId / CreationTime / ModifiedTime / StateBits.
  • CompoundStream - a stream node and seekable Stream in one. ReadAllBytes / AsMemory, the standard Read / Seek, and a ReadAsync that is truly asynchronous over a streaming-mode cursor; Write / SetLength / Flush on a writable cursor (payloads capped at int.MaxValue).
  • CompoundEntryInfo - an immutable directory-entry snapshot (Name, EntryType, Length, ClassId, timestamps). CompoundEntryType, CompoundEntryColor - the entry kind and red-black node color.

Read options

Authoring - Bodu.IO.Compound.Builders

Property sets - Bodu.IO.Compound.PropertySets

Errors

Example

using Bodu.IO.Compound;

// Read: open, navigate, and read a named stream.
using CompoundFile file = CompoundFile.Open(File.OpenRead("book.xls"));
CompoundStream workbook = file.RootStorage.OpenStream("Workbook");
byte[] bytes = workbook.ReadAllBytes();

using Bodu.IO.Compound.Builders;

// Write: assemble a container from scratch and serialize it.
var root = CompoundStorageBuilder.CreateRoot();
root.AddStream("Workbook", workbookBytes);
CompoundStorageBuilder storage = root.AddStorage("Storage 1");
storage.AddStream("Nested", new byte[] { 1, 2, 3 });

root.Save("out.xls");   // or ToArray() / WriteTo(stream)

Notes

  • Two ways to read. CompoundFileOptions selects between fully buffered access (the whole source is read into memory at open time - the default, and safe to share across threads) and streaming access (sectors are read on demand from a seekable source, bounding memory for large files). The Auto strategy switches on MaxBufferedBytes.
  • Two ways to write. The detached CompoundStorageBuilder assembles a tree in memory and serializes it once (Save / WriteTo / ToArray) - ideal for authoring a container from scratch. The in-place Create path returns a writable file whose RootStorage.CreateStream / CreateStorage mutate a staging tree that Commit (or the asynchronous CommitAsync / FlushAsync) persists to the destination. A writable CompoundStream is a true read-write Stream (CanWrite is true).
  • Names. Entry names are at most 31 UTF-16 code units, non-empty, and free of / and null characters; comparison is case-insensitive by default (per the CFB format). Duplicate names and invalid names throw CompoundFileSerializationException at author time.
  • Versions. V3 (512-byte sectors) is the most compatible default; V4 (4096-byte sectors) suits larger containers. Choose via CompoundBuildOptions.
  • Property sets round-trip. On a writable file, CompoundFile.SetSummaryInformation embeds a summary set and CompoundFile.TryGetSummaryInformation reads it back; CompoundStorage.WritePropertySet does the same for any named set. The writer emits every value shape the reader parses, including vector properties (variant vectors round-trip by value, not byte, identity).
  • See also: the introduction, core concepts, and getting-started; the reading, authoring, and property-set guides; and the Bodu.Formats.Excel.Binary reader built on this package.

Namespaces

Bodu.IO.Compound.Builders
Bodu.IO.Compound.PropertySets

Classes

CompoundEntryInfo

Provides an immutable snapshot of the metadata recorded for a single compound-file directory entry - a storage, a stream, or the root storage.

CompoundFile

Represents an OLE2 / Compound File Binary (CFB) container opened over a path or stream, exposing its storage hierarchy, the metadata of every entry, and the byte payload of each named stream for reading or editing.

CompoundFileException

The base class for exceptions raised by the compound-file reader, writer, and object model.

CompoundFileFormatException

The exception thrown when a stream cannot be interpreted as a well-formed OLE2 / Compound File Binary container.

CompoundFileOptions

Specifies options that control how a CompoundFile is opened for reading.

CompoundFileSerializationException

The exception thrown when a compound file cannot be authored or serialized - for example, when a storage contains a duplicate or invalid child name, the directory nesting is too deep, or a value cannot be represented in the container.

CompoundStorage

Represents a storage within a compound file - a named container of child storages and streams - and provides navigation over its immediate children.

CompoundStream

Provides seekable access to the bytes of a single stream within a compound file.

CompoundStreamNotFoundException

The exception thrown when a named stream is requested from a compound file but no matching directory entry exists.

Enums

CompoundEntryColor

Identifies the red-black tree node color recorded for a directory entry.

CompoundEntryType

Identifies the kind of object an entry describes within a compound file's directory.

CompoundFileError

Categorizes the structural failure that caused a CompoundFileFormatException.

CompoundFileVersion

Specifies the compound-file format version, which determines the sector size used when writing.

CompoundReadStrategy

Specifies how the compound-file reader sources the bytes of an opened container.

CompoundValidationLevel

Specifies how strictly the compound-file reader validates a container's structure.