Teknik Makale

Delphi'de PDF/A-3 İlişkili Dosyalar ve AFRelationship

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

PDFium Component'te bir PDF A-3 associated file'ının üç nesneli zinciri: application xml gibi MIME Subtype taşıyan bir EmbeddedFile akışı; F, UF, EF ve Data'ya kurulmuş AFRelationship ile bir dosya belirtimi; katalog ya da bir sayfadan ona ait bir AF dizisi — ISO 19005-3 6.8 maddesi geçmeden önce doğrulayıcının denetlediği üç nesne
Akış, dosya belirtimi ve AF dizisi aynı fikirde olmalıdır; TPdf.CreateAttachment'ın düz name-tree gömmesi ilişki alanlarının hiçbirini tasarım gereği kurmaz

İ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 gibi
  • afData → /Data: görünür içeriğin türetildiği ya da temsil ettiği makine okunur veri
  • afAlternative → /Alternative, afSupplement → /Supplement, afUnspecified → /Unspecified
  • afEncryptedPayload, 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

MIME alt türü text slash plain, PDFium Component'te PDF A-3 ayrışmasını neden kırdı: değeri eğik çizgiden sonra bitiştirmek iki name nesnesi üretti; değer olarak /text artı EmbeddedFile sözlüğünü dengesizleştiren başıboş bir /plain; v3.121.2 düzeltmesi değeri EscapePdfName'den geçirir, böylece /text#2Fplain, text/plain'e çözülen tek name olur
Başarısızlık dosya bozulması gibi görünüyordu, çünkü ayrıştırıcıda, herhangi bir PDF/A kuralından önce oluyordu; kaçışlı name, çiftleri dengede tutar ve doğrulayıcıyı okur
// 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

PDFium Component'te AF dizisinin düştüğü yer: TargetPage sıfır onu kataloğa ekler, 1 ile N arası sayfa sözlüğüne ekler ve menzil dışı bir değer istisna fırlatır; enjektör her şeyi var olan ofsetleri koruyan sabit düzenli tek artımlı güncelleme olarak ekler ve önceki her AF girdisini değiştirir
Menzil dışı bir TargetPage sessizce belge düzeyi bir ilişkiye dönüşmek yerine istisna fırlatır ve farklı bir dosya listesiyle yapılan ikinci çağrı kazanır
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