THPDFHeadlessDocument
HPDFHeadlessDocument даёт консольный API документов для нативных Linux и Windows, используя существующий парсер объектов HotPDF, хелперы Direct File, декодеры шрифтов, интерпретатор содержимого, декодеры фильтров и писатель xref
Загрузчик документов принимает классические таблицы перекрёстных ссылок, xref-потоки, гибридные xref-секции, инкрементальные цепочки Prev, прямые и сжатые объекты, наследуемые ресурсы страниц, массивы содержимого, Form XObjects и деревья полей AcroForm
Гибридные боковые потоки имеют приоритет над сопровождающей таблицей, а новые ревизии — над старыми; члены object-stream декодируются и разбираются лениво через общий парсер объектов
Жизненный цикл и владение
Create использует THPDFHeadlessDocumentOptions.Default, а перегрузка с опциями принимает явные бюджеты и токен отмены во владении вызывающего
LoadFromFile закрывает предыдущий документ, открывает источник только для чтения, загружает текущий граф объектов и закрывает частичное состояние при сбое; Close освобождает источник и все загруженные объекты
LoadFromFile(FileName, Password) аутентифицирует документы Standard AES-256 R5 или R6 через THPDFHeadlessAES256Security; исходная перегрузка с одним аргументом использует пустой пароль
User-пароли должны разрешать извлечение текста или заполнение форм до выполнения этих операций, а owner-пароли обходят ограничения прав пользователя; неверные пароли, несовпадения аутентифицированных Perms, запрещённые операции и некорректные полезные нагрузки шифра получают разные диагностики документа
Прямые строки и потоки расшифровываются общим криптографическим кодом, сжатые члены расшифровываются только вместе со своим контейнером, а зашифрованные инкрементальные замены остаются зашифрованными исходными ключами и политикой прав
Пароли — байты UTF-8 с обрезкой на 127 байтах и без нормализации SASLprep; неподдерживаемые обработчики, явные Crypt-фильтры и политики PDF MAC диагностируются, а не игнорируются
Закодированные ключи словарей и имена ресурсов декодируются перед использованием, регистр остаётся значимым, дублирующиеся декодированные ключи отвергаются; флаги полей и MaxLen должны помещаться в поддерживаемый неотрицательный 32-битный диапазон
Экземпляры не потокобезопасны; используйте один экземпляр на воркера и держите его токен отмены живым до уничтожения экземпляра
Страницы и текст
PageCount сообщает количество листьев дерева страниц; ExtractPageText(PageIndex) принимает индекс с нуля и возвращает текст Unicode, собранный общим интерпретатором глифов
ExtractPageTextBounded применяет временные лимиты глифов и потоков до подготовки текста и восстанавливает все исходные опции ресурсов после успеха, сбоя или отмены
GetObjectAccess открывает заимствованный доступ только для чтения к каталогу, информации и объектам с ограниченным выделением индексов для нативного структурного и полного сравнения
Декодирование текста следует кодировкам шрифтов, различиям кодировок, встроенным CMap ToUnicode, явным ширинам и провайдеру метрик стандартных шрифтов; вложенные Form XObjects применяют свои матрицы и используют свои или унаследованные словари ресурсов
Linux-fallback на стандартные шрифты требует Fontconfig и установленных шрифтов TrueType; сложные шрифты документа обязаны предоставлять поддерживаемую стратегию декодирования, а отсутствующие ресурсы шрифтов дают диагностику
AppendPageText добавляет видимый или подогнанный невидимый текст Unicode, сохраняя исходное содержимое страниц и зашифрованные политики безопасности
AppendImportedPages клонирует выбранные графы ресурсов страниц, унаследованную геометрию и видимые normal-appearance, сохраняя существующие ревизии назначения и аутентифицированную политику шифрования
Текстовые значения AcroForm
FormFieldCount, GetFormField(FieldIndex) и FindFormField(Name) перечисляют терминальные поля с полностью квалифицированными именами и унаследованными типами полей, флагами, максимальными длинами и значениями; индексы с нуля, отсутствующее имя возвращает -1
SetTextFieldValue(FieldIndex, Text) принимает записываемые поля Tx, пишет строку PDF в UTF-16BE и ставит NeedAppearances=true в словаре AcroForm
Этот метод, меняющий только значение, полагается на регенерацию просмотрщиком; просмотрщики без регенерации appearances могут продолжать показывать старый appearance или пустой виджет
SetTextFieldValueWithAppearance генерирует явные appearance в Unicode для каждого существующего виджета, используя переданный вызывающим шрифт TrueType, реальные метрики глифов, кодировку Identity-H, ToUnicode и полное встраивание FontFile2
Профиль appearance поддерживает однострочный и многострочный текст, переносы, ячейки comb, повороты на четверть оборота, фиксированный размер или автоподгон, выравнивание и опциональный нативный сложный шейпинг HarfBuzz/FriBidi
SetChoiceFieldValuesWithAppearance обрабатывает списки с множественным выбором, унаследованные опции, отсортированные export-массивы и каждую видимую выбранную строку; хелпер с одиночным значением поддерживает также export/display-лейблы combo
GetChoiceFieldValues читает полный массив выбранных export-значений; SetButtonFieldValueWithAppearance и SetPushButtonAppearance генерируют реальные состояния и подписи кнопок
Новые объекты и потоки appearance ограничиваются до изменений полей и при сохранении остаются зашифрованными исходной политикой безопасности AES; нативный Cairo в Linux и независимые читалки потребляют те же сгенерированные объекты
Поля read-only, значения длиннее MaxLen в кодовых единицах UTF-16, нетекстовые поля, XFA-формы, подписанные поля и разрешения сертифицированных документов отвергаются при редактировании
Подписанные документы используют аутентифицированные политики DocMDP и FieldMDP: разрешённые обновления форм сохраняют существующие подписанные ревизии, тогда как заблокированные поля, ограничения P1 и попытки перезаписать подписанные поля подписей отклоняются
Проверенные свидетельства DSS/VRI добавляют аутентифицированные данные сертификатов и отзыва в инкрементальную ревизию, не меняя существующие подписи ByteRange
Проверка подписей
SignatureCount перечисляет подписанные поля подписей AcroForm, а VerifySignature(SignatureIndex, Options) проверяет подписи с нумерацией с нуля, используя общий парсер и стриминговый провайдер OpenSSL 3 CMS
Профиль PDF принимает adbe.pkcs7.detached и автоматически распознаваемый ETSI.CAdES.detached с Contents в шестнадцатеричном или стандартном литеральном виде; CAdES всегда аутентифицирует привязку ESS signing-certificate, а явные настройки CA оценивают доверие отдельно
DocTimeStamp с ETSI.RFC3161 автоматически аутентифицирует настоящий инкапсулированный TSTInfo, ESS, назначение TSA и имя подписанта, а также точный импринт PDF; настроенные корни и CRL таймстампов отдельно оценивают доверие к TSA
Проверка валидирует точный неподписанный промежуток вместе с его ограничителями и привязывает его декодированные байты к текущему словарю подписи до криптографической проверки
Результат различает целостность, явно оценённое доверие к CA и неподписанные байты после аутентифицированной ревизии; неподдерживаемые профили подписи PDF дают типизированную диагностику
Требования рантайма см. в HPDFVerifyHeadlessCMS, бюджеты и настройки доверия — в THPDFHeadlessCMSOptions
Инкрементальные подписи утверждения
SignToFile подписывает существующее записываемое неподписанное поле Sig и публикует независимый инкрементально обновлённый PDF, используя предоставленные вызывающим сертификат PEM и незашифрованный приватный ключ PEM
AddSignatureField создаёт виджет страницы и его связи AcroForm, включая новый AcroForm в обычном импортированном PDF; SetSignatureFieldAppearance генерирует его видимую подпись, а SignPFXToFile загружает идентичность сертификат/ключ PKCS12 с цепочкой
CertificationPermission создаёт первую сертифицирующую подпись DocMDP; P2 и P3 разрешают последующие подписи утверждения в существующих полях, а P1 отвергает дальнейшие подписи
Исходные байты источника и загруженный граф объектов остаются неизменными; последующие подписи утверждения сохраняют байты прежних подписей и их аутентифицированные границы ревизий
Шифрование Standard AES-256 R5 и R6, пароли, ID и права продолжают действовать, включая зашифрованные источники object-stream; строка Contents подписи следует исключению PDF из шифрования
Существующие значения подписей, поля read-only, политики сертифицированных документов, запрещённые разрешения form-fill, расходящиеся токены отмены и исчерпанные бюджеты вывода отвергаются без публикации вывода
Таймстампы документов
TimestampToFile создаёт настоящий таймстамп документа RFC 3161 в существующем неподписанном поле подписи без ключа подписания приложения, используя TSA-транспорт во владении вызывающего и явное доверие к TSA
Писатель сохраняет исходные ревизии и безопасность AES, объявляет расширение ESIC для входных данных до PDF 2.0 и атомарно публикует только после прохождения проверок nonce, импринта, подписи, сертификата, настроенного отзыва и seed
Необходимые аутентифицированные изменения таймстампов документа разрешены при DocMDP и FieldMDP; обычные правки форм и подписи утверждения сохраняют исходные ограничения
Обмен формами FDF и XFDF
ExportAnnotationsFDF экспортирует ограниченные графы объектов аннотаций и их общие ресурсы внешних видов; SaveAnnotationsFDFToFile готовит именованные замены и добавления в независимой атомарной PDF-ревизии
Бинарный профиль FDF аннотаций сохраняет политику шифрования и подписей аутентифицированного документа, контекстно-зависимые локальные ссылки страниц GoTo и точную неизменную публикацию; он оставляет загруженный документ неизменным и после успеха, и после сбоя
SaveAnnotationsXFDFToFile дописывает ограниченные отображённые аннотации в независимую инкрементальную ревизию; HPDFExportHeadlessAnnotationsXFDF возвращает их байты XFDF
ExportFormData возвращает ограниченные данные полей в Unicode, включая реальные массивы выборов и export-состояния checkbox и radio
ImportFormDataToFile перегенерирует настоящие appearance на приватном аутентифицированном графе ревизий и атомарно публикует инкрементальный PDF, сохраняя состояние загруженного источника
ImportRichFormDataToFile импортирует ограниченный профиль XHTML из FDF RV или XFDF value-richtext с реальными программами шрифтов regular, bold, italic и bold-italic
SaveRichTextFieldUpdatesToFile применяет скалярные поля и original typed rich runs в одной независимой атомарной ревизии, сохраняя реальные программы шрифтов и числовую точность PDF; неизменённые защищённые поля требуют совпадающих декодированных appearance и разрешённых ресурсов для каждого виджета
Существующее шифрование, флаги read-only, аутентифицированные DocMDP и FieldMDP, исходные подписи, отмена и бюджеты ресурсов продолжают соблюдаться; поддерживаемый синтаксис и границы скалярного обмена см. в нативных данных форм FDF и XFDF
Заимствованный доступ для рендеринга
GetRenderAccess(PageIndex) через THPDFHeadlessRenderAccess передаёт существующий словарь страницы, унаследованные ресурсы, резолвер шрифтов, разрешение объектов, проверку прав, токен отмены и ограниченные callback'и декодированных потоков
Это последовательный заимствованный вид только для чтения; документ должен оставаться загруженным и неизменным до завершения рендерера, а вызывающие не должны мутировать его открытый граф объектов
Callback RequireOutputPath вида сверяет предполагаемый вывод с каноническим путём источника и физической идентичностью файла, не создавая и не изменяя файлы
Независимый вывод
ExtractPageGlyphs возвращает позиционированные глифы через ограниченный обходчик вложенного содержимого; AnalyzePageSemanticText даёт семантический текст и геометрию источника для нативного сравнения контрактов
SaveToFile(FileName) копирует исходные байты и дописывает замещающие значения объектов, классическую таблицу xref и trailer со связью через Prev; сжатые члены объектов материализуются как прямые объекты в дописанной ревизии, а исходные байты потоков сохраняются
Вывод не должен алиасить путь или физическую идентичность источника; запись использует монопольно созданный staging-файл в каталоге назначения, сбрасывает его на диск и публикует атомарным переименованием
Сбои бюджета, отмены или сериализации сохраняют существующее назначение и удаляют неопубликованный staging-файл; источник остаётся только для чтения
Нативный аннотированный PDF для ревью экспортирует реальные выделения Unicode и видимые appearance с аутентифицированными разрешениями аннотаций, сохраняя исходный загруженный документ и ревизии подписей
Границы формата
Текущий профиль поддерживает шифрование Standard AES-256 R5 и R6, явно диагностирует неподдерживаемые обработчики безопасности и потоковые фильтры и отвергает вышедшие из употребления поколения свободных объектов, которые не может представить его писатель
Bootstrap xref-потоки требуют прямых значений словаря и прямого ограниченного Length; некорректные ширины, перекрытия подсекций, беззнаковые смещения выше Int64, несоответствия сжатых членов, циклы ссылок и настроенные лимиты дают типизированные диагностики
Декодированное содержимое поддерживает фильтры Flate, ASCIIHex, ASCII85 и LZW с поддерживаемыми предикторами и косвенными длинами потоков; полезные данные изображений не декодируются для извлечения текста
Нативные сценарии подписания покрывают поля подписей, видимые appearance и сертификацию; аутентифицированные политики подписанных форм и API таймстампов и долговременной валидации сохраняют свои явные опции целостности и доверия
Приёмка
Именованные rich-семейства шрифтов добавляют несколько реально переданных семейств через SetRichTextFieldValueWithFamilies и ImportRichFormDataWithFamiliesToFile с прежними политиками полей, безопасности и транзакций
Нативные rich-text поля дают typed-стилизованные runs, реальные встроенные appearance стилевых шрифтов, синхронизированные значения V и RV, зашифрованный инкрементальный вывод и ограниченные транзакционные правки; GetRichTextFieldValue читает сохранённый или унаследованный XHTML
Tests/Linux/Run-HeadlessDocumentTests.sh собирает нативный ELF-исполняемый файл с очищенными переменными рабочего стола и проверяет зависимости от GUI-библиотек; Run-HeadlessDocumentTests-Windows.cmd Win32 и Win64 прогоняют тот же общий API документов
Возвращаемые значения и типизированные диагностики см. в THPDFHeadlessFormField, EHPDFHeadlessDocumentError и THPDFHeadlessDiagnosticCode
Удаление аннотаций
Удаляйте аннотации страниц по точной идентичности страницы и NM Unicode через SaveAnnotationRemovalsToFile, с каскадами popup и ответов, ограниченной подготовкой и атомарным отдельным выводом
Загруженный документ остаётся неизменным; выбор без изменений копирует точную текущую ревизию, а инкрементальное удаление сохраняет исторические байты