Table of Contents

Class PdfRangedDocument

Namespace
PdfEngine.Vector.Parsing
Assembly
PdfEngine.Vector.dll

A PDF opened from an IPdfRangeReader without reading the whole file first, as Adobe's and pdf.js's viewers open a large file from a web server that answers range requests.

  1. Opening fetches the end of the file (TailBytes) for the cross-reference data, then the objects of the document's structure: the catalog and the root of the page tree (PdfEngine.Vector.Parsing.PdfClosureKind.Structure), and the tree nodes on the path to page 1. The page tree is lazy (IsLazy, LazyPageTree): the page count is the root's /Count, and each page is found when it is first needed, by its path from the root. A tree whose /Count values do not match its kids is read whole instead (PageTreeFallbackReason). Content streams are resolved when their page is drawn.
  2. RunAsync<T>(int, Func<PdfVectorDocument, CancellationToken, ValueTask<T>>, CancellationToken) fetches the objects one page needs, level by level from the page dictionary (PdfEngine.Vector.Parsing.PdfClosureKind.Page), then runs the operation (draw, read text) on the parsed document synchronously, over the fetched blocks (PdfEngine.Vector.Parsing.PdfChunkedByteSource).
  3. A read that still finds bytes missing is recorded; the bytes are fetched, the document is parsed again over the cache (cheap: nothing is fetched twice) and the operation runs again.
  4. When the cross-reference data is damaged (the parser had to rebuild it by scanning the whole file) or an operation still misses bytes after MaxRounds tries, the whole file is read and the document is opened from memory, as without range loading (FallbackReason says why).

The in-memory path (OpenAsync(byte[], string, PdfSecurityLimits?, CancellationToken, string?, IEnumerable<X509Certificate2>?)) is not changed by any of this. Operations are serialized.

public sealed class PdfRangedDocument : IDisposable
Inheritance
PdfRangedDocument
Implements
Inherited Members

Properties

Bytes

public byte[]? Bytes { get; }

Property Value

byte[]

Document

The parsed document. It is replaced when the document is parsed again (after a miss, or when the file is complete): do not keep it across calls.

public PdfVectorDocument Document { get; }

Property Value

PdfVectorDocument

FallbackReason

Why the document was opened from the whole file instead of by ranges, or null.

public string? FallbackReason { get; }

Property Value

string

IsComplete

True when the whole file is in memory and Document was opened from it.

public bool IsComplete { get; }

Property Value

bool

Length

The length of the file.

public long Length { get; }

Property Value

long

PageTreeFallbackReason

Why the page tree was read whole instead of page by page (its /Count values do not match its kids, a loop, a tree too deep), or null. The document stays read by ranges.

public string? PageTreeFallbackReason { get; }

Property Value

string

Retries

How many times an operation was tried again after a miss.

public int Retries { get; }

Property Value

int

Statistics

public PdfRangeStatistics Statistics { get; }

Property Value

PdfRangeStatistics

Methods

CompleteAsync(CancellationToken)

Reads the whole file and parses the document from memory: from then on nothing is fetched. Returns the file.

public Task<byte[]> CompleteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<byte[]>

Dispose()

Disposes the document and drops the cache. Reads in progress are canceled; an operation still running ends with ObjectDisposedException and makes no new document.

public void Dispose()

FetchAsync(IEnumerable<PdfByteRange>, CancellationToken)

Fetches the parts of ranges that are not in the cache.

public Task FetchAsync(IEnumerable<PdfByteRange> ranges, CancellationToken cancellationToken = default)

Parameters

ranges IEnumerable<PdfByteRange>
cancellationToken CancellationToken

Returns

Task

FindPageAsync(int, CancellationToken)

Page pageNumber's node (its boxes, rotation and dictionary), fetching the page-tree nodes on its path if the tree is lazy, but not its contents. Use it for a page's size before it is drawn. The node belongs to the current Document.

public Task<PdfPageNode> FindPageAsync(int pageNumber, CancellationToken cancellationToken = default)

Parameters

pageNumber int
cancellationToken CancellationToken

Returns

Task<PdfPageNode>

OpenAsync(IPdfRangeReader, PdfRangedOptions?, string?, PdfSecurityLimits?, string, CancellationToken)

Opens the document. Throws what Open(IPdfByteSource, string, PdfSecurityLimits?, string?, IEnumerable<X509Certificate2>?) throws for a file that is not a PDF or needs a password, and what the reader throws when it cannot read.

public static Task<PdfRangedDocument> OpenAsync(IPdfRangeReader reader, PdfRangedOptions? options = null, string? password = null, PdfSecurityLimits? limits = null, string name = "Ranged.pdf", CancellationToken cancellationToken = default)

Parameters

reader IPdfRangeReader
options PdfRangedOptions
password string
limits PdfSecurityLimits
name string
cancellationToken CancellationToken

Returns

Task<PdfRangedDocument>

PrefetchPageAsync(int, CancellationToken)

Fetches the bytes that page pageNumber needs (nothing when the file is complete).

public Task PrefetchPageAsync(int pageNumber, CancellationToken cancellationToken = default)

Parameters

pageNumber int
cancellationToken CancellationToken

Returns

Task

ReadAllAsync(IProgress<long>?, CancellationToken)

Reads the whole file (the blocks already fetched are copied, not fetched again), one CompletionRequestBytes read at a time so that page reads go first. Calls after the first return the same task. After a failure, the next call resumes where the failed one stopped: what it read is kept. progress gets the bytes read so far.

public Task<byte[]> ReadAllAsync(IProgress<long>? progress = null, CancellationToken cancellationToken = default)

Parameters

progress IProgress<long>
cancellationToken CancellationToken

Returns

Task<byte[]>

RunAsync<T>(int, Func<PdfVectorDocument, CancellationToken, ValueTask<T>>, CancellationToken)

Runs operation on page pageNumber once its bytes are fetched. When the operation still reads bytes that are not there, they are fetched and it runs again on a fresh parse (the earlier run may have kept a partial result in its caches).

public Task<T> RunAsync<T>(int pageNumber, Func<PdfVectorDocument, CancellationToken, ValueTask<T>> operation, CancellationToken cancellationToken = default)

Parameters

pageNumber int
operation Func<PdfVectorDocument, CancellationToken, ValueTask<T>>
cancellationToken CancellationToken

Returns

Task<T>

Type Parameters

T