C++ API 参考
PDF Oxide 在其 C ABI 之上提供地道、仅头文件的 C++17 RAII 绑定。每个类都是对核心库的轻量内联封装：句柄被独占且只可移动（move-only），C 字符串和字节缓冲区会被拷贝进 std::string / std::vector<std::uint8_t> 并自动释放，每个非成功的 C 状态码都会抛出 pdf_oxide::Error 异常。
find_package(pdf_oxide_cpp CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE pdf_oxide::pdf_oxide_cpp)
#include <pdf_oxide/pdf_oxide.hpp>
using namespace pdf_oxide; // examples below assume this
所有类型都位于命名空间 pdf_oxide 中。对象通过静态工厂函数（Document::open、DocumentBuilder::create、Certificate::load_from_pem……）构造，而非公有构造函数；每个对象都持有一个原生句柄，在析构时或通过显式 close() 释放。
关于其他语言，请参阅 Python API 参考、Node.js API 参考、WASM API 参考 和 Rust API 参考。关于类型细节，请参阅 类型与枚举。
错误处理
所有失败都会抛出 pdf_oxide::Error，它派生自 std::runtime_error。
class Error : public std::runtime_error;
int32_t Error::code() const noexcept; // underlying C ABI error code
try {
auto doc = Document::open("missing.pdf");
} catch (const pdf_oxide::Error& e) {
std::cerr << e.what() << " (code " << e.code() << ")\n";
}
数据类型
由提取和检查方法返回的纯值结构体。
struct Version { std::uint8_t major; std::uint8_t minor; };
struct Bbox { float x, y, width, height; };
struct Char { std::uint32_t character; Bbox bbox; std::string font_name; float font_size; };
struct Word { std::string text; Bbox bbox; std::string font_name; float font_size; bool bold; };
struct TextLine { std::string text; Bbox bbox; int word_count; };
struct Table { int row_count; int col_count; bool has_header; std::vector<std::string> cells;
const std::string& cell(int row, int col) const; };
struct Font { std::string name, type, encoding; bool embedded; bool subset; };
struct Image { int width, height, bits_per_component; std::string format, colorspace;
std::vector<std::uint8_t> data; };
struct Annotation { std::string type, subtype, content, author; Bbox rect; float border_width; };
struct Path { Bbox bbox; float stroke_width; bool has_stroke, has_fill; int operation_count; };
struct SearchResult { std::string text; int page; Bbox bbox; };
struct Element { std::string type; std::string text; Bbox rect; };
struct FormField { std::string name, value, type; bool readonly; bool required; };
struct QuadPoint { float x1, y1, x2, y2, x3, y3, x4, y4; };
struct EraseRect { float x, y, width, height; }; // batch erase regions
struct RevocationMaterial { std::vector<std::vector<std::uint8_t>> certs, crls, ocsps; }; // PAdES B-LT
RenderedImage
由所有 render_* 方法返回的已渲染页面图像。只可移动；持有原生位图，并在析构时释放。
int width() const noexcept; // image width in pixels
int height() const noexcept; // image height in pixels
const std::vector<std::uint8_t>& data() const noexcept; // encoded image bytes (PNG/JPEG)
void save(const std::string& path) const; // write the encoded image to a file
void close(); // free the native handle now (idempotent)
Document
用于打开、检查、提取、渲染和校验 PDF 的主要类。只可移动；面向读取（如需原地修改请使用 DocumentEditor）。
打开
static Document open(const std::string& path); // open from a file path
static Document open_from_bytes(const std::vector<std::uint8_t>& data); // open from in-memory bytes
static Document open_from_docx_bytes(const std::vector<std::uint8_t>& data);// open a DOCX as a PDF
static Document open_from_pptx_bytes(const std::vector<std::uint8_t>& data);// open a PPTX as a PDF
static Document open_from_xlsx_bytes(const std::vector<std::uint8_t>& data);// open an XLSX as a PDF
void close(); // free the native handle now
文档信息
int page_count() const; // number of pages
Version version() const; // PDF version (major, minor)
bool is_encrypted() const; // true if the document is encrypted
bool has_structure_tree() const; // true if this is a Tagged PDF
bool authenticate(const std::string& password) const; // unlock an encrypted PDF
文本与文档转换
std::string extract_text(int page_index) const; // reading-order plain text for one page
std::string to_plain_text(int page_index) const; // plain text for one page
std::string to_markdown(int page_index) const; // Markdown for one page
std::string to_html(int page_index) const; // HTML for one page
std::string to_plain_text_all() const; // plain text for the whole document
std::string to_markdown_all() const; // Markdown for the whole document
std::string to_html_all() const; // HTML for the whole document
std::string extract_structured_json(int page_index) const; // structured content as JSON
元素提取
std::vector<Char> extract_chars(int page_index) const; // per-glyph characters + font metadata
std::vector<Word> extract_words(int page_index) const; // words with bounding boxes
std::vector<TextLine> extract_text_lines(int page_index) const;// text lines
std::vector<Table> extract_tables(int page_index) const; // detected tables
std::vector<Font> embedded_fonts(int page_index) const; // embedded fonts on a page
std::vector<Image> embedded_images(int page_index) const; // embedded images on a page
std::vector<Annotation> page_annotations(int page_index) const;// page annotations
std::vector<Path> extract_paths(int page_index) const; // vector graphics paths
区域（矩形内）提取
std::string extract_text_in_rect(int page_index, float x, float y, float w, float h) const; // text inside a rectangle
std::vector<Word> extract_words_in_rect(int page_index, float x, float y, float w, float h) const; // words inside a rectangle
std::vector<TextLine> extract_lines_in_rect(int page_index, float x, float y, float w, float h) const;// lines inside a rectangle
std::vector<Table> extract_tables_in_rect(int page_index, float x, float y, float w, float h) const; // tables inside a rectangle
std::vector<Image> extract_images_in_rect(int page_index, float x, float y, float w, float h) const; // images inside a rectangle
自动提取与分类
std::string extract_text_auto(int page_index) const; // auto-mode (native + OCR) text for one page
std::string extract_all_text() const; // reading-order text for the whole document
std::string extract_page_auto(int page_index, const std::string& options_json = "") const; // auto extract with JSON options
std::string classify_page(int page_index) const; // classify one page (JSON)
std::string classify_document() const; // classify the whole document (JSON)
搜索
std::vector<SearchResult> search(int page_index, const std::string& term, bool case_sensitive) const; // search one page
std::vector<SearchResult> search_all(const std::string& term, bool case_sensitive) const; // search the whole document
渲染
RenderedImage render_page(int page_index, int format = 0) const; // render a page (0=PNG, 1=JPEG)
RenderedImage render_page_zoom(int page_index, float zoom, int format = 0) const; // render at a zoom factor
RenderedImage render_page_thumbnail(int page_index, int size, int format = 0) const; // render a thumbnail fitting `size` px
RenderedImage render_page_with_options(int page_index, int dpi, int format,
float bg_r, float bg_g, float bg_b, float bg_a, bool transparent_background,
bool render_annotations, int jpeg_quality) const; // full RenderOptions surface
RenderedImage render_page_with_options_ex(int page_index, int dpi, int format,
float bg_r, float bg_g, float bg_b, float bg_a, bool transparent_background,
bool render_annotations, int jpeg_quality,
const std::vector<std::string>& excluded_layers) const; // as above plus OCG layer filtering
RenderedImage render_page_region(int page_index, float crop_x, float crop_y,
float crop_width, float crop_height, int format = 0) const; // render a rectangular region
RenderedImage render_page_fit(int page_index, int w, int h, int format = 0) const; // render to fit within w x h pixels
RenderedImage render_page_raw(int page_index, int dpi, int& out_width, int& out_height) const; // render to raw RGBA8888
int estimate_render_time(int page_index) const; // estimated render time (ms)
页面几何与元素
float page_get_width(int page_index) const; // page width in points
float page_get_height(int page_index) const; // page height in points
int page_get_rotation(int page_index) const; // page rotation in degrees
std::vector<Element> page_get_elements(int page_index) const; // laid-out page elements
class Page page(int index) const; // a lightweight 0-based page view (see Document::Page)
OCR
bool ocr_page_needs_ocr(int page_index) const; // true if the page benefits from OCR
std::string ocr_extract_text(int page_index, const OcrEngine* engine) const;// OCR text (engine may be nullptr)
页眉 / 页脚 / 伪影移除
int erase_header(int page_index) const; // erase the detected header on a page
int erase_footer(int page_index) const; // erase the detected footer on a page
int erase_artifacts(int page_index) const; // erase detected artifacts on a page
int remove_headers(float threshold) const; // remove repeated headers across the document
int remove_footers(float threshold) const; // remove repeated footers across the document
int remove_artifacts(float threshold) const; // remove repeated artifacts across the document
表单字段
std::vector<FormField> get_form_fields() const; // all interactive AcroForm fields
std::vector<std::uint8_t> export_form_data_to_bytes(int format_type) const; // export field values (0=FDF, 1=XFDF, 2=JSON)
int import_form_data(const std::string& data_path) const; // import field values from a file
bool form_import_from_file(const std::string& filename) const; // import field values (alternate entry)
结构与元数据
std::string get_outline() const; // document outline (bookmarks) as JSON
std::string get_page_labels() const; // page label ranges as JSON
std::string get_xmp_metadata() const; // XMP metadata as JSON
std::vector<std::uint8_t> get_source_bytes() const; // original source PDF bytes
std::string plan_split_by_bookmarks(const std::string& options_json = "") const; // split plan from bookmarks as JSON
签名
int sign(const Certificate& cert, const std::string& reason = "",
const std::string& location = "") const; // sign the document in place
int get_signature_count() const; // number of signatures present
class SignatureInfo get_signature(int index) const;// the index-th signature
int verify_all_signatures() const; // verify every signature
int has_timestamp() const; // document timestamp presence
注释检查
std::uint32_t annotation_get_color(int page_index, int ann_index) const; // packed RGBA colour
std::int64_t annotation_get_creation_date(int page_index, int ann_index) const; // creation date (epoch seconds)
bool annotation_is_hidden(int page_index, int ann_index) const; // hidden flag
bool annotation_is_marked_deleted(int page_index, int ann_index) const; // marked-deleted flag
bool annotation_is_printable(int page_index, int ann_index) const; // printable flag
bool annotation_is_read_only(int page_index, int ann_index) const; // read-only flag
int highlight_annotation_get_quad_points_count(int page_index, int ann_index) const; // number of QuadPoints
QuadPoint highlight_annotation_get_quad_point(int page_index, int ann_index, int quad_index) const; // one QuadPoint
std::string link_annotation_get_uri(int page_index, int ann_index) const; // link annotation URI
std::string text_annotation_get_icon_name(int page_index, int ann_index) const; // text annotation icon name
JSON 检查辅助方法
std::string annotations_to_json(int page_index) const; // page annotations as JSON
std::string elements_to_json(int page_index) const; // page elements as JSON
std::string fonts_to_json(int page_index) const; // page fonts as JSON
float font_get_size(int page_index, int font_index) const; // size of one font
std::string search_results_to_json(int page_index, const std::string& term,
bool case_sensitive) const; // page search results as JSON
Office 转换与 PDF/A
std::vector<std::uint8_t> to_docx() const; // convert the document to DOCX bytes
std::vector<std::uint8_t> to_pptx() const; // convert the document to PPTX bytes
std::vector<std::uint8_t> to_xlsx() const; // convert the document to XLSX bytes
bool convert_to_pdf_a(int level) const; // convert to PDF/A (returns success)
校验
class PdfAResults validate_pdf_a(int level) const; // PDF/A conformance (0=A1b 1=A1a 2=A2b 3=A2a 4=A2u 5=A3b 6=A3a 7=A3u)
class UaResults validate_pdf_ua(int level) const; // PDF/UA accessibility validation
class PdfXResults validate_pdf_x(int level) const; // PDF/X conformance validation
class Dss get_dss() const; // read the Document Security Store, if present
Document::Page
一个绑定到 Document 的轻量、0 基索引页面视图，由 Document::page(index) 返回。父 Document 的生命周期必须长于该页面。
std::string text() const; // reading-order text for this page
std::string markdown() const; // Markdown for this page
std::string html() const; // HTML for this page
std::string plain_text() const; // plain text for this page
int index() const noexcept; // 0-based page index
由源格式（Markdown、HTML、文本、图像）生成的 PDF。只可移动。
static Pdf from_markdown(const std::string& markdown); // build a PDF from Markdown
static Pdf from_html(const std::string& html); // build a PDF from HTML
static Pdf from_text(const std::string& text); // build a PDF from plain text
static Pdf from_image(const std::string& path); // single-page PDF wrapping an image file
static Pdf from_image_bytes(const std::vector<std::uint8_t>& data); // single-page PDF from image bytes
static Pdf from_html_css(const std::string& html, const std::string& css,
const std::vector<std::uint8_t>& font_bytes = {}); // HTML + CSS with one optional font
static Pdf from_html_css_with_fonts(const std::string& html, const std::string& css,
const std::vector<std::string>& families,
const std::vector<std::vector<std::uint8_t>>& fonts); // HTML + CSS with a font cascade
void save(const std::string& path) const; // write the PDF to a path
std::vector<std::uint8_t> to_bytes() const; // serialize the PDF to bytes
int page_count() const; // number of pages
void close(); // free the native handle now
DocumentEditor
原地编辑句柄：页面操作、元数据、密文涂黑（redaction）、表单、合并与保存。只可移动。
打开与信息
static DocumentEditor open(const std::string& path); // open an editor from a file path
static DocumentEditor open_from_bytes(const std::vector<std::uint8_t>& data); // open an editor from bytes
int page_count() const; // number of pages
Version version() const; // PDF version
std::string get_source_path() const; // source file path
bool is_modified() const; // true if there are unsaved edits
void close(); // free the native handle now
元数据
std::string get_producer() const; // Producer metadata
void set_producer(const std::string& value); // set Producer
std::string get_creation_date() const; // CreationDate metadata
void set_creation_date(const std::string& date_str); // set CreationDate
页面操作
void delete_page(int page_index); // delete a page
void move_page(int from, int to); // move a page
void rotate_page_by(int page_index, int degrees); // add to a page's rotation
void rotate_all_pages(int degrees); // rotate every page
void set_page_rotation(int page_index, int degrees); // set absolute page rotation
int get_page_rotation(int page_index) const; // get page rotation
void crop_margins(float left, float right, float top, float bottom); // crop all page margins
Bbox get_page_crop_box(int page_index) const; // get CropBox
void set_page_crop_box(int page_index, double x, double y, double w, double h); // set CropBox
Bbox get_page_media_box(int page_index) const; // get MediaBox
void set_page_media_box(int page_index, double x, double y, double w, double h); // set MediaBox
擦除 / 涂白
void erase_region(int page_index, float x, float y, float w, float h); // queue one erase region
void erase_regions(int page_index, const std::vector<EraseRect>& rects); // queue multiple erase regions
void clear_erase_regions(int page_index); // clear pending erase regions
密文涂黑
void apply_page_redactions(int page_index); // apply queued redactions on a page
void apply_all_redactions(); // apply all queued redactions
bool is_page_marked_for_redaction(int page_index) const; // redaction-mark query
void unmark_page_for_redaction(int page_index); // remove a page's redaction mark
void redaction_add(int page, double x1, double y1, double x2, double y2,
double r, double g, double b); // queue a geometric redaction region
int redaction_count(int page) const; // queued redaction regions on a page
int redaction_apply(bool scrub_metadata, double r, double g, double b); // destructively apply, returns glyphs removed
int redaction_scrub_metadata(); // sanitize metadata without geometric redaction
注释与表单
void flatten_annotations(int page_index); // flatten annotations on a page
void flatten_all_annotations(); // flatten all annotations
int flatten_warnings_count() const; // warnings from the last flatten save
std::string flatten_warning(int index) const; // one flatten warning message
bool is_page_marked_for_flatten(int page_index) const; // flatten-mark query
void unmark_page_for_flatten(int page_index); // remove a page's flatten mark
void flatten_forms(); // flatten all form fields
void flatten_forms_on_page(int page_index); // flatten forms on a page
void set_form_field_value(const std::string& name, const std::string& value); // set a form field value by name
int import_fdf_bytes(const std::vector<std::uint8_t>& data) const; // import FDF field values
int import_xfdf_bytes(const std::vector<std::uint8_t>& data) const; // import XFDF field values
文档操作
void merge_from(const std::string& source_path); // merge pages from a PDF on disk
void merge_from_bytes(const std::vector<std::uint8_t>& data); // merge pages from in-memory PDF
void convert_to_pdf_a(int level); // convert to PDF/A in place
void embed_file(const std::string& name, const std::vector<std::uint8_t>& data);// embed a file attachment
std::vector<std::uint8_t> extract_pages_to_bytes(const std::vector<int32_t>& pages) const; // extract pages to a new PDF
void add_barcode_to_page(int page_index, const Barcode& barcode,
float x, float y, float width, float height); // stamp a barcode onto a page
保存
void save(const std::string& path) const; // save to a path
std::vector<std::uint8_t> save_to_bytes() const; // save to bytes
std::vector<std::uint8_t> save_to_bytes_with_options(bool compress,
bool garbage_collect, bool linearize) const; // save with optimization options
void save_encrypted(const std::string& path, const std::string& user_password,
const std::string& owner_password) const; // save AES-256 encrypted to a path
std::vector<std::uint8_t> save_encrypted_to_bytes(const std::string& user_password,
const std::string& owner_password) const; // save AES-256 encrypted to bytes
EmbeddedFont
注册到 DocumentBuilder 的 TTF/OTF 字体。只可移动。
static EmbeddedFont from_file(const std::string& path); // load a font from a file
static EmbeddedFont from_bytes(const std::vector<std::uint8_t>& data,
const std::string& name = ""); // load a font from bytes
void close(); // free the native handle now
DocumentBuilder
用于从零创建带标签、多页 PDF 的流式构建器。只可移动。一次只打开一个 PageBuilder，并在开始下一页之前对其调用 done()。
static DocumentBuilder create(); // start a new builder
DocumentBuilder& set_title(const std::string& title); // set document title
DocumentBuilder& set_author(const std::string& author); // set document author
DocumentBuilder& set_subject(const std::string& subject); // set document subject
DocumentBuilder& set_keywords(const std::string& keywords); // set document keywords
DocumentBuilder& set_creator(const std::string& creator); // set document creator
DocumentBuilder& on_open(const std::string& script); // document-level open JavaScript
DocumentBuilder& tagged_pdf_ua1(); // enable PDF/UA-1 tagging
DocumentBuilder& language(const std::string& lang); // set document language
DocumentBuilder& role_map(const std::string& custom, const std::string& standard); // map a custom role to a standard one
DocumentBuilder& register_embedded_font(const std::string& name, EmbeddedFont& font); // register a font (consumes it)
PageBuilder a4_page(); // start an A4 page
PageBuilder letter_page(); // start a US Letter page
PageBuilder page(float width, float height); // start a custom-size page (points)
std::vector<std::uint8_t> build(); // build and return the PDF bytes
void save(const std::string& path); // build and save to a path
void save_encrypted(const std::string& path, const std::string& user_password,
const std::string& owner_password); // build and save AES-256 encrypted
std::vector<std::uint8_t> to_bytes_encrypted(const std::string& user_password,
const std::string& owner_password); // build encrypted bytes
void close(); // free the native handle now
PageBuilder
正在构建中的页面，从 DocumentBuilder 获得。每个布局操作都是流式的（返回 *this）；done() 提交该页并消费掉句柄。
文本与布局
PageBuilder& font(const std::string& name, float size); // set the active font + size
PageBuilder& at(float x, float y); // move the cursor to (x, y)
PageBuilder& text(const std::string& t); // draw text at the cursor
PageBuilder& heading(int level, const std::string& t); // draw a heading (level 1..6)
PageBuilder& paragraph(const std::string& t); // draw a wrapped paragraph
PageBuilder& space(float points); // add vertical space
PageBuilder& horizontal_rule(); // draw a horizontal rule
PageBuilder& footnote(const std::string& ref_mark, const std::string& note_text); // add a footnote
PageBuilder& inline_text(const std::string& t); // append inline text
PageBuilder& inline_bold(const std::string& t); // append inline bold text
PageBuilder& inline_italic(const std::string& t); // append inline italic text
PageBuilder& inline_color(float r, float g, float b, const std::string& t); // append inline coloured text
PageBuilder& newline(); // break the current line
链接与动作
PageBuilder& link_url(const std::string& url); // link the last run to a URL
PageBuilder& link_page(int page_index); // link to a page
PageBuilder& link_named(const std::string& destination); // link to a named destination
PageBuilder& link_javascript(const std::string& script); // link to a JavaScript action
PageBuilder& on_open(const std::string& script); // page open JavaScript
PageBuilder& on_close(const std::string& script); // page close JavaScript
PageBuilder& field_keystroke(const std::string& script); // field keystroke JavaScript
PageBuilder& field_validate(const std::string& script); // field validation JavaScript
PageBuilder& field_calculate(const std::string& script); // field calculation JavaScript
标记注释
PageBuilder& highlight(float r, float g, float b); // highlight the last run
PageBuilder& underline(float r, float g, float b); // underline the last run
PageBuilder& strikeout(float r, float g, float b); // strike out the last run
PageBuilder& squiggly(float r, float g, float b); // squiggly-underline the last run
PageBuilder& sticky_note(const std::string& t); // sticky note at the cursor
PageBuilder& sticky_note_at(float x, float y, const std::string& t); // sticky note at (x, y)
PageBuilder& watermark(const std::string& t); // add a text watermark
PageBuilder& watermark_confidential(); // add a CONFIDENTIAL watermark
PageBuilder& watermark_draft(); // add a DRAFT watermark
PageBuilder& stamp(const std::string& type_name); // add a rubber-stamp annotation
PageBuilder& freetext(float x, float y, float w, float h, const std::string& t); // add a free-text annotation
表单字段
PageBuilder& text_field(const std::string& name, float x, float y, float w, float h,
const std::string& default_value = ""); // text field widget
PageBuilder& checkbox(const std::string& name, float x, float y, float w, float h, bool checked); // checkbox widget
PageBuilder& combo_box(const std::string& name, float x, float y, float w, float h,
const std::vector<std::string>& options,
const std::string& selected = ""); // combo box widget
PageBuilder& radio_group(const std::string& name, const std::vector<std::string>& values,
const std::vector<float>& xs, const std::vector<float>& ys,
const std::vector<float>& ws, const std::vector<float>& hs,
const std::string& selected = ""); // radio group widget
PageBuilder& push_button(const std::string& name, float x, float y, float w, float h,
const std::string& caption); // push button widget
PageBuilder& signature_field(const std::string& name, float x, float y, float w, float h); // signature field widget
条形码与图像
PageBuilder& barcode_1d(int barcode_type, const std::string& data,
float x, float y, float w, float h); // draw a 1-D barcode
PageBuilder& barcode_qr(const std::string& data, float x, float y, float size); // draw a QR code
PageBuilder& image(const std::vector<std::uint8_t>& bytes, float x, float y, float w, float h); // draw an image
PageBuilder& image_with_alt(const std::vector<std::uint8_t>& bytes, float x, float y,
float w, float h, const std::string& alt_text); // image with alt text (tagged)
PageBuilder& image_artifact(const std::vector<std::uint8_t>& bytes,
float x, float y, float w, float h); // decorative image (artifact)
矢量图形
PageBuilder& rect(float x, float y, float w, float h); // stroke a rectangle
PageBuilder& filled_rect(float x, float y, float w, float h, float r, float g, float b); // filled rectangle
PageBuilder& line(float x1, float y1, float x2, float y2); // draw a line
PageBuilder& stroke_rect(float x, float y, float w, float h, float width,
float r, float g, float b); // stroked rectangle (width + colour)
PageBuilder& stroke_line(float x1, float y1, float x2, float y2, float width,
float r, float g, float b); // stroked line (width + colour)
PageBuilder& stroke_rect_dashed(float x, float y, float w, float h, float width,
float r, float g, float b,
const std::vector<float>& dash_array, float phase); // dashed rectangle
PageBuilder& stroke_line_dashed(float x1, float y1, float x2, float y2, float width,
float r, float g, float b,
const std::vector<float>& dash_array, float phase); // dashed line
PageBuilder& text_in_rect(float x, float y, float w, float h, const std::string& t, int align); // aligned text in a box
PageBuilder& new_page_same_size(); // start a new page of the same size
表格
PageBuilder& table(std::size_t n_columns, const std::vector<float>& widths,
const std::vector<int32_t>& aligns, std::size_t n_rows,
const std::vector<std::string>& cells, bool has_header); // buffer a complete table
PageBuilder& streaming_table_begin(std::size_t n_columns, const std::vector<std::string>& headers,
const std::vector<float>& widths,
const std::vector<int32_t>& aligns, bool repeat_header); // begin a streaming table
PageBuilder& streaming_table_begin_v2(std::size_t n_columns, const std::vector<std::string>& headers,
const std::vector<float>& widths, const std::vector<int32_t>& aligns,
bool repeat_header, int mode, std::size_t sample_rows,
float min_col_width_pt, float max_col_width_pt,
std::size_t max_rowspan); // begin a streaming table (auto-fit options)
PageBuilder& streaming_table_set_batch_size(std::size_t batch_size); // set the flush batch size
std::size_t streaming_table_pending_row_count(); // rows buffered but not flushed
std::size_t streaming_table_batch_count(); // number of flushed batches
PageBuilder& streaming_table_flush(); // flush buffered rows
PageBuilder& streaming_table_push_row(const std::vector<std::string>& cells); // push a row
PageBuilder& streaming_table_push_row_v2(const std::vector<std::string>& cells,
const std::vector<std::uintptr_t>& rowspans); // push a row with rowspans
PageBuilder& streaming_table_finish(); // finish the streaming table
提交
void done(); // commit this page to the parent builder (consumes the handle)
void close(); // drop an uncommitted page handle now
Certificate
PKI 签名凭据。只可移动。
static Certificate load_from_bytes(const std::vector<std::uint8_t>& data,
const std::string& password = ""); // load PKCS#12 (PFX) bytes
static Certificate load_from_pem(const std::string& cert_pem, const std::string& key_pem); // load PEM cert + key
std::string subject() const; // subject distinguished name
std::string issuer() const; // issuer distinguished name
std::string serial() const; // serial number
std::pair<std::int64_t, std::int64_t> validity() const; // (not-before, not-after) epoch seconds
bool is_valid() const; // currently within validity window
void close(); // free the native handle now
Timestamp
一个 RFC 3161 时间戳令牌。只可移动。
static Timestamp parse(const std::vector<std::uint8_t>& bytes); // parse a timestamp token (TST)
std::vector<std::uint8_t> token() const; // raw token bytes
std::vector<std::uint8_t> message_imprint() const; // message imprint bytes
std::int64_t time() const; // timestamp time (epoch seconds)
std::string serial() const; // serial number
std::string tsa_name() const; // TSA name
std::string policy_oid() const; // policy OID
int hash_algorithm() const; // hash algorithm code
void close(); // free the native handle now
SignatureInfo
从 Document 读取的单个签名。只可移动。
std::string signer_name() const; // signer common name
std::string signing_reason() const; // signing reason
std::string signing_location() const; // signing location
std::int64_t signing_time() const; // signing time (epoch seconds)
Certificate certificate() const; // the signer's certificate
int pades_level() const; // PAdES baseline level
bool has_timestamp() const; // signature timestamp presence
Timestamp timestamp() const; // the signature's timestamp
bool add_timestamp(const Timestamp& ts); // attach a timestamp
int verify() const; // crypto check (1=valid, 0=invalid, -1=unknown)
int verify_detached(const std::vector<std::uint8_t>& pdf_data) const; // detached verification against full PDF bytes
void close(); // free the native handle now
TsaClient
一个 RFC 3161 时间戳颁发机构（TSA）客户端。只可移动。
static TsaClient create(const std::string& url, const std::string& username = "",
const std::string& password = "", int timeout = 30,
int hash_algo = 0, bool use_nonce = true, bool cert_req = true); // create a TSA client
Timestamp request_timestamp(const std::vector<std::uint8_t>& data) const; // request a timestamp over data
Timestamp request_timestamp_hash(const std::vector<std::uint8_t>& hash, int hash_algo) const; // timestamp a precomputed hash
void close(); // free the native handle now
Dss
文档安全存储（Document Security Store），由 Document::get_dss() 返回。只可移动。
int cert_count() const; // number of certificates
int crl_count() const; // number of CRLs
int ocsp_count() const; // number of OCSP responses
int vri_count() const; // number of VRI entries
std::vector<std::uint8_t> get_cert(int index) const; // certificate bytes
std::vector<std::uint8_t> get_crl(int index) const; // CRL bytes
std::vector<std::uint8_t> get_ocsp(int index) const; // OCSP response bytes
void close(); // free the native handle now
PdfAResults
PDF/A 校验结果，由 Document::validate_pdf_a() 返回。只可移动。
bool is_compliant() const; // true if compliant
std::vector<std::string> errors() const; // conformance errors
int warning_count() const; // number of warnings
void close(); // free the native handle now
UaResults
PDF/UA 无障碍校验结果，由 Document::validate_pdf_ua() 返回。只可移动。
bool is_accessible() const; // true if accessible
std::vector<std::string> errors() const; // accessibility errors
std::vector<std::string> warnings() const; // accessibility warnings
UaStats stats() const; // accessibility statistics
void close(); // free the native handle now
PdfXResults
PDF/X 校验结果，由 Document::validate_pdf_x() 返回。只可移动。
bool is_compliant() const; // true if compliant
std::vector<std::string> errors() const; // conformance errors
void close(); // free the native handle now
Barcode
一个生成的一维条形码或二维 QR 码。只可移动。
static Barcode generate_qr_code(const std::string& data, int error_correction = 1, int size_px = 256); // generate a QR code
static Barcode generate_barcode(const std::string& data, int format, int size_px = 256); // generate a barcode
std::string get_data() const; // encoded data string
int get_format() const; // barcode format/symbology code
float get_confidence() const; // decode confidence (0..1)
std::vector<std::uint8_t> get_image_png(int size_px = 256) const; // render to PNG bytes
std::string get_svg(int size_px = 256) const; // render to an SVG string
void close(); // free the native handle now
OcrEngine
从检测/识别模型加上一个字典加载而成的 OCR 引擎。只可移动。传给 Document::ocr_extract_text()。
static OcrEngine create(const std::string& det_model_path,
const std::string& rec_model_path,
const std::string& dict_path); // create an OCR engine from model files
void close(); // free the native handle now
Renderer
一个独立、可复用的渲染器配置。只可移动。
static Renderer create(int dpi, int format, int quality, bool anti_alias); // create a renderer (format 0=PNG, 1=JPEG)
void close(); // free the native handle now
自由函数
命名空间 pdf_oxide 中的顶层函数。
日志
void set_log_level(int level); // set global log level (0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace)
int get_log_level(); // get the current global log level
签名与时间戳
std::vector<std::uint8_t> sign_bytes(const std::vector<std::uint8_t>& pdf_data,
const Certificate& cert, const std::string& reason = "",
const std::string& location = ""); // sign raw PDF bytes
std::vector<std::uint8_t> sign_bytes_pades(const std::vector<std::uint8_t>& pdf_data,
const Certificate& cert, int level, const std::string& tsa_url = "",
const std::string& reason = "", const std::string& location = "",
const RevocationMaterial& revocation = {}); // PAdES baseline signing (0=B-B 1=B-T 2=B-LT)
std::vector<std::uint8_t> sign_bytes_pades_opts(const std::vector<std::uint8_t>& pdf_data,
const Certificate& cert, int level, const std::string& tsa_url = "",
const std::string& reason = "", const std::string& location = "",
const RevocationMaterial& revocation = {}); // struct-options PAdES signing
std::vector<std::uint8_t> add_timestamp(const std::vector<std::uint8_t>& pdf_data,
int sig_index, const std::string& tsa_url); // add an RFC 3161 document timestamp
合并
std::vector<std::uint8_t> merge(const std::vector<std::string>& paths); // merge multiple PDFs (in order) into one
密码学 / FIPS
std::string crypto_active_provider(); // active crypto provider name
std::string crypto_cbom(); // crypto bill-of-materials (CBOM) as JSON
int crypto_fips_available(); // 1 if a FIPS provider is available
std::string crypto_inventory(); // crypto algorithm inventory as JSON
std::string crypto_policy(); // active crypto policy
int crypto_set_policy(const std::string& spec); // set the crypto policy
int crypto_use_fips(); // switch to the FIPS provider
模型与全局配置
std::string model_manifest(); // model manifest as JSON
int prefetch_available(); // 1 if model prefetch is available
std::string prefetch_models(const std::string& languages_csv); // prefetch OCR/layout models for languages
std::int64_t set_max_ops_per_stream(std::int64_t limit); // set the max content-stream ops limit (returns previous)
int set_preserve_unmapped_glyphs(int preserve); // toggle preservation of unmapped glyphs
完整示例
#include <pdf_oxide/pdf_oxide.hpp>
#include <iostream>
using namespace pdf_oxide;
int main() {
// --- Extraction ---
auto doc = Document::open("input.pdf");
std::cout << "Pages: " << doc.page_count() << "\n";
for (int i = 0; i < doc.page_count(); ++i) {
std::cout << "Page " << (i + 1) << ": "
<< doc.extract_text(i).size() << " chars\n";
}
// Render the first page to PNG
doc.render_page(0).save("page0.png");
// --- Creation ---
auto db = DocumentBuilder::create();
db.set_title("Report");
db.letter_page()
.font("Helvetica", 18.0f)
.heading(1, "Quarterly Report")
.paragraph("Generated by PDF Oxide.")
.done();
db.save("report.pdf");
// --- Editing ---
auto editor = DocumentEditor::open("input.pdf");
editor.rotate_all_pages(90);
editor.set_producer("PDF Oxide");
editor.set_form_field_value("name", "John Doe");
editor.save("output.pdf");
// --- Signing ---
auto cert = Certificate::load_from_pem(cert_pem, key_pem);
auto signed_pdf = sign_bytes(editor.save_to_bytes(), cert, "Approval", "HQ");
return 0;
}
Other Language Bindings
PDF Oxide 为所有主流生态系统提供原生绑定：Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir。
后续步骤
- 类型与枚举 — 所有共享类型与枚举
- Page API 参考 — 各绑定间一致的逐页迭代方式
- C++ 快速上手 — 教程