Не-нулевой хэндл документа с числом страниц, равным нулю, — это то, что FPDFAvail_GetDocument может вернуть при вызове на PDF, который никогда не был линеаризован, даже после того, как FPDFAvail_IsDocAvail отчитался PDF_DATA_AVAIL. Хэндл выглядит открытым, никто не жалуется, а просмотрщик показывает пустой документ. Availability API PDFium читает линеаризованную раскладку Приложения F к ISO 32000-1; всякий другой файл обязан быть полным и открываться через обычный путь кастомного документа. Это решение о маршрутизации — половина того, что значит открыть PDF во время закачки. Вторая половина — пользователь, закрывший вкладку на четверти файла и снова открывший ту же ссылку мгновение спустя
Цикл доступности за TPdfProgressiveDocument
В PDFium Component весь сеанс живёт в TPdfProgressiveDocument, подклассе TPdf, который держит availability-провайдера PDFium живым, пока random-access stream наполняется. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) принимает опорный stream и логический размер удалённого файла (это Content-Length, а не текущая длина вашего локального хранилища), подключает колбэк IsDataAvail и колбэк AddSegment и вызывает FPDFAvail_Create. После того как OpenProgressiveDocument удался, объект ведёт себя как любой другой активный TPdf: страницы, текст, рендеринг и сохранение работают через обычные члены
Каждый шаг разбора — вопрос вашему коду. Когда PDFium просит диапазон, компонент отвечает «да», если диапазон лежит внутри непрерывного префикса, описанного AvailableByteCount, или внутри диапазона, уже доведённого планировщиком RangeRequests до конца. Затем обработчик OnDataAvailable получает последнее слово — так разреженный кэш отвечает за диапазоны, которые ни то ни другое описать не может. CheckDocumentAvailability возвращает одно из трёх значений TPdfDataAvailability (pdaAvailable, pdaNotAvailable, pdaError) и отдаёт диапазоны, которые просил PDFium, отсортированным, слитым массивом TPdfDownloadRanges. Эти диапазоны уже стоят в очереди планировщика с приоритетом rrpImmediate к моменту, когда вы их видите, так что массив подсказок — для журнала и индикатора прогресса; рабочая очередь — RangeRequests
// FetchRange — ваш транспорт (HTTP Range GET, сокет, читатель блобов):
// он пишет Size байтов со смещением Offset в Store и возвращает, сколько доехало
function FetchRange(Store: TStream; Offset, Size: UInt64): UInt64; forward;
procedure OpenWhileDownloading(Pdf: TPdfProgressiveDocument; Store: TStream;
RemoteSize: UInt64);
const
MaxRounds = 64;
var
Hints: TPdfDownloadRanges;
State: TPdfDataAvailability;
Request: TPdfRangeRequest;
Round: Integer;
begin
Pdf.BeginProgressiveLoad(Store, RemoteSize, False);
State := pdaNotAvailable;
for Round := 1 to MaxRounds do
begin
State := Pdf.CheckDocumentAvailability(Hints);
if State <> pdaNotAvailable then
Break;
// Подсказки уже в очереди; сперва пишем байты, затем завершаем
while Pdf.RangeRequests.TryDequeue(Request) do
Pdf.RangeRequests.CompleteRequest(Request,
FetchRange(Store, Request.Offset, Request.Size));
end;
if State <> pdaAvailable then
raise EPdfError.Create('The document could not be discovered');
Pdf.OpenProgressiveDocument;
end;
Две детали того цикла несут вес. Потолок раундов существует, потому что мёртвая ссылка заставляет CheckDocumentAvailability спрашивать одни и те же диапазоны при каждом вызове, а неограниченный цикл превращает сетевой сбой в зависший UI. Порядок важен, потому что планировщик сериализует собственное состояние критической секцией, но ничего не делает для TStream.Position опорного хранилища. Транспортный поток обязан записать байты ответа в stream до вызова CompleteRequest, поскольку PDFium может прочитать диапазон в момент публикации завершения. Конкурентным писцам нужны позиционированное I/O или собственная блокировка
Почему AvailableByteCount отказывается ехать назад?
AvailableByteCount только растёт. Присваивание меньшего значения бросает EPdfError с текстом «Available byte count cannot move backwards»: раз availability-колбэк уже сказал PDFium, что диапазон существует, парсер мог уже прочитать и закэшировать оттуда объекты. Отнять те байты задним числом значило бы оставить PDFium с объектами, чей источник ответы о доступности теперь отрицают. Тот же сеттер отвергает значения больше LogicalFileSize и бросает «No progressive load is active» вне сеанса
Последняя проверка решает, где живут байты, которые вы уже держите. Если прошлый визит оставил первые 300 КБ файла в кэше, передайте этот счёт как AInitialAvailableByteCount: компонент записывает его до запуска FPDFAvail_Create, так что первый взгляд PDFium на заголовок его уже видит. При начальном счёте ноль Linearization читает plnUnknown, пока PDFium не увидит заголовок; это нормальное стартовое состояние
Подъём префикса вдобавок отменяет работу. Любой летящий запрос, пересекающийся с только что объявленными байтами, стал избыточным, поэтому планировщик его сбрасывает и стреляет для него OnCancelRequest; поздний CompleteRequest для того запроса возвращает False. Хранилище, наполняющееся не по порядку, вообще не должно пытаться выразить себя через префикс. Доводите диапазоны до конца через планировщик или отвечайте за диапазон в OnDataAvailable. Исключение, брошенное внутри того обработчика, не может пересечь границу C-колбэка, поэтому компонент его ловит и репортит диапазон отсутствующим, а PDFium просто спросит снова при следующей проверке
Когда частично скачанный PDF реально открывается?
До приезда всего файла открывается только линеаризованный PDF. OpenProgressiveDocument проверяет свойство Linearization (plnUnknown, plnNotLinearized, plnLinearized) и выбирает загрузчик. Линеаризованный файл открывается через FPDFAvail_GetDocument, как только на месте секция первой страницы и таблицы подсказок. Нелинеаризованный идёт через FPDF_LoadCustomDocument на той же записи файлового доступа, и для такого файла PDFium объявляет документ доступным, только когда на месте каждый байт. Именно эта маршрутизация удерживает не-нулевой хэндл с нулём страниц из вступления подальше от вашего просмотрщика
Так что быстрота первой страницы решается файлом на сервере. Если время до первой отрисовки важно, а публикующая сторона ваша, линеаризуйте файлы там. TPdf.SaveAsLinearized пишет раскладку Приложения F силами самого компонента, а руководство по Fast Web View и таблицам подсказок разбирает, что та раскладка содержит. Для файлов вне вашего контроля нелинеаризованный PDF грузится через тот же цикл; он просто добирается до pdaAvailable на ста процентах, а не заранее
LoadAvailablePage берёт номер страницы с единицы и соблюдает порядок, которого ждёт PDFium. Перед первой проверкой страницы он гоняет CheckFormAvailability, оборачивающую FPDFAvail_IsFormAvail, и лишь затем вызывает FPDFAvail_IsPageAvail. Результат pfaNotPresent — нормальный ответ для документа без AcroForm и ничего не блокирует. Когда страница готова, LoadAvailablePage делает её активной, так что просмотрщик может отрисовать страницу 1 линеаризованного буклета, пока остальные ещё в пути. Ожидание страницы той же формы, что и первый листинг: зовите LoadAvailablePage, сливайте RangeRequests на pdaNotAvailable, останавливайтесь на pdaAvailable или pdaError и держите потолок раундов. FirstAvailablePageNumber репортит страницу, которую словарь линеаризации назначил первой, — уже сконвертированную из нулевого индекса PDFium. Для нелинеаризованного файла каждая страница сразу отчитывается pdaAvailable, ведь документ мог открыться только при полном файле
Повторы, короткие чтения и приоритеты в планировщике диапазонов
Сам API FPDFAvail_* о сетях не знает ничего. Он говорит, какие байты парсеру нужны прямо сейчас, и спрашивает снова позже; понятий запроса, повтора или отмены у него нет. Их поставляет TPdfRangeRequestScheduler, и четыре его правила формируют то, как вы пишете транспорт
- Короткий ответ считается прогрессом.
CompleteRequest(Request, BytesReceived)с меньшим числом байтов, чем запрошено, публикует префикс и ставит остаток в очередь. Короткий ответ вдобавок идёт в счёт неудавшейся попытки, поэтому остаток всё ещё скованMaxRetryCountи бросается, когда тот исчерпан; ноль байтов — обычная неудавшаяся попытка MaxRetryCountпо умолчанию 2, так что один диапазон получает три попытки в сумме.FailRequestвозвращаетTrue, когда заново поставила диапазон в очередь, иFalse, когда диапазон брошен;Statistics.AbandonedRequestCountведёт счёт сдавшимсяMaxRequestSizeрежет крупные диапазоны на куски при выдаче из очереди, аMergeGapпозволяет двум ожидающим диапазонам слиться через маленький неизвестный зазор, но никогда через байты, уже доведённые до конца или в полёте- Подсказки от
CheckDocumentAvailabilityиLoadAvailablePageприходят сrrpImmediate. Форменные подсказки от прямого вызоваCheckFormAvailabilityприходят сrrpNormal; когдаLoadAvailablePageгоняет ту проверку сама, а данных формы нет, подсказки ставятся в очередь сrrpImmediate.TryDequeueвсегда обслуживает высший приоритет первым и низшее смещение внутри приоритета
Правило приоритетов окупается при предзагрузке. Поставьте весь файл в очередь с rrpBackground сразу после открытия документа, и планировщик вычтет всё уже доведённое или летящее, так что в сеть уйдут только недостающие байты. Когда пользователь затем прыгает на страницу 40 и подсказка той страницы пересекается с фоновым куском, который уже качается, планировщик выдёргивает фоновый запрос, стреляет для него OnCancelRequest, возвращает непересекающиеся хвосты на фоновый приоритет без списания попытки и ставит пересечение как свежую немедленную работу. Прыжок выигрывает соединение. Без этого запрос страницы стоял бы за куском на 256 КБ, который ему безразличен
procedure TDownloadForm.QueueRestOfFile;
var
Whole: TPdfDownloadRanges;
begin
FPdf.RangeRequests.MaxRequestSize := 256 * 1024; // размер куска — ваше решение
SetLength(Whole, 1);
Whole[0].Offset := 0;
Whole[0].Size := FPdf.LogicalFileSize;
FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;
// Вызывается в рабочем потоке, когда приезжает один HTTP Range-ответ.
// WriteAt — ваша собственная позиционная запись в опорное хранилище
procedure TDownloadForm.RangeFinished(const Request: TPdfRangeRequest;
const Body: TBytes; Succeeded: Boolean);
begin
if Succeeded and (Length(Body) > 0) then
begin
WriteAt(FStore, Request.Offset, Body); // сперва байты
FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
end
else if not FPdf.RangeRequests.FailRequest(Request) then
TThread.Queue(nil, ShowRangeGaveUp); // брошен, либо из отменённой сессии
end;
И CompleteRequest, и FailRequest безопасно звать из рабочего потока: планировщик берёт собственную блокировку. Запрос, который оказался замещён или принадлежит отменённой сессии, возвращается как False безо всяких касаний, так что рабочему не нужно знать, почему его диапазон устарел
Что освобождает CancelProgressiveLoad и в каком порядке?
CancelProgressiveLoad разбирает сеанс за четыре шага, всегда в одном порядке: отменить планировщик диапазонов, закрыть документ, уничтожить availability-хэндл вызовом FPDFAvail_Destroy, затем распорядиться записями колбэков и освободить адаптер stream. Отмена планировщика первой накатывает его счётчик поколений, сбрасывает каждый ожидающий и летящий запрос и стреляет OnCancelRequest по каждому летящему. Завершение транспорта, приземлившееся позже, несёт старое поколение, и CompleteRequest возвращает False. Документ закрывается до того, как уйдут availability-хэндл и адаптер stream, потому что PDFium может читать через провайдер файлового доступа, пока закрывает документ
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
FPdf := TPdfProgressiveDocument.Create(nil);
// The scheduler lives as long as FPdf, so wire it once
FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;
procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
Attempt: Cardinal);
begin
FTransport.Abort(RequestId); // your code: close that socket or request
end;
procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
FPdf.CancelProgressiveLoad;
// ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;
Метод идемпотентен и служит единственным путём уборки для трёх ситуаций: BeginProgressiveLoad, сорвавшийся на середине строительства, явная пользовательская отмена и деструктор. BeginProgressiveLoad зовёт его тоже, так что перезапуск того же объекта на новом URL безобиден, пока прежний сеанс так и не дошёл до открытия. После успеха OpenProgressiveDocument объект активен, и BeginProgressiveLoad бросает привычную ошибку «Cannot perform this operation on an active»; сперва вызовите CancelProgressiveLoad. OnCancelRequest вдобавок единственное место, где закрываются ваши сокеты: планировщик понятия не имеет, что такое сокет. Исключения, поднятые внутри него, глотаются по-запросно, так что один сорвавшийся abort не блокирует остальные
Кто пишет в хранилище, тот им и владеет. При рабочем потоке, пишущем в опорный stream, передавайте AOwnsStream = False и освобождайте stream сами после остановки рабочего. Переданное владение означает, что отмена освободит stream, пока уже идущая запись может ещё быть в пути. Держите владение всякий раз, когда до хранилища дотягивается поток, отличный от вызывающего; AOwnsStream = True подходит только полностью синхронному транспорту вроде первого листинга
Возможности, ждущие весь файл
Некоторым возможностям нужны исходные байты файла, а не разобранный документ, и неполный прогрессивный источник они отказывают сходу. ReadXmpPacket бросает «PDF/A metadata is unavailable until progressive loading completes». ValidatePades возвращает результат, чей SourceStatus равен pvssIncomplete, а ValidatePdfMac отчитывается «unsupported» с просьбой дать полный источник. BeginIncrementalSave тоже падает, ведь инкрементное обновление обязано добавляться к точным байтам, которые были загружены
Проверка полноты за всеми ими — AvailableByteCount, добравшийся до LogicalFileSize. Транспорт, доставляющий всё через планировщик, потому может держать каждый байт и всё равно услышать, что источник неполон: непрерывный префикс так и не сдвинулся. Публикуйте префикс, как только планировщик подтвердит полное покрытие:
procedure TDownloadForm.CheckSignaturesWhenComplete;
var
Report: TPadesValidationResult;
begin
if FPdf.RangeRequests.IsRangeAvailable(0, FPdf.LogicalFileSize) then
FPdf.AvailableByteCount := FPdf.LogicalFileSize;
Report := FPdf.ValidatePades;
if Report.SourceStatus = pvssIncomplete then
LabelStatus.Caption := 'Signatures are checked when the download finishes'
else
ShowSignatureReport(Report); // ваш UI
end;
Один предел размера вступает прежде всего этого. На Windows FPDF_FILEACCESS хранит длину файла в 32-битном поле, поэтому BeginProgressiveLoad отвергает логический размер выше 4 ГиБ с EPdfError вместо того, чтобы позволить PDFium парсить усечённую длину
Про загрузку полного локального файла по требованию через адаптер stream см. стриминг больших PDF по требованию с PDFium; про PDF, сидящий внутри большего буфера, — загрузку byte range для встроенных PDF. Остановка медленного рендера уже приехавшей страницы — другой механизм, разобранный в статье о отменяемом прогрессивном рендеринге страниц. TPdfProgressiveDocument, его планировщик диапазонов и SaveAsLinearized — часть PDFium Component для Delphi и C++Builder