Technischer Artikel

Annotation-Appearance-Roundtrips in Delphi mit PDFium

In PDFium Component schreibt das Lesen einer Annotation über TPdf.Annotation[] und das Zurückzuweisen des Records nichts Neues, wenn sich nichts geändert hat: Der Getter meldet nur eine Appearance, die er tatsächlich gelesen hat, also geht eine Annotation, die nur /N trägt, mit nur /N zurück. Das Detail lohnt sich zu verstehen, denn eine Leseseite, die Appearances übermeldet, fügt dem /AP-Appearance-Dictionary leere /R- und /D-Einträge hinzu, PDF/A-Validatoren weisen dieses Dictionary zurück, und der übliche Auslöser ist ein Fix, der eine Datei konformer machen sollte, nicht weniger

Diagramm des PDFium-Component-Annotation-Roundtrips: Das Hinzufügen von afPrint über TPdf.Annotation[] und SetAnnotationData würde bei einem übermeldenden Getter zusätzlich leere /R- und /D-Streams über FPDFAnnot_SetAP schreiben und ein PDF/A-sauberes Appearance-Dictionary in eines verwandeln, das veraPDF zurückweist, während ein Getter, der nur die tatsächlich gelesenen Appearances meldet, es sauber hält
Leere Rollover- und Down-Appearance-Streams, die ein übermeldender Getter zurückschreibt, sind es, die an PDF/A scheitern, nicht das Print-Flag, das Sie hinzufügen wollten

Was geht schief, wenn Sie eine Annotation unverändert zurückschreiben?

Die kurze Antwort: Wenn die Leseseite übermeldet, gewinnt die Annotation Appearance-Streams, die sie nie hatte, und eine Datei, die vor Ihrer Bearbeitung die PDF/A-Validierung bestand, fällt danach durch. Das typische Szenario läuft so: Ein Kundenarchiv kommt mit Square- und Text-Annotationen ohne Print-Flag, PDF/A verlangt, dass jede Annotation gedruckt wird, also laufen Sie über die Seiten, fügen afPrint hinzu und weisen jeden Record zurück. Nichts in diesem Code fasst Appearances an. Der Record aus TPdf.Annotation[] ist ein TPdfAnnotation, und SetAnnotationData schreibt jedes Feld, dessen Has*-Sentinel gesetzt ist — genau so sollen die HasContents / ContentsText-Paare arbeiten. Die Falle ist ein Getter, der HasAppearanceRollover und HasAppearanceDown mit leeren Strings auf True setzt für Modi, die nicht existieren; der Setter schreibt dann pflichtbewusst zwei leere Streams. Der PDFium-Component-Getter meldet nur, was er gelesen hat, also schreibt die Schleife unten nur die Appearances zurück, die die Quelle hatte:

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];
          // Der Getter meldet nur die Appearances, die er gelesen hat, also wird
          // eine Quelle mit nur /AP/N mit nur /AP/N zurückgeschrieben
          Pdf.Annotation[I] := A;
        end;
      end;
    end;
    Pdf.SaveAs(ChangeFileExt(FileName, '.printable.pdf'));
  finally
    Pdf.Free;
  end;
end;

ISO 32000-1 §12.5.5 definiert das Appearance-Dictionary mit drei Einträgen: /N für die normale Appearance, /R für Rollover und /D für Down. /R und /D sind optional, und wenn sie fehlen, fällt ein Viewer auf /N zurück. Ein leerer /R-Stream ist aber nicht abwesend. Er ist ein gültiger Stream, der nichts malt, also zeigt ein Viewer, der Rollover-Appearances ehrt, in dem Moment, in dem der Zeiger über die Annotation wandert, ein leeres Rechteck. PDF/A ist noch strenger: ISO 19005-1 (mit Corrigendum 2) und ISO 19005-2 / 19005-3 erlauben in einem Annotation-Appearance-Dictionary nur /N. veraPDF meldet so eine Datei unter Regel 6.5.3-4 für PDF/A-1 und Regel 6.3.3-2 für PDF/A-2 und PDF/A-3, und das eingebaute TPdf.ValidatePdfA listet sie als pvaiAnnotationApDictViolation. Eine Bearbeitung, die das Print-Flag hinzufügt, um einer Klausel des Standards zu genügen, kann eine andere brechen

Das Annotation-Appearance-Dictionary aus ISO 32000-1 mit normal-, rollover- und down-Einträgen: PDFium liefert 2 Bytes für einen fehlenden Stream wie für einen vorhandenen leeren, beide lesen sich über TPdf als ohne Inhalt zurück, und nur ein Byte-Level-Check wie TPdf.ValidatePdfA findet den leeren Stream, den PDF/A verbietet
Ein fehlendes /R fällt auf /N zurück; ein leeres /R malt ein leeres Rechteck und fällt trotzdem durch PDF/A, und über den Record sind beide ununterscheidbar

Warum liefert FPDFAnnot_GetAP für eine fehlende Appearance 2?

PDFium liefert aus FPDFAnnot_GetAP nie null, selbst wenn der angefragte Appearance-Stream nicht existiert. Die Funktion folgt dem üblichen PDFium-Zwei-Aufrufe-Muster: nil-Buffer übergeben, um die benötigte Größe in Bytes zu bekommen, allokieren, dann erneut aufrufen, um UTF-16LE-Text zu kopieren. Die Größe schließt stets den UTF-16-Terminator ein, also meldet ein fehlender Stream 2 Bytes, ein leerer String plus Terminator. Das naheliegende Gate, ByteLength >= SizeOf(FPDF_WCHAR), ist eine Prüfung, die jeder Aufruf passiert, also meldet ein darauf gebauter Getter alle drei HasAppearance*-Flags als True für jede Annotation mit irgendeiner Appearance. Ein Roundtrip durch den Record bittet FPDFAnnot_SetAP dann, für jeden Modus einen leeren String zu speichern, und PDFium erzeugt den Stream dafür. Keine Exception, keine Warnung, und die sichtbare Seite sieht identisch aus — deshalb taucht dieser Fehler in einem PDF/A-Validator auf und nicht in einem Viewer

Wie FPDFAnnot_GetAP in PDFium einen fehlenden Appearance-Stream meldet: Das Zwei-Aufrufe-Muster liefert stets mindestens zwei Bytes für den UTF-16-Terminator, ein naives Gate gegen SizeOf(FPDF_WCHAR) passiert jeden Aufruf und setzt alle HasAppearance-Sentinels auf true, während das PDFium-Component-Gate mehr als den Terminator plus eine gerade Bytezahl verlangt
Zwei Bytes sind der kodierte leere String, kein Beweis, dass eine Appearance existiert; der PDFium-Component-Getter behandelt alles bis hinauf zur Terminator-Länge als keinen Inhalt, und das Zurückschreiben bleibt still

Wie PDFium Component entscheidet, dass eine Appearance existiert

ReadAppearance, der Helfer in GetPageAnnotation, der AppearanceNormal, AppearanceRollover und AppearanceDown füllt, hält ein Ergebnis nur dann für Inhalt, wenn es mindestens ein Zeichen jenseits des Terminators trägt. Der erste Aufruf muss mehr als SizeOf(FPDF_WCHAR) Bytes und eine gerade Bytezahl liefern, denn eine ungerade Länge kann kein UTF-16 sein. Der zweite Aufruf, der den Text tatsächlich kopiert, wird erneut validiert: Eine zurückgegebene Länge von 2 oder weniger oder eine größere als der zugewiesene Buffer setzt HasValue auf False und lässt den String leer. Auf der Schreibseite ruft SetAnnotationData FPDFAnnot_SetAP nur für Modi auf, deren HasAppearance*-Flag True ist, also schreibt ein Record, der aus einer Annotation mit nur /N gelesen wurde, auch nur /N zurück

Fehlende und leere Streams sehen identisch aus, der Getter bleibt konservativ

Die native API kann einen fehlenden Appearance-Stream nicht von einem unterscheiden, der existiert, aber leer ist, und PDFium Component behauptet das Gegenteil nicht. Beide Fälle liefern dieselben 2 Bytes aus FPDFAnnot_GetAP, also lesen beide als HasAppearanceRollover = False mit leerem AppearanceRollover zurück. Das hat zwei Konsequenzen, um die Sie Ihr Design herumbauen sollten. Erstens bedeutet ein False-Sentinel „es wurde kein Inhalt gelesen, ein Zurückschreiben lässt diesen Modus in Ruhe“, nicht „der /R-Schlüssel fehlt im Dictionary“. Zweitens kann der Record einen leeren Stream, der bereits in der Datei steckt, nicht erkennen: Ein Dokument, das bereits einen leeren Stream trägt, egal wer ihn geschrieben hat, liest sich sauber zurück, und das Zurückzuweisen des Records repariert es weder, noch verschlimmert es es. Um solche Dateien zu finden, brauchen Sie einen Byte-Level-Check, und genau dafür sind TPdf.ValidatePdfA und der PDF/A-Preflight-Validierungs-Workflow mit PDFium Component da

Wie löschen Sie eine Appearance absichtlich?

Sie setzen den Sentinel explizit und übergeben einen leeren String; der Setter schreibt ihn. Leere Strings in SetAnnotationData zu blockieren wäre die grobe Methode, um streunende Streams zu vermeiden, hätte aber auch Aufrufer gebrochen, die eine Appearance gezielt leeren — derselbe Vertrag, dem HasContents und HasAuthor für Text folgen. Also trägt der Getter die Vorsicht, und der Setter ehrt weiterhin, was der Aufrufer verlangt:

// Die Rollover-Appearance ersetzen, dann wieder leeren
A := Pdf.Annotation[0];
A.HasAppearanceRollover := True;
A.AppearanceRollover := 'q Q';
Pdf.Annotation[0] := A;

A := Pdf.Annotation[0];
// A.HasAppearanceRollover ist True und der Text läuft als 'q Q' durch
A.HasAppearanceRollover := True;   // Absicht explizit erneut behaupten
A.AppearanceRollover := '';        // absichtlich einen leeren Stream schreiben
Pdf.Annotation[0] := A;

A := Pdf.Annotation[0];
// Liest als HasAppearanceRollover = False mit leerem String zurück:
// ein leerer Stream und ein fehlender sind hier ununterscheidbar

Denken Sie daran: Ein explizit geleertes /R oder /D zählt unter den oben zitierten PDF/A-Regeln weiterhin als zusätzlicher Schlüssel. Wenn das Ziel ein Archivprofil ist, ist das Schreiben eines nicht-leeren /N bei unangetasteten anderen beiden Modi die einzige Form, die validiert. Jeder Workflow, der Annotationen zwischen Dokumenten bewegt, wie XFDF-Export und -Import mit PDFium Component, sollte derselben Regel folgen: Kopieren Sie die Modi, die die Quelle tatsächlich hatte, und lassen Sie den Rest der Sentinels auf False

Ein Read-Modify-Write-Muster, das PDF/A-sicher bleibt

Lassen Sie die Appearance-Sentinels exakt so, wie der Getter sie zurückgeliefert hat, und validieren Sie die gespeicherte Datei, bevor Sie sie ausliefern. Weil ein veralteter leerer Stream sich als abwesend zurückliest, muss der Verifikationsschritt ins serialisierte Dokument schauen statt in den Record, und er ist billig genug, um nach jedem Batch zu laufen:

uses
  PDFium, FPdfPdfa;  // FPdfPdfa deklariert TPdfAValidationIssue

function AnnotationAppearancesAreClean(Pdf: TPdf): Boolean;
var
  Report: TPdfAValidationResult;
begin
  // Validiert das in Pdf aktuell geladene Dokument, einschließlich
  // über Pdf.Annotation[] gemachter Änderungen seit dem Öffnen
  Report := Pdf.ValidatePdfA;
  Result := not (pvaiAnnotationApDictViolation in Report.Issues);
end;

Dieselbe Disziplin gilt für jedes Panel, das Seiten für ein Review umfärbt oder annotiert – ein Workflow, der in Aufbau eines Delphi-Annotation-Review-Workflows mit PDFium Component behandelt wird: Der Record ist ein Schnappschuss dessen, was die Engine lesen konnte, und ein Sentinel, den Sie nicht selbst gesetzt haben, sollte unverändert zurückreisen. Die vollständige Annotation-API, PDF/A-Preflight und die native PDFium-Engine kommen zusammen in PDFium Component for Delphi, C++Builder and Lazarus