PDFium Delphi Component 文件 API 參考

附件批次擷取

元件: TPdf  ·  單元: PDFium
一次清點內嵌附件,並在明確的資源控制下把解碼後的承載寫入呼叫端自有的串流

ReadAttachmentMetadata

function ReadAttachmentMetadata(MaxAttachments: Integer = 10000): TPdfAttachmentMetadataArray;

此方法列舉文件層級附件一次,傳回呼叫端自有的記錄,包含 Index、Name、Description、MimeType、Relationship、解碼後的 Size 與 Readable

MaxAttachments 會在填入結果陣列前檢查,避免不受信任的文件造成無上限的中繼資料配置

大小查詢不會把承載位元組複製進 PDFium Delphi Component 記憶體,不過 PDFium 可能會在內部解碼串流以判定其解碼後長度

ExtractAttachmentsToStreams

function ExtractAttachmentsToStreams(const Destinations: array of TStream; const Options: TPdfAttachmentBatchOptions; out Report: TPdfAttachmentBatchReport; const CancellationToken: IPdfCancellationToken = nil): Boolean;

Destinations 必須為每個文件附件恰好包含一個槽位,並遵循與 Attachment[Index] 相同的以零為基底順序

nil 目的地會把該項目標記為 paesSkipped,讓呼叫端不必再次列舉即可挑選附件

每個非空承載都會透過 PDFium 解碼到一個暫存 PDFium Delphi Component 緩衝區,再從該緩衝區以 ChunkBytes 為單位寫出

緩衝區會在處理下一個附件前釋放,因此 PDFium Delphi Component 不會保留整個批次,但公開的 PDFium 附件 API 不支援範圍讀取,內部可能使用自己的完整承載解碼記憶體

串流仍由呼叫端擁有,寫入從每個串流目前位置開始,方法不會倒轉或截斷串流

取消或目的地例外可能在該串流中留下已寫入的位元組,因此需要交易式輸出的呼叫端應提供暫存串流,並在報告成功後才對外發布

選項

FieldDefaultMeaning
MaxAttachments10000中繼資料與報告項目上限
MaxFileBytes256 MiB單一附件解碼後大小上限
MaxTotalBytes1 GiB寫入所有目的地的位元組總量上限
ChunkBytes1 MiB單次串流寫入傳遞的位元組上限
StopOnErrorTrue遇到第一個無法讀取、超出額度或寫入失敗的項目即停止

報告

每個 TPdfAttachmentMetadata 記錄描述一個原生附件,TPdfAttachmentMetadataArray 儲存中繼資料快照

每個 TPdfAttachmentBatchItem 結合中繼資料、TPdfAttachmentExtractionState、已寫入位元組數與錯誤文字,TPdfAttachmentBatchItems 則儲存所有個別項目結果

TPdfAttachmentExtractionState 的值為 paesNotProcessed、paesSkipped、paesExtracted、paesUnreadable、paesFileLimit、paesAggregateLimit、paesCancelled 與 paesWriteFailed

TPdfAttachmentBatchReport 統計 AttachmentCount、ExtractedCount、SkippedCount 與 FailedCount,另有 BytesWritten 與 PeakBufferBytes

Completed 代表每個項目都在未取消的情況下到達終態,而函式傳回值還另外要求 FailedCount = 0

PeakBufferBytes 回報最大的 PDFium Delphi Component 承載緩衝區,不包括 PDFium 解碼時使用的私有記憶體

Example

var Options: TPdfAttachmentBatchOptions;
var Report: TPdfAttachmentBatchReport;
Options := TPdfAttachmentBatchOptions.Default;
Options.MaxFileBytes := 64 * 1024 * 1024;
Options.MaxTotalBytes := 256 * 1024 * 1024;
if not Pdf1.ExtractAttachmentsToStreams(Destinations, Options, Report) then
  HandleAttachmentBatchFailure(Report);

See Also

Attachment, AttachmentCount, AttachmentDescription, AttachmentName, AttachmentType