Delphi'den bir PDF/A-3 belgesine kaynak dosya eklemek için PDFium Component, PDF 2.0 associated-file zinciri yazar: MIME /Subtype taşıyan gömülü bir dosya akışı, /AFRelationship taşıyan bir dosya belirtimi ve kataloğa ya da bir sayfaya asılı bir /AF dizisi. InjectAssociateFiles ile TPdf.SaveAsWithAssociateFiles o zinciri tek bir artımlı güncellemede kurar; MIME türü tek, doğru kaçışlı bir PDF name olarak serileştirilir. Yazının kalanı bir doğrulayıcının neyi denetlediğini, text/plain'i kıran tek karakterlik tuzağı ve bir yazım hatasının ya da okunamayan bir trailer'ın yanlış dosya üretmesini önleyen kontrolleri kapsar
Bir PDF/A-3 associated file aslında neye ihtiyaç duyar?
Bir PDF/A-3 eki, yalnızca üç nesne birbiriyle aynı fikirde olduğunda doğrulamayı geçer: gömülü dosya akışı /Type /EmbeddedFile artı bir MIME /Subtype bildirir, dosya belirtimi sözlüğü (ISO 32000-2 §7.11.3) /F, /UF, /EF ve /AFRelationship taşır ve belgedeki bir şey o dosya belirtimine bir /AF dizisi üzerinden referans verir (ISO 32000-2 §14.13). TPdf.CreateAttachment'ın yaptığı türden düz gömme, /Names /EmbeddedFiles ağacı üzerinden, ilişki alanlarını hiç kurmaz. Bir PDF/A-3b doğrulama turu bağımlılığı somutlaştırır: yalnızca /AFRelationship anahtarını yeniden adlandırın ve dosya ISO 19005-3'ün 6.8 maddesinde tam olarak tek kuralda düşer; yalnızca MIME /Subtype'ı atın ve farklı bir 6.8 kuralı düşer; aynı eki bir PDF/A-1b adayına koyun ve tümüyle reddedilir, çünkü PDF/A-1, üst veri ne kadar derli toplu olursa olsun gömülü dosyaları yasaklar
İlişki değeri, insanların tahmin etmeye eğilimli olduğu kısımdır. FPdfAssocFiles içindeki TPdfAFRelationship, enjektörün basabileceği her name tokenina bir enum üyesi eşler ve ilk beşi ISO 19005-3'ün tanıdığı alt kümeye aittir:
afSource→/Source: PDF'in üretildiği özgün belge; bir kelime işlemci dosyası ya da elektronik tablo gibiafData→/Data: görünür içeriğin türetildiği ya da temsil ettiği makine okunur veriafAlternative→/Alternative,afSupplement→/Supplement,afUnspecified→/UnspecifiedafEncryptedPayload,afFormData,afTemplate: PDF/A-3 alt kümesinin dışına düşen PDF 2.0 ekleri; arşiv çıktısında bunları uzak tutun
/Subtype /text/plain doğrulamayı neden kırar?
Bu bir tokenization hatasıdır, uyumluluk boşluğu değil. Çağıranın dizesini doğrudan bir eğik çizginin ardına bitiştirin ve /Subtype /text/plain elde edersiniz. PDF sözdiziminde ikinci eğik çizgi yeni bir name nesnesi başlatır (ISO 32000-1 §7.3.5); akış sözlüğü bir anda /Subtype anahtarını, /text name'ini ve anahtar-değer çiftlerini dengesizleştiren başıboş bir /plain fazlasını taşır. Bağımsız bir PDF/A doğrulayıcı böyle bir dosyayı, daha bir PDF/A kuralına varmadan, EmbeddedFile sözlüğünü ayrıştırırken reddeder; başarısızlığın eksik bir ek özelliği gibi değil dosya bozulması gibi görünmesinin nedeni budur
PDFium Component MIME değerini EscapePdfName'den geçirir; bu, /text#2Fplain basar: çözülen değeri text/plain olan tek bir name. Kaçış, eğik çizgiden bilinçli olarak geniştir. 32 ve altındaki her bayt (boşluk, tab, CR, LF), 127 ve üstündeki her bayt, ()<>[]{}/% ayraçları ve # kaçış karakterinin kendisi #XX olur. Yalnızca eğik çizgiyi kaçışlamak başka bir delik bırakırdı: >> içeren ya da boşluk taşıyan bir MIME dizesi sözlüğü erken kapatabilir ya da fazladan anahtarlar enjekte edebilirdi
// MIMEType = 'text/plain'
// naif bitiştirme: /Type /EmbeddedFile /Subtype /text/plain (iki name)
// enjektör çıktısı: /Type /EmbeddedFile /Subtype /text#2Fplain (tek name)
//
// Çağıranlar daima sıradan MIME değerini geçirir. Kendiniz önceden kaçışlarsanız
// '#' çift kodlanır; 'text#2Fplain', 'text#232Fplain'e döner
Options.Files[0].MIMEType := 'text/plain';
InjectAssociateFiles ile PDF/A-3 dosyası kurmak
PDF/A-3 çıktısı için uyumlu taban belgeyi TPdf.SaveAsPdfAToStream ile üretin, sonra o akış üzerinde InjectAssociateFiles çağırın; PDF/A-3b doğrulamasından geçen ardışık düzen odur. TPdf.SaveAsWithAssociateFiles kolaylık sarmalayıcısıdır ama kaydı, PDF/A yazıcısı yerine saRemoveSecurity'li sıradan SaveAs yoluyla yapar; dolayısıyla PDF/A'nın istediği XMP kimliğini ve çıktı niyetini eklemez. Kayıt tiplerinin FPdfAssocFiles ile FPdfPdfa'da olduğuna dikkat edin; iki unit de uses cümlenizde olmalı. v3.121.3'ten beri FileName ile Description yalın ASCII ile sınırlı değildir: /UF ile /Desc PDF metin dizeleri olarak yazılır — yazdırılabilir ASCII harfiyen, geri kalanı bayt sırası işaretli UTF-16BE olarak; eski /F adı ise daima taşınabilir yazdırılabilir ASCII olur ve her başka karakter _ ile değiştirilir; böylece /F'yi kendi kod sayfasıyla çözen okuyucular mojibake yerine alt çizgi görür
uses
System.SysUtils, System.Classes, System.IOUtils,
PDFium, FPdfPdfa, FPdfAssocFiles;
procedure SaveWithSourceData(Pdf: TPdf; const XmlPath, OutPath: string);
var
PdfAOptions: TPdfASaveOptions;
Options: TAssocFilesOptions;
Base: TMemoryStream;
Output: TFileStream;
begin
PdfAOptions := TPdfASaveOptions.Default;
PdfAOptions.Conformance := pac3b;
Options := TAssocFilesOptions.Default; // TargetPage = 0: katalog düzeyi /AF
SetLength(Options.Files, 1);
Options.Files[0].FileName := 'invoice-data.xml';
Options.Files[0].Description := 'Structured invoice data';
Options.Files[0].Content := TFile.ReadAllBytes(XmlPath);
Options.Files[0].Relationship := afData;
Options.Files[0].MIMEType := 'application/xml'; // /application#2Fxml olarak yazılır
Base := TMemoryStream.Create;
try
if not Pdf.SaveAsPdfAToStream(Base, PdfAOptions) then
raise Exception.Create('PDF/A-3 base save failed');
Output := TFileStream.Create(OutPath, fmCreate);
try
InjectAssociateFiles(Base, Output, Options); // Base'i geri sarar; başarısızlıkta EPdfAssocFilesError yükseltir
finally
Output.Free;
end;
finally
Base.Free;
end;
end;
Katalog mu sayfa mı: /AF dizisi nereye düşer?
TAssocFilesOptions.TargetPage, /AF dizisinin sahibine karar verir: 0 onu belge düzeyi bir ilişki olarak kataloğa ekler, 1..N ise o sayfa sözlüğüne ekler, 1 tabanlı. Enjektör her şeyi sabit bir düzende tek bir artımlı güncelleme olarak ekler (gömülü akışlar, sonra dosya belirtimleri, sonra /AF dizisi, sonra yeniden yazılmış katalog ya da sayfa nesnesi); böylece var olan nesneler ofsetlerini korur ve hiçbir şey yeniden sıkıştırılmaz. Hedef sözlükteki önceki her /AF girdisi değiştirilir, birleştirilmez; bu, tekrarlanan bir kaydı idempotent yapar ama farklı bir dosya listesiyle yapılan ikinci çağrının kazandığı anlamına da gelir. TargetPage sıkı denetlenir: SaveAsWithAssociateFiles ile SaveAsWithAssociateFilesToStream, TargetPage 0..PageCount dışındayken EPdfError fırlatır; InjectAssociateFiles negatif bir TargetPage ya da var olmayan bir sayfayı adlandıran bir değer için EPdfAssocFilesError fırlatır ve hedef akışı değiştirmeden bırakır; böylece bir yazım hatası sayfa düzeyi bir ilişkiyi sessizce belge düzeyine çeviremez. TargetPage, belge sayfa sırasında o konumdaki sayfayı adlandırır. Kendi kodunuzda kaçınacağınız tuzak, kaydedilen baytlarda /Type /Page sözlüklerini dosya sırasına göre taramaktır: sayfalar yeniden sıralanınca ya da araya sayfa girince sayfa nesneleri, gösterildikleri sıradan başka bir sırada saklanabilir ve dosya başka bir sayfaya düşer
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
const CsvBytes: TBytes; const OutPath: string);
var
Options: TAssocFilesOptions;
begin
// Menzil dışı bir TargetPage EPdfError fırlatır; önce kontrol etmek hatanın
// sayfayı adlandırmasını sağlar
if (PageNumber < 1) or (PageNumber > Pdf.PageCount) then
raise EArgumentOutOfRangeException.CreateFmt('No page %d', [PageNumber]);
Options := TAssocFilesOptions.Default;
Options.TargetPage := PageNumber;
SetLength(Options.Files, 1);
Options.Files[0].FileName := 'chart-data.csv';
Options.Files[0].Content := CsvBytes;
Options.Files[0].Relationship := afSource;
Options.Files[0].MIMEType := 'text/csv';
if not Pdf.SaveAsWithAssociateFiles(OutPath, Options) then
raise Exception.Create('Associated-file save failed');
end;
AFRelationship'i güvenilir biçimde geri nasıl okursunuz?
TPdf.AttachmentRelationship[Index], bir ekin /AFRelationship name'ini yerli FPDFAttachment_GetAFRelationship ihracı üzerinden döndürür; ama boş dizenin iki olası anlamı vardır, bu yüzden önce AttachmentRelationshipFeaturesAvailable çağırın. Bağlama toleranslı yüklenir: PDFium DLL bu ihracı taşımıyorsa her ilişki boş okunur; bu, basitçe /AFRelationship'i olmayan bir dosya belirtiminden ayırt edilemez. Özellik indeksini AttachmentCount ile paylaşır; bu, /Names /EmbeddedFiles ağacındaki girdileri sayar. Enjektör yalnızca /AF zincirini yazar ve name-tree girdisi eklemez; dolayısıyla InjectAssociateFiles üzerinden eklenen bir dosya o indeksin dışındadır; enjekte edilen zinciri teyit için kaydedilen baytları inceleyin ya da bir PDF/A doğrulayıcı koşturun. O name ağacının iç işleyişi PDFium Component ile Delphi'de PDF ekleriyle çalışma makalesinde kapsanıyor
procedure ReportRelationships(const FileName: string);
var
Pdf: TPdf;
I: Integer;
Rel: string;
begin
if not AttachmentRelationshipFeaturesAvailable then
begin
Writeln('This PDFium build cannot report /AFRelationship');
Exit; // boş yanıt belirsiz olurdu, o yüzden sorma
end;
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FileName;
Pdf.Active := True;
for I := 0 to Pdf.AttachmentCount - 1 do
begin
Rel := Pdf.AttachmentRelationship[I];
if Rel = '' then
Rel := '(no /AFRelationship)';
Writeln(Pdf.AttachmentName[I], ': ', Rel);
end;
finally
Pdf.Free;
end;
end;
SaveAsWithAssociateFiles neyi garanti etmez?
TPdf.SaveAsWithAssociateFiles dosya biçimi zarfını ve istenen dosyaların enjekte edildiğini garanti eder; uyumluluğu değil. Kaydedilen baytlarda okunabilir bir trailer yoksa ya da katalog sözlüğü bulunamıyorsa InjectAssociateFiles hiçbir şey yazmadan EPdfAssocFilesError fırlatır ve SaveAsWithAssociateFiles False döndürür; metot, hedefi açmadan önce tam çıktıyı bir kayıt deposunda kurduğu için reddedilen ya da başarısız bir kayıt, var olan dosyayı olduğu gibi bırakır. Boş bir Files dizisi, belgeyi tasarım gereği değiştirmeden kopyalar. Yükün içeriği de sizin sorumluluğunuzdadır: enjektör bir XML dosyasının biçimsel olarak düzgün olduğunu, MIME türünün baytlarla eşleştiğini ya da taban belgenin gerçekten PDF/A olduğunu denetlemez. Nihai dosyayı, bir doğrulayıcı görene kadar doğrulanmamış sayın; PDFium Component ve PDF/A arşiv uyumluluğu yazısında anlatılan disiplin aynıdır. Gelen sözlükleri kendiniz de ayrıştırıyorsanız aynı #XX name kuralları ters yönde geçerlidir; konu PDF sözlüklerini ayrıştırırken name token tuzakları yazısında ele alınır
Associated files, PDF/A çıktısı, ek üst verisi ve doğrulama aynı bileşende gelir; böylece yukarıdaki hat, derlemede ikinci bir PDF kütüphanesi olmaksızın koşar. API referansı, deneme indirmesi ve lisans seçenekleri PDFium Component ürün sayfasındadır