Operacje dokumentowe JSON i C ABI

export.structured eksportuje wybrane strony jako semantyczny HTML, XHTML, XML albo JSON, a tables.export eksportuje tabele typowane jako CSV, JSON lub XLSX, zachowując ciągłość między stronami, scalone komórki i natywną inferencję wartości

Obie operacje wymagają binarnego celu wyjściowego, pozostawiają dokument i istniejące pola podpisów nietknięte oraz udostępniają ograniczone natywne opcje eksportu

Eksport strukturyzowany i tabel typowanych

{"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":"."}}

Eksport strukturyzowany przyjmuje html, xhtml, xml i json (domyślnie), a eksport tabel przyjmuje csv (domyślnie), json i xlsx

Opcje boolowskie eksportu strukturyzowanego to includeCoordinates, includeStyles, includeImages, includeTables, includeAccessibilitySemantics, preferTaggedStructure, fallbackToGeometricSemantics, includeNavigation, includeAnnotations i includeFormControls, przy czym wszystkie domyślnie mają wartość true

imageMode przyjmuje omit, metadata i embedded-png (domyślnie); model semantyczny i zachowanie wobec pól wrażliwych opisuje strona Strukturyzowany eksport załadowanych stron

Opcje zasobowe eksportu strukturyzowanego to maxPageCount, maxGlyphsPerPage, maxImagesPerPage, maxStructureNodes, maxOutlineItems, maxInteractionsPerPage, maxFormOptionsPerField, maxOutputBytes, maxImageBytes i maxTotalImageBytes

Opcje boolowskie eksportu tabel to detectMergedCells, detectRepeatedHeaders, mergeAcrossPages i inferValueTypes, przy czym wszystkie domyślnie mają wartość true

dateOrder przyjmuje ymd (domyślnie), mdy i dmy; separatory muszą być pojedynczymi znakami drukowalnymi, a pusty thousandsSeparator wyłącza separator tysięcy

minimumTableConfidence przyjmuje wartości od 0 do 1, domyślnie 0.55; dodatnie columnTolerance ma domyślnie 12 jednostek strony

Opcje zasobowe eksportu tabel to maxPageCount, maxGlyphsPerPage, maxTableCount, maxRowCount, maxCellCount, maxTextCharacters i maxOutputBytes; model komórki opisuje strona Ekstrakcja tabel typowanych

Nieznane nazwy opcji, nieprawidłowe typy, nieobsługiwane formaty i niedodatnie limity są odrzucane; żądane limity natywne są docinane konserwatywnymi budżetami pamięci i obiektów

Etapowanie eksportu jest ograniczone do mniejszej z wartości: budget.outputBytes i jedna czwarta budget.memoryBytes; ten limit raportuje effectiveOutputLimit, a może dodatkowo obowiązywać ciaśniejsze options.maxOutputBytes

Błędy zasobów po stronie natywnej raportują budget-exceeded, metrykę nativeExportResources i diagnostykę natywną; observed=1 i limit=0 oznaczają odmówiony dostęp do zasobu, a nie zmierzony pobór bajtów

Obie operacje raportują documentUpdated: false, zachowują ustawienia auto-launch i dekodowania źródła, etapują wyjście przed publikacją, a po nieudanym zadaniu plikowym zachowują istniejący plik docelowy

Kontrole terminu i anulowania callbacków ABI są kooperatywne w punktach kontrolnych operacji i publikacji; natywne tokeny anulowania działają też wewnątrz obsługiwanych etapów ekstrakcji, a praca natywna nie jest przerywana na siłę

THPDFJobProcessor.ExecuteLoadedOperation i hpdf_document_execute_json_v1 korzystają z tego samego silnika operacji dokumentowych z wersjonowanym schematem

Bieżące nazwy operacji, formaty, profil podpisywania, zachowanie callbacków i domyślne budżety poznasz przez THPDFJobProcessor.Capabilities albo hpdf_capabilities_json_to_io

Operacje

JSON operacji używa UTF-8 i schemaVersion: 1; indeksy stron są liczone od zera, a tablice wybranych stron nie mogą zawierać duplikatów

Zamiana tekstu zwraca status częściowy, gdy natywne API zamiany nie potrafi zakodować dopasowania; sprawdź wtedy liczby dla poszczególnych stron

Zadania zewnętrznego OCR przyjmują jawnie skonfigurowane silniki Tesseract CLI/DLL i RapidOCR CLI/DLL obok domyślnego wbudowanego ASCII, z typowanymi ustawieniami, timeoutami silników, limitami pikseli i publikacją atomową

Operacje modyfikujące odrzucają dokumenty z istniejącymi polami podpisów, łącznie z niepodpisanymi placeholderami; żeby zachować podpisy w takich dokumentach, użyj natywnych API przyrostowych

Przyrostowe podpisywanie PFX przyjmuje niezmodyfikowane zapamiętane źródło, w tym wspierane zaszyfrowane PDF-y z jawnym hasłem operacji, waliduje każdy stary i nowy CMS, zachowuje oryginalne bajty i szyfrowanie, wspiera istniejące puste pole, sprawdza uprawnienia szyfrowania i odrzuca aliasy plików źródła/wyjścia

Podpisywanie wytwarza podpisany artefakt i przywraca pierwotny uchwyt, raportując documentUpdated: false; istniejące pola formularzy pozostają dostępne, tymczasowe pola podpisów są usuwane, a uchwyt po podpisaniu można odpytywać albo użyć do kolejnej operacji

Archiwalna konwersja rastrowa PDF/A-4

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

Ten obiekt umieść w tablicy operations zadania plikowego albo podaj go bezpośrednio przez hpdf_document_execute_json_v1 z załadowanym uchwytem i callbackami wyjścia binarnego; C ABI ignoruje ścieżki wejścia/wyjścia zadania plikowego i korzysta z własnych adapterów

acceptInformationLoss musi być boolowskim true w JSON, a iccProfileFile musi wskazywać niepustą, wolną od NUL ścieżkę do obsługiwanego profilu ICC sRGB matrix/TRC na hoście wykonania; względne ścieżki profili rozstrzygają się względem katalogu roboczego procesu

dpi ma domyślnie 150 i przyjmuje liczby całkowite od 36 do 1,200; konwersja obejmuje każdą stronę źródłową i odrzuca jakikolwiek element pages

Obiekt wyniku archive raportuje nativeValidationSucceeded, sourcePages, pagesRendered, rasterPixels, outputBytes, removedAnnotations, removedFormFields i removedEmbeddedFiles

archive.lossy ma wartość true, a każda flaga w archive.lossProfile wartość false: searchableText, vectorContent, interactiveContent, originalSignatures, annotationAppearances i structureIdentity

Zawartość strony staje się pikselami RGB; adnotacje i wyglądy widżetów są pomijane, a pierwotne podpisy nie przechodzą do wyjścia. Załadowane źródło pozostaje dostępne z documentUpdated: false, także po nieudanej publikacji; wcześniejsze ustawienia uruchamiania, dekodowania, progów strumieni, anulowania i renderowania zostają odtworzone

Wymagane jest wyjście binarne, a natywna walidacja PDF/A-4 musi się powieść przed dostarczeniem wyniku. Granice dotyczące renderowania, kolorów, kodeków, aliasów źródła i zgodności opisuje strona rastrowa konwersja PDF/A-4 załadowanego dokumentu

Budżety zasobów archiwizacji

Opcjonalny obiekt options przyjmuje dodatnie dokładne liczby całkowite, które zaostrzają poniższe efektywne limity; nieznane klucze i wartości przekraczające limit odrzucają żądanie, zamiast zwiększać budżet operacji

Plik ICC przed alokacją jest ograniczony do mniejszej z wartości 4 MiB i memoryBytes / 16; te konserwatywne zapasy uwzględniają równoległe etapowanie, bufory wyjścia, dane obrazów i pracę dekodera, a nie stanowią ścisłego limitu RSS procesu

Gdy większe obciążenie archiwizacyjne jest zamierzone, zwiększ budżety zadania najwyższego poziomu; zagnieżdżone opcje tylko zaostrzają efektywne limity, a maksima natywne nadal obowiązują

Punkty kontrolne archiwizacji odpytują w trakcie konwersji o anulowanie callbacków, pożyczony token anulowania źródła, upływający czas i liczniki obiektów. Błędy budżetu i anulowania zachowują swoje ustrukturyzowane kody statusu w obrębie całego konwertera natywnego

Zadania plikowe

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

THPDFJobProcessor.Execute przyjmuje tablicę operacji — do 1,024 operacji i 4 MiB JSON; istniejące zadania scalania, dzielenia, optymalizacji, szyfrowania i walidacji pozostają dostępne

Każda operacja dokumentowa podaje ścieżkę wejściową i opcjonalne hasło; render, text.replace, forms.fill, forms.flatten, ocr.layer, redact, sign i archive.pdfa4.raster wymagają ścieżki wyjściowej

Artefakty trafiają do pliku tymczasowego obok pliku docelowego, są zapisywane i walidowane, a potem publikowane atomowo; niepowodzenie zachowuje istniejący plik docelowy, a wejście i wyjście mogą współdzielić ścieżkę

Kontrakt callbacków C

Wyzeruj hpdf_operation_v1, ustaw struct_size na jego natywny rozmiar, abi_version na HPDF_ABI_VERSION_1, a flags na zero; rozmiar porównaj z hpdf_abi_operation_v1_size

Rekord operacji przenosi bajty JSON wraz z dokładną długością, opcjonalne wejście o dostępie swobodnym, opcjonalne sekwencyjne wyjście binarne i wymagane sekwencyjne wyjście z wynikiem JSON

Callbacki wejścia, dane użytkownika i bazowe bajty PDF muszą pozostać ważne, dopóki uchwyt nie zostanie podmieniony albo zniszczony, bo leniwe parsowanie zatrzymuje adapter

Callbacki wyjścia i wyniku istnieją tylko w trakcie wywołania; serializuj wywołania dla każdego uchwytu i unikaj ponownego wejścia w callback

Callbacki używają cdecl, transfery częściowe są ponawiane, a udane zapisy muszą robić rzeczywisty postęp; wyjątki są konwertowane na stałe kody statusu

Modyfikacje są zatwierdzane dopiero po udanym dostarczeniu zarówno artefaktu, jak i wyniku JSON; niepowodzenie albo anulowanie callbacku wycofuje zmiany, a wywołujący odrzuca bajty już dostarczone

Wejście zamiany jest ładowane przed transakcją modyfikacji i pozostaje odrębną zmianą stanu

Budżety

Opcjonalny obiekt budżetu przyjmuje dodatnie dokładne liczby całkowite nie większe niż 9,007,199,254,740,991

Ogólne budżety wyjścia i wyniku są każdorazowo ograniczone do połowy budżetu pamięci; konwersja archiwizacyjna stosuje ostrzejsze limity opisane wyżej. Ograniczają one skonfigurowane zasoby operacji, a nie całkowitą pamięć procesu

Kontrole anulowania i upływu czasu są kooperatywne w punktach kontrolnych operacji, strony, odczytu wejścia i zapisu wyjścia; długa natywna procedura może trwać dalej, aż do swojego następnego punktu kontrolnego

Raporty niosą schemaVersion, status i statusCode; błędy budżetu mają status 8, anulowanie 4, niepowodzenie I/O 5, niepowodzenie parsowania 6, nieprawidłowe argumenty 1, a niepowodzenie wykonania 7