C++ API Reference
PDF Oxide ships idiomatic, header-only C++17 RAII bindings over its C ABI. Every class is a thin inline wrapper around the core library: handles are owned and move-only, C strings and byte buffers are copied into std::string / std::vector<std::uint8_t> and freed automatically, and every non-success C status raises a pdf_oxide::Error exception.
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
All types live in namespace pdf_oxide. Objects are constructed through static factory functions (Document::open, DocumentBuilder::create, Certificate::load_from_pem, …) rather than public constructors; each owns a native handle freed on destruction or via an explicit close().
For other languages, see the Python API Reference, Node.js API Reference or WASM API Reference, and Rust API Reference. For type details, see Types & Enums.
Error handling
All failures raise pdf_oxide::Error, derived from 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";
}
Data types
Plain value structs returned by extraction and inspection methods.
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
A rendered page image returned by all render_* methods. Move-only; owns the native bitmap and frees it on destruction.
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
The primary class for opening, inspecting, extracting from, rendering, and validating PDFs. Move-only; read-oriented (use DocumentEditor for in-place mutation).
Opening
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
Document info
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
Text & document conversion
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
Element extraction
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
Region (in-rect) extraction
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
Auto extraction & classification
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)
Search
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
Rendering
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)
Page geometry & elements
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)
Header / footer / artifact removal
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
Form fields
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)
Structure & metadata
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
Signatures
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
Annotation inspection
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 inspection helpers
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 conversion & 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)
Validation
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
A lightweight 0-based page view bound to a Document, returned by Document::page(index). The parent Document must outlive the page.
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
A PDF produced from a source format (Markdown, HTML, text, image). Move-only.
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
In-place editing handle: page operations, metadata, redaction, forms, merging, and saving. Move-only.
Opening & info
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
Metadata
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
Page operations
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
Erase / whiteout
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
Redaction
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
Annotations & forms
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
Document operations
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
Saving
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
A TTF/OTF font registered with a DocumentBuilder. Move-only.
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
Fluent builder for creating tagged, multi-page PDFs from scratch. Move-only. Open one PageBuilder at a time and done() it before starting the next page.
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
A page under construction, obtained from DocumentBuilder. Every layout op is fluent (returns *this); done() commits the page and consumes the handle.
Text & layout
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
Links & actions
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
Markup annotations
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
Form fields
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
Barcodes & images
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)
Vector graphics
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
Tables
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
Commit
void done(); // commit this page to the parent builder (consumes the handle)
void close(); // drop an uncommitted page handle now
Certificate
PKI signing credentials. Move-only.
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
An RFC 3161 timestamp token. Move-only.
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
One signature read from a Document. Move-only.
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
An RFC 3161 timestamp-authority client. Move-only.
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
The Document Security Store, returned by Document::get_dss(). Move-only.
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 validation result, returned by Document::validate_pdf_a(). Move-only.
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 accessibility validation result, returned by Document::validate_pdf_ua(). Move-only.
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 validation result, returned by Document::validate_pdf_x(). Move-only.
bool is_compliant() const; // true if compliant
std::vector<std::string> errors() const; // conformance errors
void close(); // free the native handle now
Barcode
A generated 1-D barcode or 2-D QR code. Move-only.
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
An OCR engine loaded from detection/recognition models plus a dictionary. Move-only. Pass to 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
A standalone, reusable renderer configuration. Move-only.
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
Free functions
Top-level functions in namespace pdf_oxide.
Logging
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
Signing & timestamping
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
Merge
std::vector<std::uint8_t> merge(const std::vector<std::string>& paths); // merge multiple PDFs (in order) into one
Crypto / 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
Models & global config
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
Complete example
#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 ships native bindings for every major ecosystem: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, and Elixir.
Next Steps
- Types & Enums — all shared types and enums
- Page API Reference — consistent per-page iteration across bindings
- Getting Started with C++ — tutorial