THotPDF.SaveIncrementalUpdate

THotPDF

寫出稀疏的增量修訂版，同時保留每一個原始來源 byte

Delphi 語法：

procedure SaveIncrementalUpdate(const TargetFile: TFileName);

C++ 語法：

void __fastcall SaveIncrementalUpdate(System::Sysutils::TFileName TargetFile);

procedure SaveIncrementalUpdate(const TargetFile: TFileName); overload;

有界 overload

procedure SaveIncrementalUpdate(const TargetFile: TFileName;
  MaxOutputBytes: Int64; Checkpoint: TNotifyEvent); overload;

正數的 MaxOutputBytes 要求先呼叫 BeginIncrementalUpdate，並為完整原始前綴加上附加 delta 設定上限；負數上限無效，零則保留舊有的無上限行為

正數上限的 overload 會把 delta 溢寫到暫存儲存，序列化超過上限時在發布前擲回 EHPDFIncrementalOutputBudget，該失敗路徑會保留既有目標

Checkpoint 在物件走訪與發布複製期間收到文件，寫入期間收到內部溢寫緩衝；請勿依賴特定的 Sender 型別

對不同的目標而言，這個底層儲存不是原子替換 API；發布期間的取消或 I/O 失敗可能留下部分檔案，需要對外原子發布時，請使用私有候選檔或經驗證的增量簽章工作

說明

SaveIncrementalUpdate 完成 BeginIncrementalUpdate 啟動的工作流程。只有變更、新增與刪除的物件會被走訪並輸出，連同稀疏的 xref 子區段，以及 /Prev 指向前一個修訂版的 trailer

目標不同時，原始前綴會從檔案支援的來源循序複製，再附加完成的 delta。目標相同時，HotPDF 會驗證來源身分、長度與寫入時間，釋放惰性來源 handle，直接附加、沖寫檔案，附加失敗時截回原始長度。兩條路徑都保留既有 byte 範圍與較早的簽章

沒有物件是 dirty 或被刪除時，目標與來源 byte 完全一致，不附加任何 xref 區段、trailer、換行或 EOF 標記。需要修訂版時，第一個 trailer ID 保持穩定，只輪換第二個修改 ID

加密來源的附加 trailer 會保留原始的 /Encrypt 表示法：間接字典保留其物件與 generation 參照，直接的 trailer 字典則保留不變的 security handler bytes。重寫的字串與串流仍受來源 security handler 保護，產生的文件也繼續接受原始 Standard user 與 owner 密碼，或公鑰收件者憑證

成功對同一目標進行附加後，持有的來源會被消耗，因為原始修訂版已被就地變更。建立下一個修訂版前，請再次呼叫 BeginIncrementalUpdate。GetIncrementalUpdateSourceInfo 會公開保留的位元組、探測位元組、拷貝與附加計數、追蹤的變更、走訪過的物件、xref 項目、鎖定與消耗狀態

破壞性編輯會自動重建完整的活動自由物件鏈。既有的 free generation 會保留，新釋放的 generation 遞增至 65535，重寫的物件保留原本的 generation，且每個輸出項目都按物件編號排序。GetLastIncrementalXRefRebuildInfo 在儲存後回報來源、轉換、飽和與重建鏈計數

新增後續簽章修訂版時，請在準備或插入新簽章之前呼叫本方法。附加後的檔案存在之後，再用一般的簽署輔助方法保留並填入新的簽章值

對已認證或含使用權限的文件，SaveIncrementalUpdateAuthenticated 會寫出同目錄的候選檔，驗證每個帶政策的簽章，強制執行每個後續修訂版，並只在所有政策都接受更新後，才以原子方式替換目標

另請參閱： BeginIncrementalUpdate, MarkDirty, SaveIncrementalUpdateAuthenticated, GetIncrementalUpdateSourceInfo, GetLastIncrementalXRefRebuildInfo, AcroForm 支援, PDF Filter 支援