In PDFium Component, leggere una annotazione tramite TPdf.Annotation[] e riassegnare il record non scrive nulla di nuovo quando nulla è cambiato: il getter riferisce solo un appearance che ha davvero letto, quindi una annotazione che porta solo /N torna indietro con solo /N. Il dettaglio merita di essere capito, perché un lato lettura che riporta troppi appearance aggiunge voci /R e /D vuote al dizionario di appearance /AP, i validatori PDF/A rifiutano quel dizionario, e il trigger abituale è una correzione pensata per rendere un file più conforme, non meno
Che cosa va storto quando riscrivete una annotazione invariata?
Risposta breve: se il lato lettura riporta troppo, la annotazione guadagna stream di appearance che non aveva, e un file che passava la validazione PDF/A prima della tua modifica la fallisce dopo. Lo scenario tipico va così. Arriva un archivio clienti con annotazioni square e text sprovviste del flag Print, PDF/A richiede che ogni annotazione si stampi, quindi scorri le pagine in loop, aggiungi afPrint e riassegni ogni record. Nulla in quel codice tocca gli appearance. Il record da TPdf.Annotation[] è un TPdfAnnotation, e SetAnnotationData scrive ogni campo il cui sentinel Has* è impostato, che è esattamente come le coppie HasContents / ContentsText sono pensate per funzionare. La trappola è un getter che imposta HasAppearanceRollover e HasAppearanceDown a True con stringhe vuote per le modalità inesistenti; il setter allora scrive diligentemente due stream vuoti. Il getter del PDFium Component riferisce solo ciò che ha letto, quindi il loop qui sotto riscrive solo gli appearance che la sorgente aveva:
procedure MarkAnnotationsPrintable(const FileName: string);
var
Pdf: TPdf;
PageNo, I: Integer;
A: TPdfAnnotation;
begin
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FileName;
Pdf.Active := True;
for PageNo := 1 to Pdf.PageCount do
begin
Pdf.PageNumber := PageNo;
for I := 0 to Pdf.AnnotationCount - 1 do
begin
A := Pdf.Annotation[I];
if not (afPrint in A.Flags) then
begin
A.Flags := A.Flags + [afPrint] - [afHidden, afInvisible, afNoView];
// Il getter riferisce solo gli appearance che ha letto, così una sorgente
// con solo /AP/N viene riscritta con solo /AP/N
Pdf.Annotation[I] := A;
end;
end;
end;
Pdf.SaveAs(ChangeFileExt(FileName, '.printable.pdf'));
finally
Pdf.Free;
end;
end;
ISO 32000-1 §12.5.5 definisce il dizionario di appearance con tre voci: /N per l'aspetto normale, /R per rollover e /D per down. /R e /D sono opzionali, e quando mancano un viewer ricade su /N. Uno stream /R vuoto non è però assente. È uno stream valido che non dipinge nulla, quindi un viewer che onora gli appearance rollover mostra un rettangolo bianco nel momento in cui il puntatore passa sopra la annotazione. PDF/A è più severo ancora: ISO 19005-1 (con Corrigendum 2) e ISO 19005-2 / 19005-3 consentono solo /N in un dizionario di appearance di annotazione. veraPDF segnala un tale file sotto la regola 6.5.3-4 per PDF/A-1 e la regola 6.3.3-2 per PDF/A-2 e PDF/A-3, e il TPdf.ValidatePdfA incorporato lo elenca come pvaiAnnotationApDictViolation. Una modifica che aggiunge il flag Print per soddisfare una clausola dello standard può romperne un'altra
Perché FPDFAnnot_GetAP restituisce 2 per un appearance mancante?
PDFium non restituisce mai zero da FPDFAnnot_GetAP, nemmeno quando lo stream di appearance richiesto non esiste. La funzione segue il consueto schema PDFium a due chiamate: passi un buffer nil per ottenere la dimensione richiesta in byte, allochi, poi richiami per copiare il testo UTF-16LE. La dimensione include sempre il terminatore UTF-16, quindi uno stream mancante riferisce 2 byte, una stringa vuota più il suo terminatore. Il gate ovvio, ByteLength >= SizeOf(FPDF_WCHAR), è un controllo che ogni chiamata supera, quindi un getter costruito su di esso riferisce tutti e tre i flag HasAppearance* come True per qualunque annotazione con almeno un appearance. Un round trip tramite il record chiede allora a FPDFAnnot_SetAP di memorizzare una stringa vuota per ogni modalità, e PDFium crea lo stream per contenerla. Nessuna eccezione, nessun warning, e la pagina visibile appare identica, ecco perché questo errore emerge in un validatore PDF/A anziché in un viewer
Come decide il PDFium Component che un appearance esiste
ReadAppearance, l'helper dentro GetPageAnnotation che riempie AppearanceNormal, AppearanceRollover e AppearanceDown, tratta un risultato come contenuto solo quando porta almeno un carattere oltre il terminatore. La prima chiamata deve restituire più di SizeOf(FPDF_WCHAR) byte e un numero di byte pari, dato che una lunghezza dispari non può essere UTF-16. La seconda chiamata, quella che copia davvero il testo, viene validata di nuovo: una lunghezza restituita di 2 o meno, o una maggiore del buffer allocato, azzera HasValue a False e lascia la stringa vuota. Sul lato scrittura, SetAnnotationData chiama FPDFAnnot_SetAP solo per le modalità il cui flag HasAppearance* è True, quindi un record letto da una annotazione che ha solo /N riscrive solo /N
Stream mancanti e vuoti sembrano identici, quindi il getter resta conservativo
L'API nativa non sa dire uno stream di appearance mancante da uno che esiste ma è vuoto, e PDFium Component non finge il contrario. Entrambi i casi restituiscono gli stessi 2 byte da FPDFAnnot_GetAP, quindi entrambi si rileggono come HasAppearanceRollover = False con AppearanceRollover vuota. Ne seguono due conseguenze da tenere a mente in fase di design. Primo, un sentinel False significa "nessun contenuto è stato letto, quindi una riscrittura lascerà questa modalità in pace", non "la chiave /R è assente dal dizionario". Secondo, il record non può rilevare uno stream vuoto già presente nel file: un documento danneggiato da una build più vecchia o da un altro strumento si rilegge pulito, e riassegnare il record non lo ripara né lo peggiora. Per trovare quei file serve un controllo a livello di byte, che è ciò a cui servono TPdf.ValidatePdfA e il workflow di validazione preflight PDF/A con PDFium Component
Come si ripulisce un appearance di proposito?
Impostate il sentinel esplicitamente e passate una stringa vuota; il setter la scrive. Bloccare le stringhe vuote in SetAnnotationData sarebbe stata la correzione sterninata per questo bug, ma avrebbe rotto anche i chiamanti che ripuliscono un appearance deliberatamente, lo stesso contratto che HasContents e HasAuthor seguono per il testo. Quindi la correzione vive interamente nel getter, e il setter continua a onorare qualunque cosa chieda il chiamante:
// Sostituite l'aspetto rollover, poi ripulitelo di nuovo
A := Pdf.Annotation[0];
A.HasAppearanceRollover := True;
A.AppearanceRollover := 'q Q';
Pdf.Annotation[0] := A;
A := Pdf.Annotation[0];
// A.HasAppearanceRollover è True e il testo fa round trip come 'q Q'
A.HasAppearanceRollover := True; // ribadite l'intento esplicitamente
A.AppearanceRollover := ''; // scrivete uno stream vuoto di proposito
Pdf.Annotation[0] := A;
A := Pdf.Annotation[0];
// Si rilegge come HasAppearanceRollover = False con stringa vuota:
// uno stream vuoto e uno assente sono indistinguibili qui
Tenete presente che una /R o /D svuotata esplicitamente conta comunque come chiave extra sotto le regole PDF/A citate sopra. Se il bersaglio è un profilo archivio, scrivere una /N non vuota e lasciare intatte le altre due modalità è l'unica forma che valida. Qualsiasi workflow che sposta annotazioni tra documenti, come esportare e importare XFDF con PDFium Component, dovrebbe seguire la stessa regola: copiate le modalità che la sorgente aveva davvero e lasciate a False tutti gli altri sentinel
Un pattern read-modify-write che resta a misura di PDF/A
Lascia i sentinel di appearance esattamente come il getter li ha restituiti, e valida il file salvato prima di spedirlo. Dato che uno stream vuoto stantio si rilegge come assente, il passo di verifica deve guardare il documento serializzato anziché il record, e costa abbastanza poco da girare dopo ogni batch:
uses
PDFium, FPdfPdfa; // FPdfPdfa dichiara TPdfAValidationIssue
function AnnotationAppearancesAreClean(Pdf: TPdf): Boolean;
var
Report: TPdfAValidationResult;
begin
// Valida il documento attualmente caricato in Pdf, incluse le modifiche
// fatte tramite Pdf.Annotation[] da quando è stato aperto
Report := Pdf.ValidatePdfA;
Result := not (pvaiAnnotationApDictViolation in Report.Issues);
end;
La stessa disciplina vale per qualsiasi pannello che ricolora o annota pagine per la revisione, un workflow trattato in costruire un workflow di revisione annotazioni in Delphi con PDFium Component: il record è uno snapshot di ciò che l'engine riusciva a leggere, e un sentinel che non avete impostato voi dovrebbe tornare indietro invariato. L'API completa delle annotazioni, il preflight PDF/A e il motore nativo PDFium viaggiano insieme in PDFium Component for Delphi, C++Builder and Lazarus