Object graph inspection and patching - TPdf

Componente: TPdf · Unidades: PDFium, FPdfCompress

Exporta uma vista tipada e limitada dos objetos indiretos ativos e aplica transacionalmente correções de dicionário restringidas

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 raiz, a contagem de objetos ativos, os objetos exportados e o estado de truncagem são emitidos no envelope com versão pdf-object-graph-v1

Cada valor é identificado como dicionário, array, cadeia literal ou hexadecimal, nome, referência, null, Boolean, inteiro, real ou palavra-chave

Os streams expõem a respetiva contagem de bytes codificados e, quando ativado, um digest SHA-256, enquanto o respetivo payload permanece omitido

Os objetos diretos e os membros materializados a partir de contentores ObjStm usam a mesma representação

Inspection options

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

Patch model

Cada TPdfObjectPatchOperation seleciona um número de objeto exato, a geração e uma chave de dicionário de topo, e depois define ou remove essa chave

As operações de definição aceitam valores tipados null, Boolean, inteiro, real, nome, cadeia de texto ou referência indireta e nunca aceitam sintaxe PDF em bruto

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

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

O escritor acrescenta uma revisão incremental, reconstrói o grafo ativo resultante, carrega-o em modo strict através do PDFium e só então escreve o stream do chamador ou substitui atomicamente um ficheiro

Policies and limits

Documentos encriptados são rejeitados porque as atualizações diretas de objetos em texto simples exigem processamento pelo security handler
Documentos assinados são rejeitados salvo se AllowSignedDocument estiver explicitamente ativo
Uma validação falhada deixa intocado um destino já existente
O modelo de correção abrange intencionalmente valores de dicionário de topo em vez de substituição arbitrária de objetos em bruto

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