PstPropertyContext Class
Definition
Represents a node's property context (PC): the LTP property bag of 16-bit property identifiers with
wire-typed values, in the manner the exploration plan sketches - format-agnostic, with no MAPI semantics.
public sealed class PstPropertyContext : IReadOnlyCollection<PstPropertyValue>, IEnumerable<PstPropertyValue>, IEnumerable
- Inheritance
-
PstPropertyContext
- Implements
- Inherited Members
- Extension Methods
Remarks
The context's records are materialized when the context is read; each value's payload is resolved on access, so a large subnode-resident value costs its read only when it is actually retrieved. Enumeration yields values in property-identifier order (the tree's stored order).
When the session omits unresolvable values (OmitUnresolvableValues), a property whose value reference does not resolve is absent from every member of the context, as if the context did not hold it, and its identifier is listed in OmittedPropertyIds.
Properties
Count
Gets the number of properties the context carries.
public int Count { get; }
Property Value
- int
The property count, excluding any omitted property.
OmittedPropertyIds
Gets the identifiers of the properties left out of the context because their value references do not resolve.
public IReadOnlyList<ushort> OmittedPropertyIds { get; }
Property Value
- IReadOnlyList<ushort>
The omitted property identifiers, in ascending order; empty when every reference resolves or when the session does not omit unresolvable values.
Remarks
Properties are omitted only when the session was opened with OmitUnresolvableValues; otherwise an unresolvable reference raises PstFileFormatException when its value is read. A non-empty list marks the context as salvaged from a damaged file.
Methods
Contains(ushort)
Determines whether the context carries a property.
public bool Contains(ushort propertyId)
Parameters
propertyIdushortThe 16-bit property identifier.
Returns
EnumeratePropertyIds()
Enumerates the identifiers of the properties the context holds, in ascending order, without materializing any value.
public IEnumerable<ushort> EnumeratePropertyIds()
Returns
- IEnumerable<ushort>
The property identifiers.
GetEnumerator()
Enumerates the context's values in property-identifier order, resolving each payload as it is yielded.
public IEnumerator<PstPropertyValue> GetEnumerator()
Returns
- IEnumerator<PstPropertyValue>
The value enumerator.
Exceptions
- PstFileFormatException
A value reference does not resolve.
GetValue(ushort)
Retrieves a property's value, resolving its payload.
public PstPropertyValue GetValue(ushort propertyId)
Parameters
propertyIdushortThe 16-bit property identifier.
Returns
- PstPropertyValue
The property value.
Exceptions
- PstFileException
The property is not present (Error is PropertyNotFound).
- PstFileFormatException
The property's value reference does not resolve.
TryGetValue(ushort, out PstPropertyValue)
Attempts to retrieve a property's value, resolving its payload.
public bool TryGetValue(ushort propertyId, out PstPropertyValue value)
Parameters
propertyIdushortThe 16-bit property identifier.
valuePstPropertyValueWhen this method returns true, the property value.
Returns
Exceptions
- PstFileFormatException
The property's value reference does not resolve.
TryGetValueLength(ushort, out long)
Attempts to determine the length of a property's payload without reading it.
public bool TryGetValueLength(ushort propertyId, out long length)
Parameters
propertyIdushortThe 16-bit property identifier.
lengthlongWhen this method returns true, the payload length in bytes.
Returns
Remarks
For a subnode-resident value only the data tree's index blocks are read, so the length is available for a payload of any size regardless of MaxNodeDataLength.
Exceptions
- PstFileFormatException
The value's storage is malformed.
TryGetWireType(ushort, out ushort)
Attempts to determine a property's wire type without materializing its value.
public bool TryGetWireType(ushort propertyId, out ushort wireType)
Parameters
propertyIdushortThe 16-bit property identifier.
wireTypeushortWhen this method returns true, the raw 16-bit wire type.
Returns
TryOpenValueStream(ushort, out Stream)
Attempts to open a property's payload as a read-only, seekable stream.
public bool TryOpenValueStream(ushort propertyId, out Stream stream)
Parameters
propertyIdushortThe 16-bit property identifier.
streamStreamWhen this method returns true, the payload stream.
Returns
Remarks
The stream is the streaming counterpart of TryGetValue(ushort, out PstPropertyValue): a heap-resident value is served from the heap's decoded bytes, and a subnode-resident value is read block by block on demand - the same stream OpenDataStream() returns - so MaxNodeDataLength, which bounds materialization, does not apply. The stream is bound to the owning session and must be disposed before it.
Inline and fixed-width values are exposed as their raw little-endian bytes for uniformity; the typed accessors on PstPropertyValue remain the natural way to read them.
Exceptions
- PstFileFormatException
The value's storage is malformed.
Explicit Interface Implementations
IEnumerable.GetEnumerator()
Returns an enumerator that iterates through a collection.
IEnumerator IEnumerable.GetEnumerator()
Returns
- IEnumerator
An IEnumerator object that can be used to iterate through the collection.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |