Um handle de documento não nulo com contagem de páginas zero é o que o FPDFAvail_GetDocument pode devolver quando é chamado sobre um PDF que nunca foi linearizado, mesmo depois de o FPDFAvail_IsDocAvail ter reportado PDF_DATA_AVAIL. O handle parece aberto, nada reclama, e o visualizador mostra um documento vazio. A API de availability do PDFium lê o layout linearizado do Anexo F da ISO 32000-1; qualquer outro arquivo precisa estar completo e ser aberto pelo caminho ordinário de documento customizado. Essa decisão de roteamento é metade do que abrir um PDF durante o download envolve. A outra metade é o usuário que fecha a aba num quarto do arquivo e abre o mesmo link de novo um instante depois
O loop de availability por trás do TPdfProgressiveDocument
No PDFium Component a sessão inteira vive no TPdfProgressiveDocument, uma subclasse de TPdf que mantém um provider de availability do PDFium vivo enquanto um stream de acesso aleatório se enche. O BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) recebe o stream de apoio e o tamanho lógico do arquivo remoto (o Content-Length, não o tamanho atual do seu store local), liga um callback IsDataAvail e um callback AddSegment, e chama o FPDFAvail_Create. Uma vez que o OpenProgressiveDocument tem sucesso, o objeto se comporta como qualquer outro TPdf ativo: páginas, texto, renderização e save funcionam todos pelos membros de sempre
Cada passo de parse é uma pergunta ao seu código. Quando o PDFium quer um range, o componente responde sim se o range está dentro do prefixo contíguo descrito pelo AvailableByteCount, ou dentro de um range já completado pelo scheduler RangeRequests. Um handler OnDataAvailable então tem a palavra final, e é assim que um cache esparso responde por ranges que nenhum dos dois consegue descrever. O CheckDocumentAvailability devolve um de três valores de TPdfDataAvailability (pdaAvailable, pdaNotAvailable, pdaError) e entrega os ranges de bytes que o PDFium pediu como um array TPdfDownloadRanges ordenado e mesclado. Esses ranges já estão na fila do scheduler com prioridade rrpImmediate quando você os vê, então o array de hints serve para log e exibição de progresso; a fila de trabalho é o RangeRequests
// FetchRange é o seu transporte (HTTP Range GET, socket, leitor de blob):
// escreve Size bytes no Offset em Store e devolve quantos chegaram
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;
// As hints já estão na fila; escreva os bytes primeiro, depois complete
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;
Dois detalhes nesse loop carregam peso. O teto de rodadas existe porque um link morto faz o CheckDocumentAvailability pedir os mesmos ranges em toda chamada, e um loop sem limite transforma uma falha de rede numa UI travada. A ordem importa porque o scheduler serializa o próprio estado dele com uma critical section mas não faz nada pelo TStream.Position no store de apoio. Uma thread de transporte precisa escrever os bytes da resposta no stream antes de chamar o CompleteRequest, já que o PDFium pode ler o range no instante em que a conclusão é publicada. Writers concorrentes precisam de I/O posicionado ou de um lock próprio
Por que o AvailableByteCount se recusa a andar para trás?
O AvailableByteCount só cresce. Atribuir um valor menor levanta EPdfError com "Available byte count cannot move backwards", porque uma vez que o callback de availability disse ao PDFium que um range existe, o parser pode já ter lido e feito cache de objetos dele. Retirar esses bytes depois deixaria o PDFium segurando objetos cuja origem as respostas de availability agora negam. O mesmo setter rejeita valores maiores que o LogicalFileSize e levanta "No progressive load is active" fora de uma sessão
Essa última checagem decide onde bytes que você já tem devem ficar. Se uma visita anterior deixou os primeiros 300 KB do arquivo num cache, passe essa contagem como AInitialAvailableByteCount; o componente a registra antes de o FPDFAvail_Create rodar, então o primeiro olhar do PDFium no header já a vê. Com contagem inicial zero, o Linearization lê plnUnknown até o PDFium ver o header; esse é o estado inicial normal
Elevar o prefixo também cancela trabalho. Qualquer requisição em voo que se sobrepõe aos bytes recém-anunciados agora é redundante, então o scheduler a descarta e dispara OnCancelRequest para ela; um CompleteRequest tardio para essa requisição retorna False. Um store que enche fora de ordem não deve tentar se expressar pelo prefixo de forma alguma. Complete os ranges pelo scheduler, ou responda por range no OnDataAvailable. Uma exceção levantada dentro desse handler não pode cruzar a fronteira do callback C, então o componente a captura e reporta o range como ausente, e o PDFium simplesmente pergunta de novo na próxima checagem
Quando um PDF parcialmente baixado consegue de fato abrir?
Só um PDF linearizado abre antes de o arquivo inteiro chegar. O OpenProgressiveDocument checa a propriedade Linearization (plnUnknown, plnNotLinearized, plnLinearized) e escolhe o loader. Um arquivo linearizado abre pelo FPDFAvail_GetDocument assim que a seção de primeira página e as hint tables estão presentes. Um arquivo não linearizado vai pelo FPDF_LoadCustomDocument no mesmo record de acesso a arquivo, e para tal arquivo o PDFium só reporta o documento como disponível quando todo byte está lá. Esse roteamento é o que mantém o handle de zero páginas do parágrafo de abertura fora do seu visualizador
Logo, o arquivo no servidor decide quão rápido a primeira página aparece. Se o tempo até o primeiro paint importa e você controla o lado de publicação, linearize os arquivos lá. O TPdf.SaveAsLinearized grava o layout do Anexo F a partir do próprio componente, e o passo a passo de Fast Web View e hint tables cobre o que esse layout contém. Para arquivos que você não controla, um PDF não linearizado ainda carrega pelo mesmo loop; ele só alcança pdaAvailable a 100 por cento em vez de cedo
O LoadAvailablePage recebe um número de página 1-based e mantém a ordem que o PDFium espera. Antes da primeira checagem de página ele roda o CheckFormAvailability, que embrulha o FPDFAvail_IsFormAvail, e só depois chama o FPDFAvail_IsPageAvail. Um resultado pfaNotPresent é a resposta normal para um documento sem AcroForm e não bloqueia nada. Quando a página está pronta, o LoadAvailablePage a torna a página ativa, então um visualizador pode renderizar a página 1 de um folheto linearizado enquanto as páginas seguintes ainda estão em trânsito. A espera pela página tem a mesma forma da primeira listagem: chame o LoadAvailablePage, drene o RangeRequests em pdaNotAvailable, pare em pdaAvailable ou pdaError, e mantenha um teto de rodadas. O FirstAvailablePageNumber reporta a página que o dicionário de linearização designa como primeira, já convertido do índice zero-based do PDFium. Para um arquivo não linearizado toda página reporta pdaAvailable direto, porque o documento só pôde abrir quando o arquivo estava completo
Retries, leituras curtas e prioridades no scheduler de ranges
A API FPDFAvail_* em si não sabe nada sobre redes. Ela diz quais bytes o parser precisa agora e pergunta de novo depois; não existe noção de requisição, retry ou cancel. O TPdfRangeRequestScheduler fornece isso, e quatro regras dele moldam como você escreve o transporte
- Uma resposta curta é tratada como progresso. O
CompleteRequest(Request, BytesReceived)com menos bytes que os pedidos publica o prefixo e coloca o resto na fila. A resposta curta também conta como uma tentativa falhada, então o resto continua limitado peloMaxRetryCounte é abandonado quando ele se esgota; zero bytes é uma tentativa falhada simples - O
MaxRetryCounttem 2 como padrão, então um range ganha três tentativas no total. OFailRequestretornaTruequando recolocou o range na fila eFalsequando o range foi abandonado; oStatistics.AbandonedRequestCountrastreia quantos desistiram - O
MaxRequestSizedivide ranges grandes em chunks na hora do dequeue, e oMergeGappermite que dois ranges pendentes se mesclem através de um pequeno gap desconhecido, mas nunca através de bytes já completados ou em voo - Hints do
CheckDocumentAvailabilitye doLoadAvailablePagechegam emrrpImmediate. Hints de form de uma chamada direta aoCheckFormAvailabilitychegam emrrpNormal; quando oLoadAvailablePageroda essa checagem ele mesmo e os dados de form estão ausentes, as hints entram na fila emrrpImmediate. OTryDequeuesempre atende a prioridade mais alta primeiro e o offset mais baixo dentro de uma prioridade
A regra de prioridade se paga quando você faz prefetch. Coloque o arquivo inteiro na fila em rrpBackground logo depois de o documento abrir, e o scheduler subtrai tudo que já está completado ou em voo, então só os bytes que faltam vão para o fio. Quando o usuário então salta para a página 40 e a hint dessa página se sobrepõe a um chunk de fundo já baixando, o scheduler puxa a requisição de fundo, dispara OnCancelRequest para ela, devolve as caudas não sobrepostas para a prioridade de fundo sem cobrar retry, e põe a sobreposição na fila como trabalho immediate fresco. O salto ganha a conexão. Sem isso, o pedido da página esperaria atrás de um chunk de 256 KB do qual ele não precisa
procedure TDownloadForm.QueueRestOfFile;
var
Whole: TPdfDownloadRanges;
begin
FPdf.RangeRequests.MaxRequestSize := 256 * 1024; // o tamanho do chunk é decisão sua
SetLength(Whole, 1);
Whole[0].Offset := 0;
Whole[0].Size := FPdf.LogicalFileSize;
FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;
// Chamado numa worker thread quando uma resposta HTTP Range termina.
// WriteAt é a sua gravação posicionada no store de apoio
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); // bytes primeiro
FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
end
else if not FPdf.RangeRequests.FailRequest(Request) then
TThread.Queue(nil, ShowRangeGaveUp); // abandonado, ou de uma sessão cancelada
end;
Tanto o CompleteRequest quanto o FailRequest podem ser chamados da worker thread; o scheduler toma o lock dele próprio. Uma requisição que foi superada ou pertence a uma sessão cancelada volta como False sem tocar em nada, então a worker não precisa saber por que o range dela ficou velho
O que o CancelProgressiveLoad libera, e em que ordem?
O CancelProgressiveLoad desmonta uma sessão em quatro passos, sempre na mesma ordem: cancelar o scheduler de ranges, fechar o documento, destruir o handle de availability com o FPDFAvail_Destroy, depois liberar os records de callback e o adaptador de stream. Cancelar o scheduler primeiro avança o contador de geração dele, derruba toda requisição pendente e em voo, e dispara OnCancelRequest para cada uma em voo. Uma conclusão do transporte que chega depois carrega a geração antiga, e o CompleteRequest retorna False. O documento fecha antes do handle de availability e do adaptador de stream irem embora porque o PDFium ainda pode ler pelo provider de acesso a arquivo enquanto fecha um documento
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
FPdf := TPdfProgressiveDocument.Create(nil);
// O scheduler vive tanto quanto FPdf, então ligue uma vez
FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;
procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
Attempt: Cardinal);
begin
FTransport.Abort(RequestId); // seu código: feche esse socket ou request
end;
procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
FPdf.CancelProgressiveLoad;
// ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;
O método é idempotente e serve como o caminho único de limpeza para três situações: um BeginProgressiveLoad que falha no meio da construção, um cancel explícito do usuário, e o destrutor. O BeginProgressiveLoad também o chama, então reiniciar o mesmo objeto numa URL nova está bem enquanto a sessão anterior nunca chegou a abrir. Uma vez que o OpenProgressiveDocument teve sucesso o objeto está ativo, e o BeginProgressiveLoad levanta o erro usual "Cannot perform this operation on an active"; chame o CancelProgressiveLoad primeiro. O OnCancelRequest também é o único lugar onde os seus sockets são fechados, já que o scheduler não faz ideia do que é um socket. Exceções levantadas dentro dele são engolidas por requisição, então um abort que falha não pode bloquear o resto
Quem escreve no store decide quem é o dono dele. Com uma worker thread escrevendo no stream de apoio, passe AOwnsStream = False e libere o stream você mesmo depois de a worker parar. Entregar a propriedade significa que o cancel libera o stream enquanto uma escrita já em andamento ainda pode estar a caminho. Mantenha a propriedade sempre que uma thread que não é a chamadora toca no store; AOwnsStream = True só serve a um transporte totalmente síncrono como a primeira listagem
Recursos que esperam o arquivo inteiro
Alguns recursos precisam dos bytes originais do arquivo, não do documento analisado, e recusam de cara uma fonte progressiva incompleta. O ReadXmpPacket levanta "PDF/A metadata is unavailable until progressive loading completes". O ValidatePades retorna um resultado cujo SourceStatus é pvssIncomplete, e o ValidatePdfMac reporta não suportado com uma mensagem pedindo a fonte completa. O BeginIncrementalSave falha também, porque uma atualização incremental precisa acrescentar exatamente aos bytes que foram carregados
O teste de completeza por trás de todos eles é o AvailableByteCount alcançando o LogicalFileSize. Um transporte que entrega tudo pelo scheduler pode portanto segurar todo byte e ainda ser informado de que a fonte está incompleta, porque o prefixo contíguo nunca se moveu. Publique o prefixo quando o scheduler confirmar cobertura completa:
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); // sua UI
end;
Um limite de tamanho se aplica antes de tudo isso começar. No Windows o FPDF_FILEACCESS guarda o comprimento do arquivo num campo de 32 bits, então o BeginProgressiveLoad rejeita um tamanho lógico acima de 4 GiB com um EPdfError em vez de deixar o PDFium analisar um comprimento truncado
Para carregar um arquivo local completo sob demanda por um adaptador de stream, veja fazer streaming de PDFs grandes sob demanda com PDFium; para um PDF que está dentro de um buffer maior, veja carregamento por byte range para PDFs embutidos. Parar um render lento de uma página que já chegou é um mecanismo diferente, coberto em renderização progressiva de página cancelável. O TPdfProgressiveDocument, o scheduler de ranges dele e o SaveAsLinearized fazem parte do PDFium Component para Delphi e C++Builder