Teknik Makale

Delphi'de PDFium Progressive Download ve İptal (FPDFAvail)

Sayfa sayısı sıfır olan null olmayan bir belge handleı, FPDFAvail_GetDocumentin hiç linearize edilmemiş bir PDF üzerinde, FPDFAvail_IsDocAvail henüz PDF_DATA_AVAIL bildirmişken bile döndürebileceği şeydir. Handle açık görünür, hiçbir şey şikayet etmez ve görüntüleyici boş bir belge gösterir. PDFiumun erişilebilirlik APIsi, ISO 32000-1 Ek Findaki linearize düzeni okur; başka her dosyanın tamamlanması ve sıradan custom-document yoluyla açılması gerekir. O yönlendirme kararı, indirme sürerken bir PDF açmanın yarısıdır. Diğer yarısı, dosyanın çeyreğinde sekmeyi kapatan ve birazdan aynı bağlantıyı yeniden açan kullanıcılardır

TPdfProgressiveDocumentın arkasındaki erişilebilirlik döngüsü

PDFium Componentte bütün oturum TPdfProgressiveDocumentta yaşar; rastgele erişimli bir akış dolarken PDFium erişilebilirlik sağlayıcısını canlı tutan bir TPdf alt sınıfıdır. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount), destek akışını ve uzak dosyanın mantıksal boyutunu (Content-Length, yerel deponuzun güncel uzunluğu değil) alır, bir IsDataAvail callbacki ile bir AddSegment callbacki bağlar ve FPDFAvail_Create çağırır. OpenProgressiveDocument başarıya ulaşınca nesne, herhangi bir aktif TPdf gibi davranır: sayfa, metin, render ve kaydetme hep alışıldık üyeler üzerinden çalışır

Her ayrıştırma adımı kodunuza sorulan bir sorudur. PDFium bir aralık istediğinde bileşen, aralık AvailableByteCountun tanımladığı bitişik önekin içindeyse ya da RangeRequests zamanlayıcısı üzerinden tamamlanmış bir aralığın içindeyse evet der. Bir OnDataAvailable handlerı sonra son sözü söyler; seyrek bir önbelleğin ikisinin de tanımlayamadığı aralıkları böyle yanıtlaması budur. CheckDocumentAvailability üç TPdfDataAvailability değerinden birini döndürür (pdaAvailable, pdaNotAvailable, pdaError) ve PDFiumun istediği bayt aralıklarını sıralı, birleştirilmiş bir TPdfDownloadRanges dizisi olarak verir. O aralıklar siz gördüğünüzde çoktan rrpImmediate önceliğiyle zamanlayıcıya kuyruklanmıştır; ipucu dizisi loglama ve ilerleme gösterimi içindir, iş kuyruğu RangeRequestsdir

// FetchRange sizin taşımanızdır (HTTP Range GET, soket, blob okuyucu):
// Store'a Offset'e Size bayt yazar ve kaç tanesinin geldiğini döndürür
function FetchRange(Store: TStream; Offset, Size: UInt64): UInt64; forward;

procedure OpenWhileDownloading(Pdf: TPdfProgressiveDocument; Store: TStream;
  RemoteSize: UInt64);
const
  MaxRounds = 64;
var
  Hints: TPdfDownloadRanges;
  State: TPdfDataAvailability;
  Request: TPdfRangeRequest;
  Round: Integer;
begin
  Pdf.BeginProgressiveLoad(Store, RemoteSize, False);
  State := pdaNotAvailable;
  for Round := 1 to MaxRounds do
  begin
    State := Pdf.CheckDocumentAvailability(Hints);
    if State <> pdaNotAvailable then
      Break;
    // İpuçları hâlihazırda kuyruktadır; önce baytları yaz, sonra tamamla
    while Pdf.RangeRequests.TryDequeue(Request) do
      Pdf.RangeRequests.CompleteRequest(Request,
        FetchRange(Store, Request.Offset, Request.Size));
  end;
  if State <> pdaAvailable then
    raise EPdfError.Create('The document could not be discovered');
  Pdf.OpenProgressiveDocument;
end;

O döngüdeki iki ayrıntı ağırlık taşır. Tur sınırı vardır çünkü ölü bir bağlantı, CheckDocumentAvailabilityi her çağrıda aynı aralıkları sormaya iter ve sınırsız bir döngü bir ağ arızasını takılmış bir arayüze çevirir. Sıralama önemlidir çünkü zamanlayıcı kendi durumunu bir critical section ile serileştirir ama arka depodaki TStream.Position için hiçbir şey yapmaz. Taşıma threadi, yanıt baytlarını CompleteRequesti çağırmadan önce akışa yazmak zorundadır; PDFium, tamamlanma duyurulduğu an o aralığı okuyabilir. Eşzamanlı yazarların konumlu G/Çsi ya da kendi kilidi gerekir

PDFium Component'te TPdfProgressiveDocument kullanılabilirlik döngüsü: BeginProgressiveLoad, FPDFAvail sağlayıcısını kurar; CheckDocumentAvailability, rrpImmediate önceliğiyle kuyruğa alınmış sıralı birleşik indirme ipuçlarını verir; taşıma, CompleteRequest her aralığı PDFium'a yayımlamadan önce baytları depoya yazar; döngü, ölü bir bağlantı aynı aralıkları istemeyi sürdüreceği için 64 turda sınırlıdır
Baytları yazın, sonra isteği tamamlayın: bir tamamlanma yayımlandığı anda PDFium o aralığı okuyabilir ve akış konumunu sizin için koruyan hiçbir şey yoktur

AvailableByteCount geriye gitmeyi neden reddeder?

AvailableByteCount yalnızca büyür. Daha küçük bir değer atamak, "Available byte count cannot move backwards" ile bir EPdfError fırlatır; çünkü erişilebilirlik callbacki bir kez PDFiuma bir aralığın var olduğunu söylediyse, parser o aralıktan nesneleri çoktan okuyup önbelleğe atmış olabilir. Baytları sonradan geri almak, PDFiumu kaynağını erişilebilirlik yanıtlarının artık reddettiği nesnelerle bırakır. Aynı setter LogicalFileSizeden büyük değerleri de reddeder ve oturum dışında "No progressive load is active" fırlatır

Sondaki kontrol, elinizdeki baytların ait olduğu yeri belirler. Önceki bir ziyaret dosyanın ilk 300 KBini önbellekte bıraktıysa o sayıyı AInitialAvailableByteCount olarak geçin; bileşen onu FPDFAvail_Create koşmadan kaydeder, PDFiumun başlığa ilk bakışı onu görmüş olur. Başlangıç sayısı sıfırken Linearization, PDFium başlığı görmeden plnUnknown okur; normal başlangıç durumu budur

Öneki yükseltmek aynı zamanda işleri de iptal eder. Yeni duyurulan baytlarla çakışan, havadaki her istek artık gereksizdir; zamanlayıcı onu düşürür ve için OnCancelRequest tetikler; o istek için geç gelen bir CompleteRequest False döndürür. Düzensiz dolan bir deponun kendini önekle ifade etmeye çalışmaması gerekir. Aralıkları zamanlayıcı üzerinden tamamlayın ya da OnDataAvailableda aralık başına yanıt verin. O handlerın içinde fırlayan bir exception C callback sınırını geçemez; bileşen onu yakalar, aralığı eksik bildirir ve PDFium bir sonraki kontrolde yeniden sorar

Kısmen inmiş bir PDF gerçekte ne zaman açılabilir?

Yalnızca linearize bir PDF, dosyanın tamamı gelmeden açılır. OpenProgressiveDocument, Linearization özelliğine bakar (plnUnknown, plnNotLinearized, plnLinearized) ve yükleyiciyi seçer. Linearize bir dosya, ilk sayfa bölümü ve ipucu tabloları yerindeyken FPDFAvail_GetDocument üzerinden açılır. Linearize olmayan bir dosya, aynı dosya erişim kaydı üzerinden FPDF_LoadCustomDocumentten geçer ve böyle bir dosya için PDFium belgeyi ancak her bayt yerindeyken erişilebilir bildirir. Açılıştaki sıfır sayfalık handleın görüntüleyicinize gelmemesini sağlayan yönlendirme budur

OpenProgressiveDocument, PDFium Component'te kısmi bir indirmeyi nasıl yönlendirir: linearized dosya, ilk sayfa bölümü ile ipucu tabloları gelince FPDFAvail_GetDocument üzerinden açılır; linearize edilmemiş dosya FPDF_LoadCustomDocument ile her baytı ister; LoadAvailablePage, sayfa denetiminden önce form kullanılabilirliğini FPDFAvail_IsFormAvail ile denetler ve null olmayan sıfır sayfalı tanıtıcı tuzağından kaçınır
Yalnızca linearized dosyalar erken başlangıç kazanır; gerisinde FPDFAvail_GetDocument, sıfır sayfalı açık görünen bir belge döndürebilir ve yönlendirmenin engellediği de tam olarak budur

İlk sayfanın ne kadar çabuk görüneceğine sunucudaki dosya karar verir. İlk boyamaya kadar geçen süre önemliyse ve yayınlama tarafını kontrol ediyorsanız, dosyaları orada linearize edin. TPdf.SaveAsLinearized, Ek F düzenini bileşenin kendisinden yazar ve Fast Web View ve ipucu tabloları anlatımı o düzenin ne taşıdığını ele alır. Kontrol etmediğiniz dosyalar için linearize olmayan bir PDF de aynı döngüden yüklenir; pdaAvailablea erken değil yüzde 100de ulaşır

LoadAvailablePage, 1 tabanlı bir sayfa numarası alır ve PDFiumun beklediği sırayı korur. İlk sayfa kontrolünden önce CheckFormAvailabilityı koşar — FPDFAvail_IsFormAvailı sarar — ve ancak sonra FPDFAvail_IsPageAvaili çağırır. pfaNotPresent, AcroFormu olmayan bir belge için normal cevaptır ve hiçbir şeyi engellemez. Sayfa hazır olduğunda LoadAvailablePage onu aktif sayfa yapar; bir görüntüleyici böylece sonraki sayfalar hâlâ yoldayken linearize bir broşürün 1. sayfasını render edebilir. Sayfa bekleyişi ilk listelemeyle aynı şekildedir: LoadAvailablePage çağırın, pdaNotAvailablede RangeRequestsi boşaltın, pdaAvailable ya da pdaErrorda durun ve bir tur sınırı tutun. FirstAvailablePageNumber, linearization sözlüğünün ilk olarak adlandırdığı sayfayı, PDFiumun sıfır tabanlı indeksinden çevrilmiş haliyle bildirir. Linearize olmayan bir dosyada her sayfa hemen pdaAvailable bildirir, çünkü belge ancak dosya tamamlanınca açılabilirdi

Aralık zamanlayıcısında yeniden denemeler, kısa okumalar ve öncelikler

FPDFAvail_* APInin kendisi ağlardan hiç anlamaz. Parserın şu an hangi baytlara ihtiyaç duyduğunu söyler ve sonra yeniden sorar; istek, yeniden deneme ya da iptal kavramı yoktur. Bunları TPdfRangeRequestScheduler sağlar ve dört kuralı taşıma kodunuzu biçimlendirir

  • Kısa bir yanıt ilerleme sayılır. İstenenden az baytla CompleteRequest(Request, BytesReceived), öneki yayımlar ve kalanı kuyruklar. Kısa yanıt ayrıca başarısız bir deneme sayılır; kalan bölüm hâllâ MaxRetryCounta bağlıdır ve o tükenince terk edilir. Sıfır bayt düz bir başarısız denemedir
  • MaxRetryCount öntanımlı 2dir; bir aralık toplamda üç deneme alır. FailRequest, aralığı yeniden kuyrukladığında True, terk edildiğinde False döndürür; Statistics.AbandonedRequestCount kaç tanesinin vazgeçtiğini izler
  • MaxRequestSize, büyük aralıkları kuyruktan çıkarılırken parçalara böler ve MergeGap, iki bekleyen aralığın küçük bilinmeyen bir boşluk boyunca birleşmesine izin verir; ama asla hâllâ tamamlanmış ya da havadaki baytların üzerinden
  • CheckDocumentAvailability ile LoadAvailablePagedaki ipuçları rrpImmediate ile gelir. Doğrudan bir CheckFormAvailability çağrısından gelen form ipuçları rrpNormal ile gelir; LoadAvailablePage o kontrolü kendisi yaptığında ve form verisi eksik olduğunda ipuçları rrpImmediate ile kuyruklanır. TryDequeue daima önce en yüksek önceliği ve bir öncelik içinde en düşük ofseti servis eder

Öncelik kuralı prefetch yaparken karşılığını verir. Belge açılır açılmaz dosyanın tamamını rrpBackgroundda kuyruklayın; zamanlayıcı hâllâ tamamlanmış ya da havadaki her şeyi düşer, telle yalnızca eksik baytlar gider. Kullanıcı sonra 40. sayfaya atladığında ve o sayfanın ipucu hâllâ inen bir arka plan parçasıyla çakışıyorsa zamanlayıcı arka plan isteğini çeker, için OnCancelRequest tetikler, çakışmayan kuyrukları yeniden deneme saymadan arka plan önceliğine geri koyar ve çakışmayı taze immediate iş olarak kuyruklar. Atlama bağlantıyı kazanır. Olmasaydı sayfa isteği, umursamadığı 256 KBlik bir parçanın arkasında beklerdi

procedure TDownloadForm.QueueRestOfFile;
var
  Whole: TPdfDownloadRanges;
begin
  FPdf.RangeRequests.MaxRequestSize := 256 * 1024;  // parça boyutu size kalmış
  SetLength(Whole, 1);
  Whole[0].Offset := 0;
  Whole[0].Size := FPdf.LogicalFileSize;
  FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;

// Bir HTTP Range yanıtı bitince worker threadinde çağrılır.
// WriteAt, arka depoya kendi konumlu yazımınızdır
procedure TDownloadForm.RangeFinished(const Request: TPdfRangeRequest;
  const Body: TBytes; Succeeded: Boolean);
begin
  if Succeeded and (Length(Body) > 0) then
  begin
    WriteAt(FStore, Request.Offset, Body);              // önce baytlar
    FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
  end
  else if not FPdf.RangeRequests.FailRequest(Request) then
    TThread.Queue(nil, ShowRangeGaveUp);  // terk edilmiş ya da iptal edilmiş bir oturumdan
end;

CompleteRequest ile FailRequestin ikisi de worker threadinden çağrılmaya uygundur; zamanlayıcı kendi kilidini alır. Yerine başka bir istek geçmiş ya da iptal edilmiş bir oturuma ait olan bir istek, hiçbir şeye dokunmadan False ile döner; worker, aralığının neden bayatladığını bilmek zorunda değildir

CancelProgressiveLoad neyi, hangi sırayla serbest bırakır?

CancelProgressiveLoad bir oturumu dört adımda, daima aynı sırada söker: aralık zamanlayıcısını iptal et, belgeyi kapat, erişilebilirlik handleını FPDFAvail_Destroyle yok et, sonra callback kayıtlarını ve akış adaptörünü serbest bırak. Zamanlayıcıyı önce iptal etmek üretim sayacını ilerletir, her bekleyen ve havadaki isteği düşürür ve havadaki her biri için OnCancelRequest tetikler. Sonradan ulaşan bir taşıma tamamlanması eski üretimi taşır ve CompleteRequest False döndürür. Belge, erişilebilirlik handleı ile akış adaptörü gitmeden önce kapanır; çünkü PDFium bir belgeyi kapatırken dosya erişim sağlayıcısı üzerinden okumaya devam edebilir

PDFium Component'te CancelProgressiveLoad sabit sökme sırası: önce aralık zamanlayıcısını iptal et ki geç tamamlanmalar yükselen kuşak sayacına çarpsın ve False dönsün; dosya erişim adaptörü kaybolmadan belgeyi kapat; kullanılabilirlik tanıtıcısını FPDFAvail_Destroy ile yok et; ancak ondan sonra callback kayıtlarını at ve akış adaptörünü serbest bırak
Tek bir idempotent yöntem, başarısız bir başlangıcı, kullanıcı iptalini ve yıkıcıyı aynı biçimde temizler; depoya yazan bir worker thread varken akış sahipliği sizde kalır
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
  FPdf := TPdfProgressiveDocument.Create(nil);
  // Zamanlayıcı FPdf ile aynı ömürlüdür; bir kez bağlayın
  FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;

procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
  Attempt: Cardinal);
begin
  FTransport.Abort(RequestId);   // sizin kodunuz: o soketi ya da isteği kapat
end;

procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
  FPdf.CancelProgressiveLoad;
  // ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;

Metot idempotenttir ve üç durum için tek temizlik yolu olarak hizmet eder: kurulumu yarıda başarısız olan bir BeginProgressiveLoad, açık bir kullanıcı iptali ve destructor. BeginProgressiveLoad da onu çağırır; böylece önceki oturum açmaya varmadan bitmediyse aynı nesneyi yeni bir URLde yeniden başlatmak sorun değildir. OpenProgressiveDocument başarıya ulaştıktan sonra nesne aktiftir ve BeginProgressiveLoad alışıldık "Cannot perform this operation on an active" hatasını fırlatır; önce CancelProgressiveLoad çağırın. OnCancelRequest ayrıca soketlerinizin kapatıldığı tek yerdir; zamanlayıcının soketin ne olduğu hakkında hiçbir fikri yoktur. İçinde fırlayan exceptionlar istek başına yutulur; başarısız tek bir abort geri kalanını engelleyemez

Depoya yazan, ona sahip olanı da belirler. Bir worker thread destek akışına yazarken AOwnsStream = False geçirin ve worker durduktan sonra akışı kendiniz serbest bırakın. Sahipliği devretmek, iptalin akışı serbest bırakması ve hâllâ yolda olan bir yazım demektir. Arayan dışında bir thread depona dokunuyorsa sahipliği tutun; AOwnsStream = True yalnızca ilk listeleme gibi tümüyle senkron bir taşımaya uyar

Tam dosyayı bekleyen özellikler

Bazı özellikler ayrıştırılmış belgeyi değil, özgün dosya baytlarını ister ve eksik bir progressive kaynağı tümüyle reddeder. ReadXmpPacket, "PDF/A metadata is unavailable until progressive loading completes" fırlatır. ValidatePades, SourceStatusı pvssIncomplete olan bir sonuç döndürür; ValidatePdfMac, tam kaynağı isteyen bir mesajla unsupported bildirir. BeginIncrementalSave de başarısız olur; çünkü artımlı bir güncelleme, yüklenmiş tam baytların üzerine eklemek zorundadır

Hepsinin arkasındaki tamlık testi, AvailableByteCountin LogicalFileSizee ulaşmasıdır. Her şeyi zamanlayıcı üzerinden teslim eden bir taşıma bu yüzden her baytı tutuyor olabilir ve yine de kaynağın eksik söylenebilir; bitişik önek hiç kıpırdamamıştır. Zamanlayıcı tam kapsamı onaylayınca öneki yayımlayın:

procedure TDownloadForm.CheckSignaturesWhenComplete;
var
  Report: TPadesValidationResult;
begin
  if FPdf.RangeRequests.IsRangeAvailable(0, FPdf.LogicalFileSize) then
    FPdf.AvailableByteCount := FPdf.LogicalFileSize;
  Report := FPdf.ValidatePades;
  if Report.SourceStatus = pvssIncomplete then
    LabelStatus.Caption := 'Signatures are checked when the download finishes'
  else
    ShowSignatureReport(Report);   // sizin arayüzünüz
end;

Bu işler başlamadan önce uygulanan tek boyut sınırı vardır. Windowsda FPDF_FILEACCESS dosya uzunluğunu 32-bitlik bir alanda tutar; BeginProgressiveLoad, 4 GiB üstü bir mantıksal boyutu, PDFiumun kırpılmış bir uzunlukla ayrıştırmasına izin vermek yerine bir EPdfError ile reddeder

Tam bir yerel dosyayı istek üzerine akış adaptörüyle yüklemek için PDFium ile büyük PDFleri istek üzerine akıtmak yazısına; daha büyük bir tamponun içinde duran bir PDF için gömülü PDFler için byte range yükleme yazısına bakın. Gelmiş bir sayfanın yavaş renderını durdurmak başka bir mekanizmadır; iptal edilebilir progressive sayfa renderı yazısında işlenir. TPdfProgressiveDocument, aralık zamanlayıcısı ve SaveAsLinearized, Delphi ve C++Builder için PDFium Componentin parçasıdır