Technisch artikel

Annotatie-appearance-roundtrips in Delphi met PDFium

In PDFium Component schrijft het lezen van een annotatie via TPdf.Annotation[] en het terugschrijven van het record niets nieuws weg wanneer niets veranderde: de getter meldt alleen een appearance die hij daadwerkelijk heeft gelezen, dus een annotatie die alleen /N draagt gaat terug met alleen /N. Het detail is het begrijpen waard, omdat een leeskant die appearances te veel meldt lege /R- en /D-entries toevoegt aan de /AP-appearance-dictionary, PDF/A-validators die dictionary afwijzen, en de gebruikelijke aanleiding een fix is die een bestand conformeerder moest maken, niet minder

Diagram van de PDFium Component annotatie-roundtrip waarbij het toevoegen van afPrint via TPdf.Annotation[] en SetAnnotationData ook lege /R- en /D-streams zou wegschrijven via FPDFAnnot_SetAP als de getter appearances te veel meldde, waardoor een PDF/A-schone appearance-dictionary verandert in een die veraPDF verwerpt, terwijl een getter die alleen de appearances meldt die hij werkelijk las hem schoon houdt
Lege rollover- en down-appearance-streams die een te veel meldende getter terugschrijft zijn wat PDF/A laat zakken, niet de Print-vlag die u bedoelde toe te voegen

Wat gaat er mis wanneer u een annotatie ongewijzigd terugschrijft?

Het korte antwoord: als de leeskant appearances te veel meldt, krijgt de annotatie appearance-streams die ze nooit had, en een bestand dat vóór uw bewerking door de PDF/A-validatie kwam valt er daarna doorheen. Het typische scenario verloopt zo. Een klantarchief komt binnen met vierkant- en tekstannotaties zonder de Print-vlag, PDF/A eist dat elke annotatie print, dus u loopt de pagina's af, voegt afPrint toe en schrijft elk record terug. Niets in die code raakt appearances aan. Het record uit TPdf.Annotation[] is een TPdfAnnotation, en SetAnnotationData schrijft elk veld weg waarvan de Has*-sentinel staat, precies zoals de HasContents / ContentsText-paren bedoeld zijn. De valkuil is een getter die HasAppearanceRollover en HasAppearanceDown op True zet met lege strings voor modi die niet bestaan; de setter schrijft dan plichtsgetrouw twee lege streams weg. De getter van PDFium Component meldt alleen wat hij las, dus de lus hieronder schrijft alleen de appearances terug die de bron had:

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];
          // De getter meldt alleen de appearances die hij las, dus een bron
          // met alleen /AP/N wordt teruggeschreven met alleen /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 definieert de appearance-dictionary met drie entries: /N voor de normale appearance, /R voor rollover en /D voor down. /R en /D zijn optioneel, en wanneer ze ontbreken valt een viewer terug op /N. Een lege /R-stream is echter niet afwezig. Het is een geldige stream die niets tekent, dus een viewer die rollover-appearances eert toont een leeg vierkant zodra de aanwijzer over de annotatie beweegt. PDF/A is nog strenger: ISO 19005-1 (met Corrigendum 2) en ISO 19005-2 / 19005-3 staan in een annotatie-appearance-dictionary alleen /N toe. veraPDF meldt zo'n bestand onder regel 6.5.3-4 voor PDF/A-1 en regel 6.3.3-2 voor PDF/A-2 en PDF/A-3, en de ingebouwde TPdf.ValidatePdfA zet het op de lijst als pvaiAnnotationApDictViolation. Een bewerking die de Print-vlag toevoegt om aan één clausule van de standaard te voldoen, kan een andere breken

De annotatie-appearance-dictionary uit ISO 32000-1 met normal-, rollover- en down-entries: PDFium geeft 2 bytes terug voor een ontbrekende stream en voor een bestaande lege, dus beide lezen via TPdf terug als geen inhoud, terwijl alleen een controle op byteniveau zoals TPdf.ValidatePdfA de lege stream vindt die PDF/A verbiedt
Een ontbrekende /R valt terug op /N; een lege /R tekent een leeg vierkant en zakt alsnog door PDF/A, en via het record zijn de twee niet van elkaar te onderscheiden

Waarom geeft FPDFAnnot_GetAP 2 terug voor een ontbrekende appearance?

PDFium geeft nooit nul terug uit FPDFAnnot_GetAP, ook niet wanneer de gevraagde appearance-stream niet bestaat. De functie volgt het gebruikelijke PDFium-twee-aanroepen-patroon: geef een nil-buffer door om de benodigde grootte in bytes te krijgen, alloceer, roep dan opnieuw aan om UTF-16LE-tekst te kopiëren. De grootte omvat altijd de UTF-16-beëindiger, dus een ontbrekende stream meldt 2 bytes, een lege string plus zijn beëindiger. De voor de hand liggende poort, ByteLength >= SizeOf(FPDF_WCHAR), is een controle die elke aanroep haalt, dus een getter daarop gebouwd meldt alle drie de HasAppearance*-vlaggen als True voor elke annotatie met überhaupt een appearance. Een round trip door het record vraagt FPDFAnnot_SetAP dan per modus een lege string op te slaan, en PDFium maakt de stream om haar te huisvesten. Geen exception, geen waarschuwing, en de zichtbare pagina ziet er identiek uit, wat verklaart waarom deze fout in een PDF/A-validator boven water komt en niet in een viewer

Hoe FPDFAnnot_GetAP een ontbrekende appearance-stream in PDFium meldt: het twee-aanroepen-patroon geeft altijd ten minste twee bytes terug voor de UTF-16-beëindiger, een naïeve poort die tegen SizeOf(FPDF_WCHAR) vergelijkt haalt elke aanroep en zet alle HasAppearance-sentinels op true, terwijl de poort van PDFium Component meer dan de beëindiger plus een even aantal bytes eist
Twee bytes is de gecodeerde lege string, geen bewijs dat een appearance bestaat; de getter van PDFium Component behandelt alles op of onder de beëindigerlengte als geen inhoud en het terugschrijven blijft geruisloos

Hoe PDFium Component beslist dat een appearance bestaat

ReadAppearance, de helper in GetPageAnnotation die AppearanceNormal, AppearanceRollover en AppearanceDown vult, behandelt een resultaat alleen als inhoud wanneer het ten minste één teken voorbij de beëindiger draagt. De eerste aanroep moet meer dan SizeOf(FPDF_WCHAR) bytes teruggeven en een even aantal bytes, want een oneven lengte kan geen UTF-16 zijn. De tweede aanroep, die de tekst werkelijk kopieert, wordt opnieuw gevalideerd: een teruggegeven lengte van 2 of minder, of één groter dan de toegewezen buffer, zet HasValue terug op False en laat de string leeg. Aan de schrijfkant roept SetAnnotationData FPDFAnnot_SetAP alleen aan voor modi waarvan de HasAppearance*-vlag True is, dus een record gelezen uit een annotatie die alleen /N heeft schrijft alleen /N terug

Ontbrekende en lege streams zien er identiek uit, dus de getter blijft conservatief

De native API kan een ontbrekende appearance-stream niet onderscheiden van een die bestaat maar leeg is, en dat suggereert PDFium Component ook niet. Beide gevallen geven dezelfde 2 bytes terug uit FPDFAnnot_GetAP, dus beide lezen terug als HasAppearanceRollover = False met een lege AppearanceRollover. Dat heeft twee gevolgen waar u uw ontwerp op moet inrichten. Ten eerste betekent een False-sentinel "er is geen inhoud gelezen, dus een terugschrijfactie laat deze modus met rust", niet "de /R-sleutel ontbreekt in de dictionary". Ten tweede kan het record een lege stream die al in het bestand zit niet detecteren: een document dat al een lege stream draagt, van wie dan ook, leest schoon terug, en het record terugschrijven herstelt hem niet maar maakt het ook niet erger. Om die bestanden te vinden heeft u een controle op byteniveau nodig, en daarvoor bestaan TPdf.ValidatePdfA en de PDF/A-preflight-validatieworkflow met PDFium Component

Hoe wist u een appearance met opzet?

U zet de sentinel expliciet en geeft een lege string door; de setter schrijft haar weg. Lege strings blokkeren in SetAnnotationData zou een botte manier zijn om verdwaalde streams te vermijden, maar het zou ook aanroepers breken die een appearance bewust wissen, hetzelfde contract dat HasContents en HasAuthor voor tekst volgen. Dus de getter draagt de voorzichtigheid, en de setter doet wat de aanroeper vraagt:

// Vervang de rollover-appearance en wis haar daarna weer
A := Pdf.Annotation[0];
A.HasAppearanceRollover := True;
A.AppearanceRollover := 'q Q';
Pdf.Annotation[0] := A;

A := Pdf.Annotation[0];
// A.HasAppearanceRollover is True en de tekst round-tript als 'q Q'
A.HasAppearanceRollover := True;   // bevestig de bedoeling expliciet opnieuw
A.AppearanceRollover := '';        // schrijf bewust een lege stream weg
Pdf.Annotation[0] := A;

A := Pdf.Annotation[0];
// Leest terug als HasAppearanceRollover = False met een lege string:
// een lege stream en een ontbrekende zijn hier niet te onderscheiden

Bedenk dat een bewust geleegde /R of /D onder de hierboven geciteerde PDF/A-regels nog steeds als extra sleutel telt. Is het doel een archiefprofiel, dan is het schrijven van een niet-lege /N en de andere twee modi met rust laten de enige vorm die valideert. Elke workflow die annotaties tussen documenten verplaatst, zoals XFDF-export en -import met PDFium Component, zou dezelfde regel moeten volgen: kopieer de modi die de bron werkelijk had en laat de overige sentinels op False

Een read-modify-write-patroon dat PDF/A-veilig blijft

Laat de appearance-sentinels precies zoals de getter ze teruggaf, en valideer het opgeslagen bestand voordat u het verscheept. Omdat een achtergebleven lege stream als afwezig terugleest, moet de verificatiestap naar het geserialiseerde document kijken in plaats van naar het record, en die is goedkoop genoeg om na elke batch te draaien:

uses
  PDFium, FPdfPdfa;  // FPdfPdfa declareert TPdfAValidationIssue

function AnnotationAppearancesAreClean(Pdf: TPdf): Boolean;
var
  Report: TPdfAValidationResult;
begin
  // Valideert het document dat nu in Pdf is geladen, inclusief bewerkingen
  // gedaan via Pdf.Annotation[] sinds het werd geopend
  Report := Pdf.ValidatePdfA;
  Result := not (pvaiAnnotationApDictViolation in Report.Issues);
end;

Dezelfde discipline geldt voor elk paneel dat pagina's van kleur voorziet of van aantekeningen voor review, een workflow uit het bouwen van een Delphi-annotatie-reviewworkflow met PDFium Component: het record is een momentopname van wat de motor kon lezen, en een sentinel die u niet zelf heeft gezet moet ongewijzigd terugreizen. De volledige annotatie-API, PDF/A-preflight en de native PDFium-engine verschepen samen in PDFium Component for Delphi, C++Builder and Lazarus