THPDFHeadlessDocument.SaveAnnotationRemovalsToFile method

function SaveAnnotationRemovalsToFile(const FileName: string;
  const Identities: array of THPDFHeadlessAnnotationIdentity;
  const Options: THPDFHeadlessAnnotationRemovalOptions): Integer;

Prepares page-annotation removals from the currently loaded source and atomically publishes a separate PDF to FileName

Identities selects annotations by valid zero-based page indices and exact decoded Unicode NM values; Options supplies positive resource limits and optional shared cancellation

The return value counts every removed annotation once, including popup and reply dependencies; it can exceed the number of requested identities

An empty request or valid unmatched identities return zero and publish the exact current source bytes; duplicate identities, ambiguous selected names and shared annotation owners fail

Removing an owner removes dependent popups and replies transitively, with finite cycle handling; removing only its popup clears the retained owner's Popup link

A selected or dependent Widget raises hdFieldTypeUnsupported because field-tree deletion is a separate transaction

State and publication

The loaded document remains unchanged after both success and failure; reload the published PDF to adopt a changed revision

A changed output is an incremental revision retaining the original file prefix; zero changes produce an exact copy, and this operation does not securely erase old revisions

The output path must not alias the loaded source; allocation failure, invalid input, policy rejection, budget exhaustion and cancellation preserve the existing destination

Policy and diagnostics

Actual changes require encrypted-document annotation permission and authenticated signed-document policy admission; certification P1/P2 reject changes, whilst admitted P3 changes retain the original signed byte ranges

Invalid identities and malformed ownership report hdInvalidDocument; resource exhaustion reports hdLimitExceeded; Widget selection reports hdFieldTypeUnsupported

Security, signature and cancellation failures retain their existing native diagnostic contracts; configure trust and timestamp requirements through the document's signature-policy options

See THPDFHeadlessAnnotationIdentity, THPDFHeadlessAnnotationRemovalOptions and native annotation removal