Операции с документами через JSON и C ABI

export.structured экспортирует выбранные страницы в семантический HTML, XHTML, XML или JSON; tables.export экспортирует типизированные таблицы в CSV, JSON или XLSX, сохраняя непрерывность через страницы, объединённые ячейки и нативный вывод типов значений

Обе операции требуют бинарное назначение вывода, сохраняют документ и существующие поля подписи и предоставляют ограниченные опции нативного экспорта

Структурированный и типизированный табличный экспорт

{"schemaVersion":1,"type":"export.structured","pages":[0,1],"format":"html",
 "options":{"imageMode":"metadata","includeFormControls":false}}

{"schemaVersion":1,"type":"tables.export","pages":[0,1],"format":"json",
 "options":{"mergeAcrossPages":true,"dateOrder":"dmy",
            "decimalSeparator":",","thousandsSeparator":"."}}

Структурированный экспорт принимает html, xhtml, xml и json (дефолт); табличный экспорт принимает csv (дефолт), json и xlsx

Булевы опции структурного экспорта — includeCoordinates, includeStyles, includeImages, includeTables, includeAccessibilitySemantics, preferTaggedStructure, fallbackToGeometricSemantics, includeNavigation, includeAnnotations и includeFormControls; все по умолчанию равны true

imageMode принимает omit, metadata и embedded-png (дефолт); семантическая модель и поведение чувствительных полей описаны в разделе Структурированный экспорт загруженных страниц

Ресурсные опции структурного экспорта — maxPageCount, maxGlyphsPerPage, maxImagesPerPage, maxStructureNodes, maxOutlineItems, maxInteractionsPerPage, maxFormOptionsPerField, maxOutputBytes, maxImageBytes и maxTotalImageBytes

Булевы опции табличного экспорта — detectMergedCells, detectRepeatedHeaders, mergeAcrossPages и inferValueTypes; все по умолчанию равны true

dateOrder принимает ymd (дефолт), mdy и dmy; разделители должны быть одиночными печатными символами, а пустой thousandsSeparator отключает разделитель тысяч

minimumTableConfidence принимает значения от 0 до 1 и по умолчанию равен 0.55; положительный columnTolerance по умолчанию равен 12 единицам страницы

Ресурсные опции табличного экспорта — maxPageCount, maxGlyphsPerPage, maxTableCount, maxRowCount, maxCellCount, maxTextCharacters и maxOutputBytes; модель ячейки описана в разделе Извлечение типизированных таблиц

Неизвестные имена опций, неверные типы, неподдерживаемые форматы и неположительные лимиты отклоняются; запрошенные нативные лимиты ограничиваются консервативными бюджетами памяти и объектов

Staging экспорта ограничен меньшим из budget.outputBytes и четверти budget.memoryBytes; effectiveOutputLimit сообщает этот потолок, при этом может дополнительно действовать более строгий options.maxOutputBytes

Сбои нативных ресурсов сообщают budget-exceeded, метрику nativeExportResources и нативную диагностику; observed=1 и limit=0 обозначают отказ в ресурсе, а не измеренное потребление байтов

Обе операции сообщают documentUpdated: false, сохраняют исходные настройки auto-launch и декодирования, сначала пишут вывод в staging до публикации и сохраняют существующие файловые назначения после сбоя файлового задания

Проверки дедлайна и отмены ABI callback-ов кооперативны в контрольных точках операции и публикации; нативные cancellation token-ы также действуют внутри поддерживаемых стадий извлечения, при этом нативная работа принудительно не прерывается

THPDFJobProcessor.ExecuteLoadedOperation и hpdf_document_execute_json_v1 делят один и тот же движок документных операций с версионированной схемой

Текущие имена операций, форматы, профиль подписи, поведение callback-ов и дефолтные бюджеты можно узнать через THPDFJobProcessor.Capabilities или hpdf_capabilities_json_to_io

Операции

JSON операции использует UTF-8 и schemaVersion: 1; индексы страниц нумеруются с нуля, а массивы выбранных страниц не могут содержать дубликаты

Замена текста возвращает частичный статус, когда нативный API замены не может закодировать совпадение; проверяйте её постраничные счётчики

OCR-задания с внешними движками принимают явно сконфигурированные движки Tesseract CLI/DLL и RapidOCR CLI/DLL наряду со встроенным ASCII-дефолтом, с типизированными настройками, таймаутами движков, потолками пикселей и атомарной публикацией

Модифицирующие операции отклоняют документы с существующими полями подписи, включая неподписанные placeholder-ы; чтобы сохранить подписи в таких документах, используйте нативные инкрементальные API

Инкрементальное подписание PFX принимает неизменённый удержанный источник, включая поддерживаемые зашифрованные PDF с явным паролем операции, валидирует каждую старую и новую CMS, сохраняет исходные байты и шифрование, поддерживает существующее пустое поле, проверяет права шифрования и отклоняет псевдонимы источника/вывода

Подписание создаёт подписанный артефакт и восстанавливает исходный хендл, сообщая documentUpdated: false; существующие поля форм остаются доступны, временные поля подписи удаляются, и после подписания хендл можно опрашивать или использовать для другой операции

Архивная конвертация в PDF/A-4 растр

{
  "schemaVersion": 1,
  "type": "archive.pdfa4.raster",
  "acceptInformationLoss": true,
  "iccProfileFile": "profiles/sRGB.icm",
  "dpi": 150,
  "input": "source.pdf",
  "output": "archive.pdf"
}

Поместите этот объект в массив operations файлового задания или подайте его напрямую через hpdf_document_execute_json_v1 с загруженным хендлом и callback-ами бинарного вывода; C ABI игнорирует входные/выходные пути файлового задания и использует свои адаптеры

acceptInformationLoss должен быть JSON-булевым true, а iccProfileFile — непустым путём без NUL к поддерживаемому ICC-профилю sRGB matrix/TRC на машине исполнения; относительные пути профилей разрешаются относительно рабочей директории процесса

dpi по умолчанию равен 150 и принимает целые числа от 36 до 1 200; конвертация покрывает каждую исходную страницу и отклоняет любое поле pages

Объект результата archive сообщает nativeValidationSucceeded, sourcePages, pagesRendered, rasterPixels, outputBytes, removedAnnotations, removedFormFields и removedEmbeddedFiles

archive.lossy равен true, а каждый флаг в archive.lossProfile равен false: searchableText, vectorContent, interactiveContent, originalSignatures, annotationAppearances и structureIdentity

Содержимое страниц превращается в RGB-пиксели; аннотации и внешние виды widget-ов опускаются, а исходные подписи не переносятся в вывод. Загруженный источник остаётся доступен с documentUpdated: false, в том числе после неудавшейся публикации; его прежние настройки запуска, декодирования, stream-порога, отмены и рендеринга восстанавливаются

Требуется бинарный вывод, а нативная валидация PDF/A-4 должна завершиться успехом до отдачи результата. Границы рендеринга, цвета, кодеков, алиасов источника и соответствия описаны в разделе конвертация загруженных документов в PDF/A-4 растр

Бюджеты ресурсов архивации

Опциональный объект options принимает точные положительные целые числа, которые ужесточают следующие эффективные потолки; неизвестные ключи и значения сверх потолка отклоняют запрос, а не увеличивают бюджет операции

ICC-файл до аллокации ограничен меньшим из 4 MiB и memoryBytes / 16; эти консервативные допуски учитывают одновременный staging, буферы вывода, данные изображений и работу декодеров и не задают строгого лимита RSS процесса

Когда большой архивный объём задуман намеренно, поднимайте бюджеты задания верхнего уровня; вложенные опции только ужесточают эффективные потолки, а нативные максимумы продолжают действовать

Архивные контрольные точки во время конвертации опрашивают отмену callback-ов, cancellation token заимствованного источника, прошедшее время и счётчики объектов. Сбои бюджета и отмены сохраняют свои структурированные статус-коды сквозь нативный конвертер

Файловые задания

{
  "operations": [
    {"type": "capabilities"},
    {"schemaVersion": 1, "type": "text.extract", "input": "input.pdf",
     "pages": [0, 1], "output": "text.txt"}
  ]
}

THPDFJobProcessor.Execute принимает массив operations — до 1 024 операций и 4 MiB JSON; существующие задания merge, split, optimise, encrypt и validate остаются доступны

Каждая документная операция указывает входной путь и опциональный пароль; render, text.replace, forms.fill, forms.flatten, ocr.layer, redact, sign и archive.pdfa4.raster требуют выходной путь

Артефакты пишутся во временный файл рядом с назначением, сбрасываются на диск, валидируются и затем атомарно публикуются; при сбое существующее назначение сохраняется, а вход и выход могут использовать один путь

Контракт C callback-ов

Обнулите hpdf_operation_v1, задайте struct_size равным нативному размеру структуры, abi_version равным HPDF_ABI_VERSION_1, а flags — нулю; сравните размер структуры с hpdf_abi_operation_v1_size

Запись операции несёт байты JSON с точной длиной, опциональный вход с произвольным доступом, опциональный последовательный бинарный вывод и обязательный последовательный вывод JSON-результата

Входные callback-и, пользовательские данные и лежащие в основе байты PDF должны оставаться валидными, пока хендл не заменён или не уничтожен, поскольку ленивый разбор удерживает адаптер

Callback-и вывода и результата существуют только на время вызова; сериализуйте вызовы для каждого хендла и избегайте повторного входа в callback-и

Callback-и используют cdecl, частичные передачи повторяются, а успешные записи обязаны продвигаться; исключения конвертируются в фиксированные статус-коды

Модификации фиксируются только после успешной доставки и артефакта, и JSON-результата; сбой или отмена callback-а откатывает изменения, а вызывающий код отбрасывает уже доставленные байты

Вход для замены загружается до транзакции модификации и остаётся отдельным изменением состояния

Бюджеты

Опциональный объект бюджета принимает точные положительные целые числа не больше 9 007 199 254 740 991

Общие бюджеты вывода и результата каждый ограничен половиной бюджета памяти; архивная конвертация применяет более строгие потолки выше. Они ограничивают настроенные ресурсы операции, а не всю память процесса

Проверки отмены и прошедшего времени кооперативны в контрольных точках операции, страницы, чтения входа и записи вывода; долгая нативная процедура может продолжаться до своей следующей контрольной точки

Отчёты несут schemaVersion, status и statusCode; ошибки бюджета используют status 8, отмена — 4, сбой I/O — 5, сбой разбора — 6, неверные аргументы — 1, сбой исполнения — 7