Table of Contents

PstFileOptions Class

Definition

Namespace
Bodu.IO.Pst
Assembly
Bodu.IO.Pst.dll
Package
Bodu.IO.Pst 1.3.0
Source
PstFileOptions.cs

Controls how a PstFile is opened and validated.

public sealed class PstFileOptions
Inheritance
PstFileOptions
Inherited Members
Extension Methods

Constructors

PstFileOptions()

public PstFileOptions()

Properties

BlockCacheSize

Gets the maximum number of decoded pages, and separately of decoded block payloads, the session keeps in its least-recently-used caches.

public int BlockCacheSize { get; init; }

Property Value

int

The entry budget of each cache; 256 by default. 0 disables caching entirely.

Remarks

Pages and blocks are cached separately, each cache holding up to this many entries. A cached page is 512 bytes and a cached block at most 8,192 bytes, so the default budget bounds the two caches at roughly 2.2 MB per open session. Repeated structural reads - B-tree walks, property-context and table-context access over the same nodes - are served from the cache instead of re-reading and re-decoding from the source stream.

Exceptions

ArgumentOutOfRangeException

The value is negative.

MaxDataTreeLeaves

Gets the largest number of leaf data blocks a node's data tree may reference.

public int MaxDataTreeLeaves { get; init; }

Property Value

int

The fan-out limit; 65,536 by default.

Remarks

The limit is enforced while the tree's internal blocks are walked, before any leaf payload is read, and applies to streaming and buffered reads alike - the leaf list itself is the allocation it bounds. A tree exceeding it is refused with PstFileFormatException and LimitExceeded.

Exceptions

ArgumentOutOfRangeException

The value is zero or negative.

MaxNodeDataLength

Gets the largest node payload, in bytes, the session materializes in memory.

public long MaxNodeDataLength { get; init; }

Property Value

long

The materialization limit; 256 MiB by default.

Remarks

The limit governs every read that assembles a node's whole payload - ReadAllBytes(), the heap-on-node parse behind the property and table contexts, and subnode-resident property values. It does not govern OpenDataStream(), which reads one block at a time and is unbounded by design.

A data tree declaring more than this is refused with PstFileFormatException and LimitExceeded at every validation level: a crafted tree can reference the same physical block many thousands of times, so the declared size - not the file size - is what bounds the allocation.

Exceptions

ArgumentOutOfRangeException

The value is zero or negative.

OmitUnresolvableValues

Gets a value indicating whether a property value or table cell whose value reference does not resolve is omitted rather than failing the read.

public bool OmitUnresolvableValues { get; init; }

Property Value

bool

true to omit such a value and record its identifier in OmittedPropertyIds or OmittedPropertyIds; false, the default, to raise PstFileFormatException.

Remarks

A value reference does not resolve when it names a heap item the context's heap does not hold, when a property's fixed-width value is shorter than its type, or when it names a subnode the node does not hold or whose data tree cannot be resolved. Without this option each of these is container corruption that fails the whole context at every validation level. With it the value is omitted and the rest of the context stays readable, so a damaged object still yields what it can: the option is for recovering data from a damaged file.

The option is independent of ValidationLevel and covers individual values only. A fault in a heap's header, page map, or B-tree, in a table's column descriptions or row matrix, or in a node's subnode tree still fails the read, and a value whose reference resolves but whose data blocks fail their checks still raises PstFileFormatException when it is read.

ValidationLevel

Gets how strictly the file's structures and checksums are validated.

public PstValidationLevel ValidationLevel { get; init; }

Property Value

PstValidationLevel

The validation level; Compatible by default.

Applies to

ProductVersions
.NET8, 10