MergeFiles

Componente: TPdf · Unità: PDFium

Unisce sorgenti PDF basate su file tramite le API native di importazione pagine, delimitando gli handle delle sorgenti ed esponendo criteri operativi espliciti

Syntax

function MergeFiles(const Sources: TPdfBatchMergeSources; out Report: TPdfBatchMergeReport): Boolean; overload;

function MergeFiles(const Sources: TPdfBatchMergeSources; const Options: TPdfBatchMergeOptions; out Report: TPdfBatchMergeReport): Boolean; overload;

class function TPdfBatchMergeSource.FromFile(const AFileName: string; const APageRange: string = ''; const APassword: string = ''): TPdfBatchMergeSource; static;

class function TPdfBatchMergeOptions.Default: TPdfBatchMergeOptions; static;

Source selection

FileName identifica una singola sorgente PDF basata su file
Password viene applicata prima dell'apertura della sorgente
PageRange è un elenco in base 1 separato da virgole, ad esempio 1,3,5-7
Un PageRange vuoto importa tutte le pagine
L'ordine di selezione e i numeri di pagina ripetuti vengono preservati

Default options

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize`, attualmente 128 pagine
InsertAt	-1, che accoda alla destinazione
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Resource and cancellation policy

bmrpSourceScoped esegue una singola importazione nativa per sorgente, consentendo a PDFium di riutilizzare la propria mappa di oggetti clonati su tutte le pagine selezionate di quella sorgente

bmrpChunked suddivide la selezione in lotti di PageChunkSize, offrendo punti di annullamento più fini e chiamate native più piccole al costo di una possibile duplicazione delle risorse tra lotti

Al massimo una sorgente TPdf è aperta alla volta e ogni sorgente viene chiusa subito dopo il suo tentativo di importazione

L'annullamento viene verificato tra le operazioni sulle sorgenti e tra i lotti nativi; una singola chiamata di importazione PDFium non può essere interrotta

OnProgress riceve le fasi started, opening, importing, source, rollback, cancellation, failure e completion e può impostare il proprio parametro Cancel; ogni istantanea TPdfBatchMergeProgress riporta Stage, SourceIndex, SourceCount, FileName, SourcePageCount, ImportedSourceCount, ImportedPageCount e NativeImportCallCount

Il TPdfBatchMergeReport restituisce Status, SourceCount, AttemptedSourceCount, ImportedSourceCount, SkippedSourceCount, FailedSourceCount, ImportedPageCount, CommittedPageCount, RolledBackPageCount, PageCountBefore, PageCountAfter, NativeImportCallCount, LargestNativeImportPageCount, PeakOpenSourceCount, FormSourceCount, OutlineSourceCount, DestinationCreated, ViewerPreferencesSourceIndex, ErrorMessage e Issues

CancellationToken accetta lo stesso contratto IPdfCancellationToken usato dalle API asincrone e progressive

Forms, outlines, and viewer preferences

bmfpPreserveNative mantiene l'importazione native best-effort di pagine e widget di PDFium ma non risolve i conflitti di albero dei campi AcroForm, di campi con lo stesso nome, di risorse, di aspetto predefinito o di ordine di calcolo
bmfpFlatten genera le appearance e appiattisce solo le pagine sorgente selezionate prima dell'importazione
bmfpReject rifiuta le sorgenti AcroForm e XFA
bmopDiscard importa le pagine senza ricostruire la struttura della sorgente, mentre bmopReject rifiuta le sorgenti che contengono una struttura
Le viewer preferences vengono copiate con approccio best-effort dopo importazioni di pagine riuscite dalla prima sorgente andata a buon fine quando CopyViewerPreferences è abilitato; ViewerPreferencesSourceIndex resta -1 quando quella sorgente non ha voci supportate

Failure and rollback

Una sorgente che fallisce dopo che uno o più lotti hanno inserito pagine viene sempre riportata allo stato precedente al suo confine di sorgente prima della gestione di stop o skip

bmepSkip registra il problema e continua con la sorgente successiva, mentre bmepStop termina l'operazione

Con RollbackOnCancelOrFailure=True, i fallimenti di tipo stop e l'annullamento rimuovono tutte le pagine inserite dall'operazione; una destinazione creata dall'operazione viene chiusa

Con il rollback disabilitato, le sorgenti importate con successo restano confermate e si riflettono in CommittedPageCount

Il rollback rimuove le pagine inserite ma non può garantire l'inversione di ogni effetto collaterale nativo sul catalog, come i metadati del producer

Report

Status è bmrsCompleted, bmrsCompletedWithErrors, bmrsCancelled o bmrsFailed

Il report separa le sorgenti tentate, importate, ignorate e fallite dalle pagine importate, confermate e sottoposte a rollback

NativeImportCallCount, LargestNativeImportPageCount e PeakOpenSourceCount rendono misurabile la politica di schedulazione scelta

Issues conserva indice di sorgente, nome del file e testo dell'errore per i fallimenti e per gli errori non fatali delle callback terminali

Example

var
  Sources: TPdfBatchMergeSources;
  Options: TPdfBatchMergeOptions;
  Report: TPdfBatchMergeReport;
begin
  SetLength(Sources, 2);
  Sources[0] := TPdfBatchMergeSource.FromFile('part-a.pdf', '1-10');
  Sources[1] := TPdfBatchMergeSource.FromFile('part-b.pdf', '3,1', Password);
  Options := TPdfBatchMergeOptions.Default;
  Options.ErrorPolicy := bmepSkip;
  Options.FormPolicy := bmfpFlatten;
  if not Pdf.MergeFiles(Sources, Options, Report) then
    Log(Report.ErrorMessage);
end;