LoadFromRangeSource
Document management, Performance
Description
Loads and selects a PDF through a synchronous random-access callback, allowing HTTP clients, databases, object stores and custom storage providers to supply only the byte ranges the parser touches
Syntax
Delphi
Function TPDFlib.LoadFromRangeSource(SourceSize: Int64;
ReadCallback: TPDFlibRangeReadEvent; Const Password: WideString;
ChunkSize: LongInt= 0; CacheLimitBytes: Int64= 0;
CoalesceWindowMS: Cardinal= PDF_NET_DEFAULT_COALESCE_WINDOW_MS;
AvailabilityCallback: TPDFlibRangeAvailabilityEvent= Nil): Integer;Parameters
| SourceSize | The authoritative total source size in bytes |
|---|---|
| ReadCallback | The callback that copies bytes for an absolute source offset |
| Password | The password used to open the PDF, or an empty string for an unencrypted document |
| ChunkSize | The aligned range-fetch granularity; zero selects the 64 KiB default and values below 4096 also use the default |
| CacheLimitBytes | The maximum bytes retained across least-recently-used windows; zero selects the 4 MiB default and values below one chunk are raised to one chunk |
| CoalesceWindowMS | The collection window for the first uncached chunk of each absolute read; 2 milliseconds is the default and zero disables the initial delay |
| AvailabilityCallback | An optional non-fetching test for byte ranges already present in progressive storage |
Return values
| 0 | The source arguments were invalid or the PDF could not be loaded; inspect LastErrorCode |
|---|---|
| 1 | The document was loaded and selected |
Remarks
The read callback receives absolute zero-based offsets and must write no more than Count bytes to Buffer, returning the number written
The callback target and its backing storage must remain valid until the loaded document is closed because page rendering, extraction and saving can request additional ranges later
Calls are synchronous and may arrive in non-sequential order; a short result is accepted at the physical end of the source, while an unexpected zero result causes loading or the current deferred operation to fail
When AvailabilityCallback is assigned, return a nonzero value only when the complete requested range can be read immediately without transport or blocking I/O
A cached range is available regardless of the callback result; a Nil callback preserves synchronous behavior by treating every valid source range as available
Aligned chunks avoid duplicate transport fetches for overlapping reads, while the byte budget bounds retained payload independently of document size
Deferred object and segment reads use absolute offsets, so concurrent work shares same-chunk requests and merges adjacent queued chunks without changing the positional stream cursor
The source callbacks are serialized and must not recursively read from the same range stream
Use GetRangeSourceDataAvailability to test page, form or indirect-object dependencies without reading ranges reported as missing
Use GetRangeSourceCacheInfo, SetRangeSourceCacheLimit and ClearRangeSourceCache to observe or change the active cache
The library owns its internal seekable range stream, but it does not own the callback target or its backing storage