Articolo tecnico

Round trip degli appearance in Delphi con PDFium

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

Diagramma del round trip delle annotazioni di PDFium Component dove aggiungere afPrint tramite TPdf.Annotation[] e SetAnnotationData scriverebbe anche stream /R e /D vuoti via FPDFAnnot_SetAP se il getter riportasse troppi appearance, trasformando un dizionario di appearance pulito per PDF A in uno che veraPDF rifiuta, mentre un getter che riferisce solo gli appearance davvero letti lo mantiene pulito
Gli stream di appearance rollover e down vuoti riscritti da un getter che riporta troppo sono ciò che fallisce PDF/A, non il flag Print che volevi aggiungere

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

Il dizionario di appearance delle annotazioni da ISO 32000-1 con voci normal, rollover e down: PDFium restituisce 2 byte sia per uno stream mancante sia per uno esistente ma vuoto, quindi entrambi si rileggono come senza contenuto tramite TPdf, mentre solo un controllo a livello di byte come TPdf.ValidatePdfA trova lo stream vuoto che PDF/A vieta
Una /R mancante ricade su /N; una /R vuota dipinge un rettangolo bianco e fallisce comunque PDF/A, e tramite il record le due sono indistinguibili

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 FPDFAnnot_GetAP riferisce uno stream di appearance mancante in PDFium: lo schema a due chiamate restituisce sempre almeno due byte per il terminatore UTF-16, un gate ingenuo che confronta con SizeOf(FPDF_WCHAR) passa ogni chiamata e imposta tutti i sentinel HasAppearance a true, mentre il gate del PDFium Component esige più del terminatore più un numero di byte pari
Due byte sono la stringa vuota codificata, non la prova che un appearance esista; il getter del PDFium Component tratta tutto ciò che sta entro la lunghezza del terminatore come assenza di contenuto e la riscrittura resta silenziosa

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