Object graph inspection and patching - TPdf

Componente: TPdf · Unidades: PDFium, FPdfCompress

Exporta uma visão tipada e limitada dos objetos indiretos ativos e aplica correções restritas de dicionário de forma transacional

Syntax

function ExportObjectGraph(Stream: TStream; const Options: TPdfObjectGraphInspectOptions; out Report: TPdfObjectGraphReport): Boolean;

function SaveAsObjectGraphPatched(Stream: TStream; const Operations: TPdfObjectPatchOperations; out Report: TPdfObjectGraphReport; AllowSignedDocument: Boolean = False): Boolean;

function SaveAsObjectGraphPatched(const FileName: string; const Operations: TPdfObjectPatchOperations; out Report: TPdfObjectGraphReport; AllowSignedDocument: Boolean = False): Boolean;

Typed JSON format

O objeto root, a contagem de objetos ativos, os objetos exportados e o estado de truncamento são emitidos no envelope versionado pdf-object-graph-v1

Cada valor é identificado como dicionário, array, string literal ou hexadecimal, nome, referência, null, Boolean, inteiro, real ou keyword

Streams expõem sua contagem de bytes codificados e, quando habilitado, um digest SHA-256, enquanto seu payload permanece omitido

Objetos diretos e membros materializados de contêineres ObjStm usam a mesma representação

Inspection options

MaxObjects	Máximo de objetos ativos gravados antes de o envelope JSON informar `truncated: true`
MaxDepth	Profundidade máxima de arrays e dicionários aninhados, de 1 a 32
MaxOutputBytes	Limite superior rígido para o fluxo completo de bytes JSON compatível com UTF-8
MaxStringBytes	Bytes máximos retidos de uma string ou nome do PDF
IncludeStreamDigests	Calcula SHA-256 sobre os bytes codificados do stream, sem decodificar ou exportar o payload

Patch model

Cada TPdfObjectPatchOperation seleciona um número exato de objeto, geração e chave de dicionário de nível superior e, em seguida, define ou remove essa chave

Operações de definição aceitam valores tipados null, Boolean, inteiro, real, nome, text string ou referência indireta, e nunca aceitam sintaxe PDF bruta

Todas as identidades de objetos, gerações, referências, nomes, operações duplicadas e dicionários de destino são validados antes de a saída ser entregue

Chaves de comprimento e cadeia de filtros do stream não podem ser corrigidas, porque alterá-las de forma independente dos bytes codificados corromperia o stream

O gravador anexa uma revisão incremental, reconstrói o grafo ativo resultante, carrega-o em modo estrito por meio do PDFium e só então grava o stream do chamador ou substitui atomicamente um arquivo

Policies and limits

Documentos criptografados são rejeitados porque atualizações diretas de objetos em texto puro exigem processamento do security handler
Documentos assinados são rejeitados, a menos que AllowSignedDocument seja explicitamente habilitado
Uma validação com falha deixa um destino pré-existente intacto
O modelo de correção cobre intencionalmente valores de dicionário de nível superior, em vez de substituição bruta arbitrária de objetos

Example

Options := TPdfObjectGraphInspectOptions.Default;
Pdf.ExportObjectGraph(JsonStream, Options, Report);
SetLength(Operations, 1);
Operations[0].Kind := popSet;
Operations[0].ObjectNumber := CatalogObjectNumber;
Operations[0].Generation := 0;
Operations[0].Key := 'Lang';
Operations[0].Value.Kind := povTextString;
Operations[0].Value.TextValue := 'en-US';
Pdf.SaveAsObjectGraphPatched('patched.pdf', Operations, Report);

Inspeção e correção do grafo de objetos