Table of Contents

OutlookMailStore Class

Definition

Namespace
Bodu.Formats.Outlook
Assembly
Bodu.Formats.Outlook.Pst.dll
Package
Bodu.Formats.Outlook.Pst 1.3.0
Source
OutlookMailStore.ContainerFaults.cs

Provides a disposable, read-only session over an Outlook personal-folders mail store (a .pst file, MS-PST Unicode or ANSI format): the store properties, the folder hierarchy, and the messages within it, decoded into the shared MAPI value model.

public sealed class OutlookMailStore : IDisposable
Inheritance
OutlookMailStore
Implements
Inherited Members
Extension Methods

Remarks

The session owns its PstFile container (and the source stream unless it is left open); every OutlookMailFolder and OutlookMailMessage obtained from it is a view bound to the session's lifetime - disposing the store invalidates them all. Reads are lazy and streaming-first: opening parses only the container header, folder and message enumerations stream table rows, and each object decodes its properties once on first access.

The session is single-threaded, matching the container's documented contract: its members - and the members of every view obtained from it - must not be called concurrently.

Every failure to read the store surfaces as OutlookPstFormatException, part of the OutlookFormatException family the .msg reader shares. Container corruption met by the session or any view - when the store opens, a property collection decodes, a table is enumerated, or a content stream is read - is wrapped, with the container's PstFileException (and its Error category) preserved as the inner exception.

using Bodu.Formats.Outlook;

using var store = OutlookMailStore.OpenRead("archive.pst");

foreach (OutlookMailFolder folder in store.RootFolder.EnumerateSubfolders())
{
    Console.WriteLine(folder.DisplayName);
    foreach (OutlookMailMessage message in folder.EnumerateMessages())
        Console.WriteLine($"  {message.Subject} - {message.SenderName}");
}

Properties

DisplayName

Gets the store display name.

public string? DisplayName { get; }

Property Value

string

The PidTagDisplayName value, or null when absent.

Exceptions

ObjectDisposedException

The session has been disposed.

OutlookPstFormatException

The container is malformed.

Properties

Gets every decoded property of the store object.

public MapiPropertyCollection Properties { get; }

Property Value

MapiPropertyCollection

The tag-addressed property collection, decoded once on first access.

Remarks

An exception thrown by ValueOmittedCallback while the properties are decoded propagates from this access unchanged.

Exceptions

ObjectDisposedException

The session has been disposed.

OutlookPstFormatException

The container is malformed, or, under strict validation, a property value cannot be decoded.

RootFolder

Gets the root of the store's folder hierarchy.

public OutlookMailFolder RootFolder { get; }

Property Value

OutlookMailFolder

The root folder view, created once on first access.

Remarks

The root folder itself is structural - user folders (the IPM subtree) hang beneath it. Walk EnumerateSubfolders() to reach them.

Exceptions

ObjectDisposedException

The session has been disposed.

OutlookPstFormatException

The container is malformed, or has no root folder node.

Methods

Dispose()

Releases the session and its container (and source stream, unless it was left open).

public void Dispose()

IsPstFile(Stream)

Determines whether a stream begins with the !BDN magic; its position is restored before returning.

public static bool IsPstFile(Stream stream)

Parameters

stream Stream

The readable, seekable stream to sniff.

Returns

bool

true when the stream begins with the magic every PST variant shares, the OST included, whether or not this reader opens it.

Remarks

The check reads only the magic, so it never throws for malformed content; a stream that cannot be read and sought answers false.

Exceptions

ArgumentNullException

Thrown if stream is null.

Open(Stream, OutlookMailStoreReaderOptions, bool)

Opens a mail store from a stream with explicit options.

public static OutlookMailStore Open(Stream stream, OutlookMailStoreReaderOptions options, bool leaveOpen = false)

Parameters

stream Stream

The readable, seekable stream; the file is read from its current position.

options OutlookMailStoreReaderOptions

The reader options.

leaveOpen bool

true to leave the stream open when the session is disposed.

Returns

OutlookMailStore

The open session.

Exceptions

ArgumentNullException

Thrown if stream or options is null.

ArgumentException

The stream is not readable and seekable.

OutlookPstFormatException

The stream is not a structurally valid PST file, or is a format variant or uses a content encoding the reader does not support; the container's PstFileFormatException or PstUnsupportedFormatException is the inner exception.

OpenRead(Stream, bool)

Opens a mail store from a stream with default options.

public static OutlookMailStore OpenRead(Stream stream, bool leaveOpen = false)

Parameters

stream Stream

The readable, seekable stream; the file is read from its current position.

leaveOpen bool

true to leave the stream open when the session is disposed.

Returns

OutlookMailStore

The open session.

Exceptions

ArgumentNullException

Thrown if stream is null.

ArgumentException

The stream is not readable and seekable.

OutlookPstFormatException

The stream is not a structurally valid PST file, or is a format variant or uses a content encoding the reader does not support; the container's PstFileFormatException or PstUnsupportedFormatException is the inner exception.

OpenRead(string)

Opens a mail store from a path with default options.

public static OutlookMailStore OpenRead(string path)

Parameters

path string

The file path.

Returns

OutlookMailStore

The open session.

Exceptions

ArgumentNullException

Thrown if path is null.

ArgumentException

path is empty.

FileNotFoundException

No file exists at path.

DirectoryNotFoundException

A directory in path does not exist.

UnauthorizedAccessException

path names a directory, or the caller does not have permission to read the file.

IOException

The file could not be opened.

OutlookPstFormatException

The file is not a structurally valid PST file, or is a format variant or uses a content encoding the reader does not support; the container's PstFileFormatException or PstUnsupportedFormatException is the inner exception.

TryGetNamedPropertyId(MapiNamedProperty, out ushort)

Attempts to resolve the property identifier a named property maps to in this store.

public bool TryGetNamedPropertyId(MapiNamedProperty name, out ushort id)

Parameters

name MapiNamedProperty

The named-property identity.

id ushort

When this method returns true, the file-specific identifier (at or above 0x8000) the name maps to; combine it with the expected MapiPropertyType to address an object's properties.

Returns

bool

true when the store maps the name.

Remarks

The mapping is store-wide (MS-PST keeps one name-to-id map per file), so a single resolution applies to every message and attachment of the session.

Exceptions

ObjectDisposedException

The session has been disposed.

OutlookPstFormatException

The container is malformed, or, under strict validation, the mapping streams are malformed.

TryGetPropertyName(MapiPropertyTag, out MapiNamedProperty)

Attempts to resolve the named-property identity behind a property tag.

public bool TryGetPropertyName(MapiPropertyTag tag, out MapiNamedProperty name)

Parameters

tag MapiPropertyTag

A tag whose identifier is in the named range (at or above 0x8000).

name MapiNamedProperty

When this method returns true, the identity.

Returns

bool

true when the store maps the tag's identifier.

Exceptions

ObjectDisposedException

The session has been disposed.

OutlookPstFormatException

The container is malformed, or, under strict validation, the mapping streams are malformed.

Applies to

ProductVersions
.NET8, 10