Class PdfRangedDocument
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.
- 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.
- 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).
- 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.
- 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
The whole file, once it was read (ReadAllAsync(IProgress<long>?, CancellationToken), CompleteAsync(CancellationToken) or a fallback).
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
FallbackReason
Why the document was opened from the whole file instead of by ranges, or null.
public string? FallbackReason { get; }
Property Value
IsComplete
True when the whole file is in memory and Document was opened from it.
public bool IsComplete { get; }
Property Value
Length
The length of the file.
public long Length { get; }
Property Value
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
Retries
How many times an operation was tried again after a miss.
public int Retries { get; }
Property Value
Statistics
public PdfRangeStatistics Statistics { get; }
Property Value
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
cancellationTokenCancellationToken
Returns
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
rangesIEnumerable<PdfByteRange>cancellationTokenCancellationToken
Returns
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
pageNumberintcancellationTokenCancellationToken
Returns
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
readerIPdfRangeReaderoptionsPdfRangedOptionspasswordstringlimitsPdfSecurityLimitsnamestringcancellationTokenCancellationToken
Returns
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
pageNumberintcancellationTokenCancellationToken
Returns
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
progressIProgress<long>cancellationTokenCancellationToken
Returns
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
pageNumberintoperationFunc<PdfVectorDocument, CancellationToken, ValueTask<T>>cancellationTokenCancellationToken
Returns
- Task<T>
Type Parameters
T