Bodu.IO.Pst 1.3.0

Bodu.IO.Pst

API stability - Stable. The public API surface is committed: breaking changes are reserved for a major-version bump per SemVer, except a deliberate break that is recorded in the release notes and in the package's CompatibilitySuppressions.xml. See versioning and support.

A low-level, read-only container library for the Outlook personal-folders format (PST, MS-PST). It reads the node database (NDB) layer of a Unicode- or ANSI-format file - the header, the node and block B-trees, block data with the format's permute and cyclic content encodings decoded and checksums verified, multi-block data trees, and per-node subnode trees - and the LTP (Lists, Tables, Properties) layer over it: each node's heap-on-node, BTree-on-heap, and the property-context and table-context views with wire-typed values.

This is the substrate a message-level reader builds on - the same layering as Bodu.IO.Compound beneath the .msg reader. The library speaks node identifiers, 16-bit property ids, and raw wire-typed payloads; folder, message, recipient, and attachment semantics (the messaging layer of MS-PST) belong to the Bodu.Formats.Outlook.Pst mail-store reader, which builds on this package and the shared Bodu.Formats.Outlook value model.

using Bodu.IO.Pst;

using var file = PstFile.OpenRead("archive.pst");

Console.WriteLine($"{file.Format}, content encoding: {file.CryptMethod}");

foreach (PstNodeInfo info in file.EnumerateNodes())
    Console.WriteLine($"{info.NodeId} ({info.NodeId.Type}): {info.DataLength} bytes");

// Raw node payloads (NDB) …
PstNode store = file.GetNode(PstNodeId.MessageStore);
byte[] payload = store.ReadAllBytes();

// … and typed LTP views: property bags and tables.
PstPropertyContext properties = store.ReadPropertyContext();
if (properties.TryGetValue(0x3001 /* display name */, out PstPropertyValue name))
    Console.WriteLine(name.GetString());

What it reads

• Header - format discrimination (wVer), the content-encoding method (bCryptMethod), and the B-tree roots, with the header checksum verified.
• Both PST formats - the Unicode format (wVer 23 and later, except 36; 64-bit structures) and the legacy ANSI format (wVer 14/15, 32-bit identifiers and offsets) are read through the same surface; an internal layout descriptor is selected per file.
• Node B-tree (NBT) - every node's identifier, parent, data-block and subnode-block references; enumerated in identifier order or looked up by id.
• Block B-tree (BBT) - block resolution with trailer validation and, under PstValidationLevel.Strict, per-block checksum and signature verification.
• Content encodings - the MS-PST §5.1 permute and §5.2 cyclic byte substitutions are decoded transparently; real encryption (Windows Information Protection) is rejected as unsupported.
• Data trees - XBLOCK/XXBLOCK multi-block payloads flattened to a single byte sequence (ReadAllBytes / OpenDataStream).
• Subnode trees - SLBLOCK/SIBLOCK walks exposing each node's private namespace (EnumerateSubnodes / TryGetSubnode).
• Heap-on-node and BTree-on-heap - the LTP allocator (HN) parsed over each node's ordered data blocks, and the keyed record store (BTH) built on it, with all heap geometry validated at every validation level.
• Property contexts - PstNode.ReadPropertyContext() returns the node's property bag (PstPropertyContext): 16-bit property ids with raw wire type codes and resolved payloads (PstPropertyValue typed accessors), whether the value is inline, heap-resident, or subnode-resident.
• Table contexts - PstNode.ReadTableContext() returns the node's table (PstTableContext): typed columns, the row count from the row index, keyed row lookup, and forward-only row enumeration that streams the row matrix one block at a time (PstTableRow cell access honors the existence bitmap).

Validation is tiered via PstFileOptions.ValidationLevel: Compatible (default, structural checks plus the header checksum), Strict (also every page and block checksum and signature, and stricter content checks), and Minimal (as Compatible, but the header checksum is skipped too). For salvage reads of damaged files, PstFileOptions.OmitUnresolvableValues leaves out a property value or table cell whose reference does not resolve, instead of failing its whole context, and lists it in OmittedPropertyIds, so a damaged object still yields its other values.

Out of scope

• OST files (client magic SO, whatever their version) and the 4 KiB-page variant (wVer 36) - recognized and rejected with PstUnsupportedFormatException, not read.
• MAPI and messaging semantics - folders, messages, recipients, attachments, named-property resolution, and multi-valued/object payload decoding (surfaced raw). The Bodu.Formats.Outlook.Pst mail-store reader provides them over this package.
• Writing, repair, and password handling (the format's password is advisory only).