As atualizações incrementais de PDF permitem que uma aplicação Delphi modifique um documento anexando apenas os objetos alterados, deixando cada byte original intocado. A losLab PDF Library implementa isso por meio do AppendToStream, que grava apenas a seção incremental definida pela ISO 32000-1 §7.5.6, de modo que a edição de um único marcador em um arquivo de 2 GB custe kilobytes de saída em vez de uma regravação completa. Esse mesmo mecanismo é a razão pela qual documentos assinados podem ser atualizados sem invalidar suas assinaturas
O problema que isso resolve é concreto. Um salvamento completo regrava todo o arquivo: cada objeto é desserializado novamente, cada deslocamento (offset) de referência cruzada é recalculado e a saída não mantém nenhuma relação a nível de byte com a entrada. Para uma fatura de 40 KB, isso é aceitável. Para um arquivo digitalizado de 2 GB onde você apenas corrigiu um erro de digitação no título do documento, regravar dois gigabytes para alterar vinte bytes é absurdo — e se o arquivo contivesse uma assinatura digital, a regravação simplesmente a destruiria
Por que salvar um PDF corrompe sua assinatura digital?
Uma assinatura digital de PDF não assina o conteúdo lógico do documento; ela assina intervalos de bytes (byte ranges) do arquivo físico. A entrada /ByteRange no dicionário de assinaturas registra exatamente quais trechos do arquivo o resumo criptográfico (digest) cobre. Qualquer operação de salvamento que desserializar novamente esses bytes — mesmo uma que produza um documento semanticamente idêntico — altera o resumo criptográfico, e todo validador relará a assinatura como corrompida. Isso ocorre por design: a assinatura atesta os bytes que o signatário viu, não um modelo abstrato de documento
As atualizações incrementais são a válvula de escape que a especificação do PDF fornece. Como um salvamento incremental anexa novos dados após o %%EOF original e nunca toca nos intervalos de bytes assinados, a assinatura existente continua validando em relação aos bytes que ela cobre. Os validadores então classificam as alterações anexadas separadamente — uma segunda assinatura, um preenchimento de formulário, uma anotação — e decidem se são modificações permitidas. Todo fluxo de trabalho de múltiplas assinaturas depende disso: cada signatário adiciona uma seção incremental sobre a anterior. Se você estiver criando pipelines de assinatura, o artigo complementar sobre assinatura e validação PAdES no Delphi aborda detalhadamente como os intervalos de bytes de assinatura e as seções incrementais interagem
Como funcionam as atualizações incrementais sob a ISO 32000-1 §7.5.6
A ISO 32000-1 §7.5.6 define o modelo em três regras. Primeiro, o conteúdo original do arquivo é deixado inteiramente intacto — nenhum byte é movido. Segundo, os objetos alterados e os recém-criados são anexados após o último %%EOF, cada um com o mesmo número de objeto que tinha antes (objetos alterados simplesmente obtêm uma definição mais recente que sombreia a antiga). Terceiro, uma nova seção de referência cruzada (cross-reference) e um trailer são anexados; a entrada /Prev do trailer aponta de volta para o deslocamento de byte (byte offset) da seção de referência cruzada anterior, formando uma cadeia pela qual o leitor caminha do mais novo ao mais antigo para resolver cada objeto em sua definição mais recente
Duas propriedades úteis derivam dessa estrutura. As atualizações são baratas na proporção do que foi alterado, e não do tamanho do documento — o custo de anexação é o tamanho dos objetos modificados mais uma pequena sobrecarga de xref/trailer. E o arquivo se torna seu próprio histórico de versões: cada revisão anterior ainda está fisicamente presente, de modo que um auditor pode truncar o arquivo em qualquer %%EOF anterior e recuperar exatamente o documento que existia naquele ponto. Para fluxos de trabalho de conformidade que precisam provar como era a aparência de um documento antes de cada alteração, essa trilha de auditoria integrada costuma ser o argumento decisivo para salvamentos incrementais
Gravando uma atualização incremental com o AppendToStream
A losLab PDF Library expõe a saída incremental por meio de AppendToStream(AppendMode: Integer; OutStream: TStream): Integer, que retorna 1 em caso de sucesso e 0 em caso de falha. O parâmetro AppendMode seleciona o que vai para o fluxo (stream) de destino. O Modo 0 grava um arquivo completo: os bytes originais da origem são copiados primeiro para o fluxo e, em seguida, a seção incremental é anexada. O Modo 1 grava apenas a própria seção incremental — o delta — e ignora completamente os bytes de origem. O Modo 2 primeiro grava um prefixo fornecido pelo chamador registrado via SetAppendInputFromString e, em seguida, anexa a seção de atualização sobre ele
var
Doc: TPDFlib;
Delta: TMemoryStream;
begin
Doc := TPDFlib.Create;
try
if Doc.LoadFromFile('contract.pdf', '') <= 0 then
Exit;
// Edição pequena: o tipo de alteração que não deveria
// disparar uma reescrita do arquivo inteiro
Doc.SetInformation(3, 'Amended 2026-07-04'); // chave 3 = /Subject
Delta := TMemoryStream.Create;
try
// AppendMode = 1: grava apenas a seção incremental.
// Bytes originais + Delta = um PDF completo e válido.
if Doc.AppendToStream(1, Delta) = 1 then
Delta.SaveToFile('contract.delta.bin');
finally
Delta.Free;
end;
finally
Doc.Free;
end;
end;
O Modo 1 é o mais interessante para o design do sistema. Como o delta é autônomo, você pode enviá-lo independentemente do original: armazene revisões como blobs separados no armazenamento de objetos, replique apenas deltas para um site remoto ou reconstrua qualquer revisão concatenando o arquivo base com sua cadeia de incrementos. A regra de reconstrução é a concatenação simples de bytes — o arquivo original primeiro, depois cada delta em ordem — porque esse é exatamente o layout que o §7.5.6 prescreve para um arquivo atualizado de forma incremental
Como a biblioteca calcula os deslocamentos de xref sem copiar o arquivo original?
As entradas de referência cruzada dentro de uma seção incremental devem conter deslocamentos de bytes (byte offsets) absolutos — posições medidas a partir do início do arquivo completo, não a partir do início do delta. Isso cria um quebra-cabeça para o modo 1: o gravador nunca emite os bytes originais, mas cada deslocamento que ele registra precisa fingir que eles estão lá. A losLab PDF Library resolve isso com um adaptador de fluxo interno, o TPDFAppendSectionStream, que apresenta um espaço de coordenadas virtuais para o serializador. O adaptador é criado com o comprimento de bytes do arquivo original como seu deslocamento base, relata sua posição e tamanho como essa base mais o que quer que tenha sido anexado até o momento, e encaminha apenas os bytes recém-gravados para o fluxo de destino do chamador
A consequência é que o modo 1 nunca materializa uma cópia do documento de origem — nem em disco, nem em memória. A implementação ingênua (gravar o arquivo completo em um buffer temporário e depois cortar a cauda) carregaria uma cópia transitória de todo o PDF original, o que, para entradas em escala de gigabytes, é precisamente o custo que as atualizações incrementais existem para evitar. Essa técnica de virtualização de deslocamento é prima próxima do deslocamento de referência de byte (byte-reference shifting) usado em outras partes da biblioteca; o artigo sobre mesclagem rápida de PDF com deslocamento de referência de byte mostra a mesma ideia aplicada à combinação de documentos, e o guia sobre mesclagem e divisão de grandes PDFs com acesso direto a arquivos aborda a arquitetura de E/S subjacente para arquivos que não cabem confortavelmente na RAM
Salvamento completo em fluxo com o SaveToStream
A saída incremental é metade da história do streaming; a outra metade é o que acontece em um salvamento completo. O SaveToStream na losLab PDF Library aciona o serializador de documentos diretamente contra o fluxo de destino, em vez de primeiro renderizar o documento inteiro em um AnsiString intermediário e depois gravar esse buffer de uma vez. Armazenar em buffer primeiro significaria que cada salvamento completo retém transitoriamente uma segunda cópia completa da saída em memória — inofensivo em 10 MB, doloroso em 500 MB e uma parede intransponível para saídas de vários gigabytes em processos de 32 bits. A serialização direta faz a memória de pico acompanhar as estruturas de objetos do documento em vez do seu tamanho serializado
var
Doc: TPDFlib;
Output: TFileStream;
begin
Doc := TPDFlib.Create;
try
if Doc.LoadFromFile('archive.pdf', '') <= 0 then
Exit;
// ... edições que justificam uma reescrita completa ...
Output := TFileStream.Create('archive-rewritten.pdf', fmCreate);
try
if Doc.SaveToStream(Output) = 0 then
Writeln('Save failed, error ', Doc.LastErrorCode);
finally
Output.Free;
end;
finally
Doc.Free;
end;
end;
Uma armadilha de modo de compartilhamento: por que um append no mesmo arquivo pode retornar 0
Uma armadilha nessa área merece ser detalhada porque o padrão de falha se generaliza. O AppendToFile(FileName) anexa uma atualização incremental diretamente a um PDF existente no disco — a chamada natural para um fluxo de trabalho de trilha de auditoria in-loco: carregar um arquivo, fazer uma alteração e anexar ao mesmo caminho. Essa sequência coloca dois handles em um só arquivo. Para suportar a leitura sob demanda de documentos grandes, o LoadFromFile mantém o handle do arquivo de origem aberto durante todo o tempo de vida do objeto do documento, então o modo de compartilhamento desse handle decide se o append pode reabrir o mesmo arquivo para gravação. Abra com fmShareDenyWrite e o próprio modo de compartilhamento do carregador nega a gravação, e o append falha antes de escrever um único byte
A losLab PDF Library abre esse handle com fmShareDenyNone, o que é seguro justamente pelo que um append incremental é: ele adiciona bytes estritamente após o fim do arquivo e nunca regrava a região que o handle de longa duração do leitor está servindo. A lição geral para quem encapsula esta biblioteca — ou constrói carregadores de streaming semelhantes — é que leitores preguiçosos que retêm handles e gravadores do mesmo arquivo estão em tensão, e o modo de compartilhamento que você escolhe na abertura é um contrato de API, não um detalhe de implementação. Se o AppendToFile retornar 0 em algum ponto do seu código, verifique primeiro se algo mais no seu processo ainda mantém o arquivo de destino com um modo de compartilhamento restritivo
Os custos reais: quando as atualizações incrementais são a ferramenta errada
As atualizações incrementais trocam o tamanho do arquivo pela eficiência de gravação, e essa troca nem sempre é favorável. Cada revisão anexa seus objetos alterados enquanto as definições substituídas permanecem no arquivo, de modo que um documento editado centenas de vezes acumula objetos mortos e uma longa cadeia /Prev pela qual cada leitor deve caminhar. Pior ainda, o conteúdo "excluído" não desapareceu: o texto removido na revisão cinco ainda está fisicamente presente nos bytes da revisão quatro, recuperável por qualquer pessoa que trunque o arquivo. A eliminação (redaction), higienização ou qualquer remoção de conteúdo sensível, portanto, exige uma regravação completa — um salvamento incremental de uma eliminação é um vazamento de dados com etapas adicionais
Um salvamento completo também é a escolha certa quando o objetivo é a compactação (eliminação de incrementos acumulados e objetos não utilizados), ao alterar propriedades de todo o documento, como criptografia — a criptografia novamente afeta cada string e fluxo, de modo que não resta nada de "incremental" na alteração — ou ao produzir um entregável limpo no qual o histórico de edição não deve viajar com o arquivo. Uma regra razoável: use AppendToStream ou AppendToFile enquanto um documento estiver ativo e mudando, especialmente depois de conter assinaturas; use uma regravação completa com SaveToStream nos limites do ciclo de vida, quando o documento sair do seu sistema ou quando seu histórico precisar ser nivelado (flattened)
As atualizações incrementais, a saída delta de deslocamento virtual e a serialização direta em fluxo fazem parte da losLab PDF Library padrão para Delphi, C# e VB.NET; a página do produto lista a interface de API completa de salvamento e anexação, juntamente com os recursos de assinatura e arquivos grandes discutidos acima