In PDFlibPas, de Delphi PDF-bibliotheek, krijgt een pagina die met MovePage is verplaatst eigen kopieën van de waarden MediaBox, CropBox en Resources die hij van zijn oude Pages-node erfde, en een indirecte verwijzing blijft een verwijzing. De verplaatste pagina precies dezelfde objecten geven die de oude Pages-node vasthoudt, is de voor de hand liggende implementatie, en het betekent dat een latere SetPageBox of DrawText op de verplaatste pagina stilletjes die node herschrijft en elke zuster die nog van hem erfde. Dezelfde kopieer-niet-deel-regel dekt twee verwante paden: SetPageBox op een indirecte box die verschillende pagina's delen, en CopyPageRanges, dat overgeërfde waarden op de pagina's van het brondocument materialiseert
Symptomen van dit soort aliasing noemen nooit objectidentiteit. Ze klinken als "ik crop pagina 7 en pagina's 8 tot en met 12 croppen mee", of "ik versmal de CropBox en de MediaBox schuift mee", of, het verwarrendste, "ik kopieer een pagina naar een nieuw document en het originele bestand verandert". Er crasht niets, er lekt niets, en het opgeslagen bestand is perfect geldige PDF. Het bevat alleen geometrie die niemand heeft gevraagd
Hoe kan SetPageBox op één pagina zijn zusters herschalen?
Het gebeurt wanneer twee paginaboom-entries naar één array in het geheugen wijzen en SetPageBox zijn doelarray ter plekke bewerkt: elke pagina of Pages-node die dezelfde instantie vasthoudt, ziet de bewerking. Drie codepaden in een paginaboom-editor kunnen dat delen opleveren:
MovePagematerialiseert de erfelijke attributen op de pagina voordat hij hem van zijn parent losmaakt; de eigen objecten van de voorouder aanhangen in plaats van kopieën laat de verplaatste pagina en zijn voormalige zusters een boxarray en een Resources-woordenboek delen- Een boxschrijver die indirecte verwijzingen volgt en de gerefereerde array bewerkt, herschaalt elke pagina die naar één object
/MediaBox 11 0 Rwijst met een enkele aanroep, ofMovePageer nu bij betrokken was of niet CopyPageRangesmaterialiseert overgeërfde waarden op de bronpagina voordat hij haar in het doeldocument kloont; de instanties van de Pages-node op de bronpagina aanhangen, plus de MediaBox-instantie zelf als standaard CropBox, knoopt ze allemaal aan elkaar
Materialisatie zelf is geen optie. Alleen /Resources meenemen, en een pagina die onder een andere parent wordt verplaatst neemt stilletjes de grootte en rotatie van die parent aan, dus MovePage draagt MediaBox, CropBox en Rotate mee, wat ook is waarop CollateDocumentsEx vertrouwt wanneer hij pagina's herordent. De enige vraag is of die waarden als kopieën aankomen of als gedeelde instanties
Directe waarden, indirecte verwijzingen en pagina-attribuuterfenis
Een correcte kopie van een overgeërfd pagina-attribuut verdubbelt directe waarden en houdt indirecte verwijzingen als verwijzingen, want dat is precies het onderscheid dat ISO 32000-1 zelf trekt. Een direct object zoals [0 0 400 300] binnen een dictionary hoort aan die dictionary alleen. Een indirect object, één keer gedefinieerd als 11 0 obj en aangehaald als 11 0 R, is bij ontwerp gedeeld: ISO 32000-1 §7.3.10 maakt het adresseerbaar vanuit elke hoek van het bestand, en elke 11 0 R betekent hetzelfde object
Pagina-attribuuterfenis, ISO 32000-1 §7.7.3.4, voegt een derde geval toe. Resources, MediaBox, CropBox en Rotate mogen op een Pages-node zitten en gelden voor elke afstammende pagina die geen eigen definitie heeft. De pagina bewaart de waarde niet; hij zoekt de waarde op via /Parent. Die opzoekketen breekt op het moment dat een pagina van parent wisselt, en daarom moeten MovePage en BalancePageTree eerst de effectieve waarden op de pagina zelf wegschrijven. De vraag is alleen hoe ze geschreven worden
Waarom een objectpool de fout verhult
In PDFlibPas is elk geparsed of aangemaakt PDF-object eigendom van de TPDFStructure-pool van het document, en dictionaries en arrays bewaren kale pointers naar hun entries. TPDFDictionary.Add registreert de pointer en niets anders. Eén instantie aan twee parentcontainers toevoegen is daarom legaal op elk niveau dat de runtime kan controleren: geen double free bij het afbreken, geen referentieteller die kan ontsporen, geen exception. Serialisatie is net zo vergevingsgezind, want elke container schrijft de huidige waarde van de gedeelde instantie inline, en vóór elke bewerking is de uitvoer byte voor byte wat een correcte kopie zou opleveren
De aliasing komt pas boven water zodra iemand de gedeelde instantie ter plekke muteert. SetPageBox doet precies dat via een rectangle-wrapper om de bestaande array, en tekenen op een pagina doet hetzelfde met de Resources-dictionary zodra een font of afbeelding wordt geregistreerd. De bewerking landt, stilletjes, in elke andere container die de pointer vasthoudt
Hoe PDFlibPas kopieert in plaats van deelt
PDFlibPas pakt het probleem aan beide kanten aan: materialisatie hangt kopieën aan, en boxbewerkingen bewerken alleen een array die de pagina bezit. Elke regel dekt een geval die de ander niet aankan
De materialisatiehulp, PLInheritPageAttributes, hangt Page.Owner.Decode(Value.Output) aan in plaats van Value zelf. Een roundtrip door de serialiseerder is een botte maar exacte manier om PDF-semantiek gratis te krijgen. Een directe array of woordenboek serialiseert naar zijn letterlijke tekst en decodeert naar een verse, onafhankelijke instantie. Een indirecte verwijzing serialiseert naar 11 0 R en decodeert naar een nieuw verwijzingsobject dat naar hetzelfde object 11 wijst, dus de pagina verwijst nog steeds naar het gedeelde object in plaats van een inline kopie te ontvangen. De kopie is precies zo diep als de directe structuur: alles wat via een verwijzing binnen een gekopieerd woordenboek wordt bereikt, blijft gedeeld, zoals het bestandsformaat bedoelt. BalancePageTree roept dezelfde hulp aan voor elke pagina die hij herparent, dus pagina's die daar worden gematerialiseerd, krijgen ook aparte instanties
Kopiëren alleen is niet genoeg, want het verwijzingsgeval wijst nog steeds naar een gedeeld object. Als SetPageBox die verwijzing zou volgen en object 11 zou bewerken, zou de verplaatste pagina opnieuw de oude parent en zijn andere kinderen herschalen. Dus past de boxschrijver copy-on-write toe: hij bewerkt ter plekke alleen wanneer de eigen entry van de pagina een directe array is, en vervangt een indirecte of ontbrekende box door een nieuwe directe array. Object 11 blijft onaangetast voor elke andere pagina die hem citeert
| Codepad | Instanties delen (de valkuil) | PDFlibPas |
|---|---|---|
MovePage-materialisatie | De pagina houdt de eigen directe instanties van de voorouder vast | De pagina houdt gedecodeerde kopieën vast; verwijzingen blijven verwijzingen |
SetPageBox | Volgt een verwijzing en bewerkt de gedeelde array | Bewerkt alleen een directe array op de pagina, anders schrijft hij een nieuwe |
CopyPageRanges bronpagina | Deelt boxen van de Pages-node; de CropBox is de MediaBox-instantie | Elke waarde die op de bronpagina wordt gematerialiseerd, is een kopie |
| Standaardboxen bij het klonen van paginaresources | CropBox, BleedBox, TrimBox en ArtBox delen één array | Elke standaardbox krijgt zijn eigen array |
De laatste rij is de subtiele. Wanneer de bibliotheek de resources van een pagina kloont voor paginaopname of merging, vult hij de ontbrekende entries CropBox, BleedBox, TrimBox en ArtBox in, en alle vier uit één array-instantie vullen zou een alias achterlaten die wacht op de eerste aanroeper die er één bewerkt. Hoe die standaardboxwaarden worden gekozen is een onderwerp op zich, behandeld in de PDFlibPas-gids voor TrimBox-, BleedBox- en CropBox-standaardwaarden
De MovePage-aliasing reproduceren met een handgebouwd PDF-bestand
De snelste manier om paginaboom-editing te testen op aliasing is een klein handgeschreven PDF-bestand geladen met LoadFromString, waarin elk objectnummer vooraf bekend is. De hulp hieronder schrijft een klassieke cross-reference-tabel met correct berekende byte-offsets, zodat de test niet leunt op het herstelgedrag van de parser voor beschadigde bestanden
uses
System.SysUtils, PDFlibrary;
function BuildPdf(const Objects: array of AnsiString): AnsiString;
var
Offsets: array of Integer;
I, XRefPos: Integer;
begin
Result := '%PDF-1.4'#10;
SetLength(Offsets, Length(Objects));
for I := 0 to High(Objects) do
begin
Offsets[I] := Length(Result); // byte-offset van "N 0 obj", 0-based
Result := Result + AnsiString(IntToStr(I + 1)) + ' 0 obj'#10 +
Objects[I] + #10'endobj'#10;
end;
XRefPos := Length(Result);
Result := Result + 'xref'#10'0 ' + AnsiString(IntToStr(Length(Objects) + 1)) +
#10'0000000000 65535 f '#10;
for I := 0 to High(Offsets) do // elke entry is precies 20 bytes
Result := Result + AnsiString(Format('%.10d 00000 n ', [Offsets[I]])) + #10;
Result := Result + 'trailer'#10'<< /Size ' +
AnsiString(IntToStr(Length(Objects) + 1)) + ' /Root 1 0 R >>'#10 +
'startxref'#10 + AnsiString(IntToStr(XRefPos)) + #10'%%EOF'#10;
end;
function StreamObj(const Content: AnsiString): AnsiString;
begin
Result := '<< /Length ' + AnsiString(IntToStr(Length(Content))) +
' >>'#10'stream'#10 + Content + #10'endstream';
end;
Het testdocument heeft twee tussenliggende Pages-nodes. Node 3 voert een indirecte MediaBox (object 11, 400 bij 300 punten), een directe CropBox en een directe Resources-dictionary, en bezit twee pagina's. Node 4 heeft een Letter-formaat MediaBox en bezit de derde pagina. Pagina 1 naar positie 3 verplaatsen herparent hem onder node 4, en dat is precies de move die materialisatie nodig heeft: zonder die stap zou de pagina een Letter-pagina worden
procedure Check(Condition: Boolean; const Msg: string);
begin
if not Condition then
raise Exception.Create(Msg);
end;
procedure CheckMovedPageIsIsolated;
var
Lib: TPDFlib;
FontID: Integer;
begin
Lib := TPDFlib.Create;
try
Check(Lib.LoadFromString(BuildPdf([
'<< /Type /Catalog /Pages 2 0 R >>',
'<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 3 >>',
'<< /Type /Pages /Parent 2 0 R /Kids [5 0 R 6 0 R] /Count 2 ' +
'/MediaBox 11 0 R /CropBox [10 20 390 280] /Resources << >> >>',
'<< /Type /Pages /Parent 2 0 R /Kids [7 0 R] /Count 1 ' +
'/MediaBox [0 0 612 792] >>',
'<< /Type /Page /Parent 3 0 R /Contents 8 0 R >>',
'<< /Type /Page /Parent 3 0 R /Contents 9 0 R >>',
'<< /Type /Page /Parent 4 0 R /Contents 10 0 R >>',
StreamObj('1 w'), StreamObj('2 w'), StreamObj('3 w'),
'[0 0 400 300]']), '') = 1, 'load failed');
Lib.SelectPage(1);
Check(Lib.MovePage(3) = 1, 'MovePage failed');
Lib.SelectPage(3); // de pagina die we zojuist verplaatsten
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'inherited MediaBox lost');
Lib.SetPageBox(1, 0, 200, 200, 200); // MediaBox 200 x 200
Lib.SetPageBox(2, 0, 100, 100, 100); // CropBox 100 x 100
FontID := Lib.AddStandardFont(4); // Helvetica
Lib.SelectFont(FontID);
Lib.SetTextSize(12);
Lib.DrawText(20, 20, 'MOVED');
// Bekijk de oude parent VÓÓR het selecteren van een andere pagina (zie hieronder)
Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
'font registered in the old Pages node');
Lib.SelectPage(1); // voormalige pagina 2, nog steeds onder node 3
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling MediaBox changed');
Check(Abs(Lib.GetPageBox(2, 2) - 380) < 0.001, 'sibling CropBox changed');
Check(Pos(AnsiString('400'), Lib.GetObjectToString(11)) > 0,
'shared object 11 was rewritten');
finally
Lib.Free;
end;
end;
GetPageBox(BoxType, Dimension) neemt boxtype 1 voor MediaBox en 2 voor CropBox, en dimensie 2 voor breedte. Met de standaard linksonder-oorsprong betekent SetPageBox(1, 0, 200, 200, 200) links 0, boven 200, 200 breed en 200 hoog. Met een materialiseerder die instanties deelt, falen de zustercontroles: de CropBox-bewerking belandt in de directe array van node 3, en een boxschrijver die verwijzingen volgt herschrijft object 11
Verandert CopyPageRanges het brondocument?
CopyPageRanges schrijft wel degelijk op de bronpagina's, maar elke waarde die hij schrijft is een aparte kopie, dus latere bewerkingen op de bron blijven lokaal bij de pagina die u bewerkt. Het schrijven zelf is met opzet: de bronpagina heeft expliciete MediaBox, CropBox, Rotate en Resources nodig voordat zijn woordenboek in het doel wordt gekloond, anders zou de kopie alles verliezen wat hij erfde. Het hernummeren en kopiëren van de pagina naar het doel wordt behandeld in cross-document deep copy van objecten in PDFlibPas; de valkuil zit hier aan de bronkant, die de meeste mensen ervan uitgaan dat een kopie hem alleen leest
Opgeslagen uitvoer laat het nooit zien. Gedeeld of gekopieerd, de gematerialiseerde waarden serialiseren identiek, dus beide documenten slaan hoe dan ook byte voor byte hetzelfde op. Pas een bewerking op het brondocument na de kopie onthult een alias:
procedure CheckSourceSurvivesCopy;
var
Lib: TPDFlib;
SourceID, TargetID: Integer;
begin
Lib := TPDFlib.Create;
try
Check(Lib.LoadFromString(BuildPdf([
'<< /Type /Catalog /Pages 2 0 R >>',
'<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 2 ' +
'/MediaBox [0 0 400 300] /Resources << >> >>',
'<< /Type /Page /Parent 2 0 R /Contents 5 0 R >>',
'<< /Type /Page /Parent 2 0 R /Contents 6 0 R >>',
StreamObj('1 w'), StreamObj('2 w')]), '') = 1, 'load failed');
SourceID := Lib.SelectedDocument;
TargetID := Lib.NewDocument; // wordt het geselecteerde document
Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');
Lib.SelectDocument(SourceID);
Lib.SelectPage(1);
Lib.SetPageBox(2, 50, 250, 100, 100); // alleen de CropBox versmallen
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'MediaBox followed CropBox');
Lib.SetPageBox(1, 0, 200, 200, 200);
Lib.SelectPage(2);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling page resized');
Lib.SelectDocument(TargetID); // de kopie houdt zijn originele grootte
Lib.SelectPage(Lib.PageCount);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
finally
Lib.Free;
end;
end;
Beide pagina's hier erven de directe MediaBox van de root-node. Een kopiestap die die instantie aan bronpagina 1 aanhangt, en haar nog eens aanhangt als CropBox van pagina 1, zou maken dat het versmallen van de CropBox de MediaBox versmalt, en dat het herschalen van de MediaBox pagina 2 herschaalt via de root-node. Workflows die pagina's eruit kopiëren en daarna de bron blijven bewerken, zoals duplexscans colleren tot één PDF voordat de originelen worden bijgesneden, zijn waar dit soort alias opduikt
Waarom is instantie-aliasing zo moeilijk te testen?
Instantie-aliasing is moeilijk te testen omdat het waarneembare effect drie stappen in een specifieke volgorde vergt: de alias aanmaken, de ene kant muteren, en dan de andere kant inspecteren voordat er iets anders aanzit. De meeste tests doen alleen de eerste stap en vergelijken opgeslagen uitvoer, en die is identiek of de alias nu bestaat of niet
De volgordevalkuil in PDFlibPas is SelectPage. Een pagina selecteren past de huidige font opnieuw toe via SelectFont, wat die font registreert in de resources van de pagina. Een pagina zonder eigen /Resources resolveert naar het woordenboek van zijn parent, dus zulke pagina simpelweg selecteren voegt op legitieme wijze /Font toe aan de Pages-node. In de MovePage-test hierboven voegt het selecteren van de voormalige pagina 2 de Helvetica-entry toe aan node 3, wat correct gedrag is en geen lek. Daarom draait de controle GetObjectToString(3) vóór SelectPage(1); wissel de twee om en de test faalt zelfs wanneer er geen alias bestaat
Die regel markeert ook wat PDFlibPas bewust met rust laat. Een resource naar een pagina schrijven die zijn Resources-woordenboek erft, schrijft in het woordenboek van de voorouder, en elke zuster ziet de nieuwe entry. Dat is erfenis zoals gespecificeerd, geen instantiedeling, en hij is ongevaarlijk want het toevoegen van een font- of afbeeldingsnaam aan een gedeeld woordenboek verandert niet hoe andere pagina's renderen. Heeft u nodig dat een pagina stopt met erven, geef hem dan eerst zijn eigen Resources-woordenboek
Checklist voor code op het PDF-objectmodel
De lessen generaliseren naar elk PDF-objectmodel gebouwd op een pool en pointercontainers, in Delphi of elders:
- Bij het materialiseren van overgeërfde attributen volgens ISO 32000-1 §7.7.3.4, deep-copy directe waarden en houd indirecte verwijzingen als nieuwe verwijzingen naar hetzelfde object
- Voeg nooit
Addeen bestaande instantie toe aan een tweede container tenzij het delen bedoeld en gedocumenteerd is; eigendom door een pool betekent dat de runtime nooit klaagt - Bewerk ter plekke alleen wat de huidige node als direct object bezit; vervang indirecte of overgeërfde waarden door een vers direct object (copy-on-write)
- Standaardwaarden die uit een andere entry worden afgeleid, zoals een CropBox uit een MediaBox, hebben hun eigen instantie nodig
- Test aliasing met muteer-dan-inspecteer-reeksen op de andere houder, en controleer de volgorde van aanroepen die tussendoor terecht kunnen schrijven
- Vergelijken van opgeslagen uitvoer bewijst hier niets: gedeelde en gekopieerde waarden serialiseren identiek tot de eerste bewerking
PDFlibPas stelt paginaboom-editing, cross-document kopiëren en paginaboxbeheer bloot via één klasse TPDFlib voor Delphi, C++Builder en Free Pascal. Zie de productpagina van de PDFlibPas Delphi PDF-bibliotheek voor edities, platforms en de volledige API-referentie