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 在解码期间使用的私有内存

示例

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);

参见

Attachment, AttachmentCount, AttachmentDescription, AttachmentName, AttachmentType