Objective-C API Reference

PDF Oxide ships idiomatic Objective-C bindings (the PdfOxide framework / PdfOxide CocoaPod) layered over the C ABI. NSObject wrappers own their native handles and free them in -dealloc (or eagerly via -close); returned C strings and buffers are copied into NSString/NSData, and non-success status codes surface as NSError in the POXErrorDomain. Every public method is covered one-for-one by POXApiCoverageTests.

# Podfile
pod 'PdfOxide', '~> 0.3.69'

#import <PdfOxide/POXPdfOxide.h>

For the Rust API, see the Rust API Reference. For the Python API, see the Python API Reference. For the JavaScript API, see the Node.js API Reference or WASM API Reference.

All page indices are 0-based. Bounding boxes use POXBbox { float x; float y; float width; float height; } in PDF user-space points; PDF version is reported as POXVersion { uint8_t major; uint8_t minor; }.

---

POXDocument

The primary class for opening, extracting from, rendering, and inspecting a PDF.

Opening

+ (nullable instancetype)openPath:(NSString*)path error:(NSError**)error;

Open a PDF from a filesystem path.

+ (nullable instancetype)openFromBytes:(NSData*)data error:(NSError**)error;

Open a PDF from in-memory bytes.

+ (nullable instancetype)openWithPassword:(NSString*)path password:(NSString*)password error:(NSError**)error;

Open a password-protected PDF in one step.

+ (nullable instancetype)openFromDocxBytes:(NSData*)data error:(NSError**)error;
+ (nullable instancetype)openFromPptxBytes:(NSData*)data error:(NSError**)error;
+ (nullable instancetype)openFromXlsxBytes:(NSData*)data error:(NSError**)error;

Convert in-memory Office document bytes (Word/PowerPoint/Excel) to an opened PDF document.

- (BOOL)authenticate:(NSString*)password error:(NSError**)error;

Authenticate an encrypted document after opening; returns YES on success, NO for a wrong password.

Office Export

- (nullable NSData*)toDocxWithError:(NSError**)error;
- (nullable NSData*)toPptxWithError:(NSError**)error;
- (nullable NSData*)toXlsxWithError:(NSError**)error;

Export the document to Word / PowerPoint / Excel bytes.

Document Info

- (NSInteger)pageCountError:(NSError**)error;

Number of pages, or -1 on error.

- (POXVersion)version;

PDF version as a POXVersion struct.

- (BOOL)isEncrypted;
- (BOOL)hasStructureTree;
- (BOOL)hasXfa;

Encryption, Tagged-PDF structure tree, and XFA-form presence queries.

Text & Conversion

- (nullable NSString*)extractText:(NSInteger)page error:(NSError**)error;

Extract plain text from a single page.

- (nullable NSString*)toPlainText:(NSInteger)page error:(NSError**)error;
- (nullable NSString*)toMarkdown:(NSInteger)page error:(NSError**)error;
- (nullable NSString*)toHtml:(NSInteger)page error:(NSError**)error;

Convert a single page to plain text, Markdown, or HTML.

- (nullable NSString*)toPlainTextAllWithError:(NSError**)error;
- (nullable NSString*)toMarkdownAllWithError:(NSError**)error;
- (nullable NSString*)toHtmlAllWithError:(NSError**)error;

Convert all pages to plain text, Markdown, or HTML.

- (nullable NSString*)extractStructuredJson:(NSInteger)page error:(NSError**)error;

Extract a page as structured JSON (spans, geometry, fonts).

Element Extraction

- (nullable NSArray<POXChar*>*)extractChars:(NSInteger)page error:(NSError**)error;
- (nullable NSArray<POXWord*>*)extractWords:(NSInteger)page error:(NSError**)error;
- (nullable NSArray<POXTextLine*>*)extractTextLines:(NSInteger)page error:(NSError**)error;
- (nullable NSArray<POXTable*>*)extractTables:(NSInteger)page error:(NSError**)error;

Extract characters, words, text lines, and tables with positioning metadata.

- (nullable NSArray<POXFont*>*)embeddedFonts:(NSInteger)page error:(NSError**)error;
- (nullable NSArray<POXImage*>*)embeddedImages:(NSInteger)page error:(NSError**)error;
- (nullable NSArray<POXAnnotation*>*)pageAnnotations:(NSInteger)page error:(NSError**)error;
- (nullable NSArray<POXPath*>*)extractPaths:(NSInteger)page error:(NSError**)error;

Extract embedded fonts, embedded images, page annotations, and vector paths.

Search

- (nullable NSArray<POXSearchResult*>*)search:(NSInteger)page term:(NSString*)term caseSensitive:(BOOL)caseSensitive error:(NSError**)error;

Search for term on a single page.

- (nullable NSArray<POXSearchResult*>*)searchAll:(NSString*)term caseSensitive:(BOOL)caseSensitive error:(NSError**)error;

Search for term across the entire document.

In-Rect Extraction

- (nullable NSString*)extractTextInRect:(NSInteger)page x:(float)x y:(float)y width:(float)width height:(float)height error:(NSError**)error;
- (nullable NSArray<POXWord*>*)extractWordsInRect:(NSInteger)page x:(float)x y:(float)y width:(float)width height:(float)height error:(NSError**)error;
- (nullable NSArray<POXTextLine*>*)extractLinesInRect:(NSInteger)page x:(float)x y:(float)y width:(float)width height:(float)height error:(NSError**)error;
- (nullable NSArray<POXTable*>*)extractTablesInRect:(NSInteger)page x:(float)x y:(float)y width:(float)width height:(float)height error:(NSError**)error;
- (nullable NSArray<POXImage*>*)extractImagesInRect:(NSInteger)page x:(float)x y:(float)y width:(float)width height:(float)height error:(NSError**)error;

Extract text, words, lines, tables, or images restricted to a rectangular region (user-space points).

Auto Extraction & Classification

- (nullable NSString*)extractTextAuto:(NSInteger)page error:(NSError**)error;

Auto-select native vs. OCR text extraction for a page.

- (nullable NSString*)extractAllTextWithError:(NSError**)error;

Extract text from the whole document.

- (nullable NSString*)extractPageAuto:(NSInteger)page optionsJson:(nullable NSString*)optionsJson error:(NSError**)error;

Auto-extract a page with a JSON options blob.

- (nullable NSString*)classifyPage:(NSInteger)page error:(NSError**)error;
- (nullable NSString*)classifyDocumentWithError:(NSError**)error;

Classify a single page or the whole document (returns a classification JSON).

Header / Footer / Artifact Removal

- (int32_t)eraseHeader:(NSInteger)page error:(NSError**)error;
- (int32_t)eraseFooter:(NSInteger)page error:(NSError**)error;
- (int32_t)eraseArtifacts:(NSInteger)page error:(NSError**)error;

Erase the header, footer, or artifacts on a single page; returns the count removed.

- (int32_t)removeHeaders:(float)threshold error:(NSError**)error;
- (int32_t)removeFooters:(float)threshold error:(NSError**)error;
- (int32_t)removeArtifacts:(float)threshold error:(NSError**)error;

Remove repeating headers, footers, or artifacts document-wide above a similarity threshold.

Forms

- (nullable NSArray<POXFormField*>*)formFieldsWithError:(NSError**)error;

Get all AcroForm fields.

- (nullable NSData*)exportFormDataToBytes:(int32_t)formatType error:(NSError**)error;

Export form data as FDF/XFDF bytes (formatType selects the format).

- (BOOL)importFormDataFromPath:(NSString*)dataPath error:(NSError**)error;
- (BOOL)importFormFromFile:(NSString*)filename error:(NSError**)error;

Import form data from an FDF/XFDF file.

Structure & Metadata

- (nullable NSString*)outlineWithError:(NSError**)error;
- (nullable NSString*)pageLabelsWithError:(NSError**)error;
- (nullable NSString*)xmpMetadataWithError:(NSError**)error;

Get the document outline (bookmarks), page-label ranges, and XMP metadata as JSON.

- (nullable NSData*)sourceBytesWithError:(NSError**)error;

Get the raw source PDF bytes.

- (nullable NSString*)planSplitByBookmarks:(nullable NSString*)optionsJson error:(NSError**)error;

Compute a split plan grouping pages by top-level bookmarks (returns JSON).

Annotations / Fonts / Search as JSON

- (nullable NSString*)annotationsJson:(NSInteger)page error:(NSError**)error;
- (nullable NSString*)embeddedFontsJson:(NSInteger)page error:(NSError**)error;
- (nullable NSString*)searchJson:(NSInteger)page term:(NSString*)term caseSensitive:(BOOL)caseSensitive error:(NSError**)error;

JSON-serialized variants of page annotations, embedded fonts, and per-page search.

Page Geometry & Elements

- (float)pageWidth:(NSInteger)pageIndex error:(NSError**)error;
- (float)pageHeight:(NSInteger)pageIndex error:(NSError**)error;
- (int32_t)pageRotation:(NSInteger)pageIndex error:(NSError**)error;

Page width, height, and rotation in degrees (-1 on error).

- (nullable POXElementList*)pageElements:(NSInteger)pageIndex error:(NSError**)error;

Get the layout-element list for a page. See POXElementList.

- (POXPage*)pageAtIndex:(NSInteger)index;

Get a page handle bound to this document. See POXPage.

Rendering

- (nullable POXRenderedImage*)renderPage:(NSInteger)pageIndex format:(int32_t)format error:(NSError**)error;

Render a page to an image (format 0 = PNG, 1 = JPEG).

- (nullable POXRenderedImage*)renderPageZoom:(NSInteger)pageIndex zoom:(float)zoom format:(int32_t)format error:(NSError**)error;
- (nullable POXRenderedImage*)renderPageThumbnail:(NSInteger)pageIndex size:(int32_t)size format:(int32_t)format error:(NSError**)error;

Render a page at a zoom factor, or as a thumbnail of a target longest-edge size.

- (nullable POXRenderedImage*)renderPageWithOptions:(NSInteger)pageIndex
                                                dpi:(int32_t)dpi
                                             format:(int32_t)format
                                                bgR:(float)bgR bgG:(float)bgG bgB:(float)bgB bgA:(float)bgA
                              transparentBackground:(int32_t)transparentBackground
                                  renderAnnotations:(int32_t)renderAnnotations
                                        jpegQuality:(int32_t)jpegQuality
                                              error:(NSError**)error;

Render with the full options surface (DPI, RGBA background, transparency, annotation flag, JPEG quality).

- (nullable POXRenderedImage*)renderPageWithOptionsEx:(NSInteger)pageIndex
                                                  dpi:(int32_t)dpi
                                               format:(int32_t)format
                                                  bgR:(float)bgR bgG:(float)bgG bgB:(float)bgB bgA:(float)bgA
                                transparentBackground:(int32_t)transparentBackground
                                    renderAnnotations:(int32_t)renderAnnotations
                                          jpegQuality:(int32_t)jpegQuality
                                       excludedLayers:(NSArray<NSString*>*)excludedLayers
                                                error:(NSError**)error;

Like renderPageWithOptions: but additionally suppresses the named OCG layers.

- (nullable POXRenderedImage*)renderPageRegion:(NSInteger)pageIndex cropX:(float)cropX cropY:(float)cropY cropWidth:(float)cropWidth cropHeight:(float)cropHeight format:(int32_t)format error:(NSError**)error;

Render a rectangular region of a page (user-space points, origin bottom-left).

- (nullable POXRenderedImage*)renderPageFit:(NSInteger)pageIndex w:(int32_t)w h:(int32_t)h format:(int32_t)format error:(NSError**)error;

Render a page to fit inside w × h pixels, preserving aspect ratio.

- (nullable POXRenderedImage*)renderPageRaw:(NSInteger)pageIndex dpi:(int32_t)dpi outWidth:(int32_t*)outWidth outHeight:(int32_t*)outHeight error:(NSError**)error;

Render a page to a raw RGBA8888 buffer; the out-params receive pixel dimensions.

- (int32_t)estimateRenderTime:(NSInteger)pageIndex error:(NSError**)error;

Estimate the render time (engine units) for a page, or -1 on error.

OCR

- (BOOL)pageNeedsOcr:(NSInteger)pageIndex error:(NSError**)error;

Whether a page lacks extractable text and would benefit from OCR.

- (nullable NSString*)ocrExtractText:(NSInteger)pageIndex engine:(nullable POXOcrEngine*)engine error:(NSError**)error;

Extract text using OCR; pass nil for native-only text. See POXOcrEngine.

Conformance Validation

- (nullable POXPdfAResults*)validatePdfA:(int32_t)level error:(NSError**)error;
- (nullable POXUaResults*)validatePdfUa:(int32_t)level error:(NSError**)error;
- (nullable POXPdfXResults*)validatePdfX:(int32_t)level error:(NSError**)error;

Validate PDF/A, PDF/UA, or PDF/X conformance; level selects the sub-level. Returns a result handle.

- (BOOL)convertToPdfA:(int32_t)level error:(NSError**)error;

Convert the document to PDF/A at the given conformance level.

Signatures (Document-Level)

- (BOOL)sign:(POXCertificate*)certificate reason:(nullable NSString*)reason location:(nullable NSString*)location error:(NSError**)error;

Apply a basic digital signature with a loaded certificate.

- (int32_t)signatureCountWithError:(NSError**)error;
- (nullable POXSignatureInfo*)signatureAtIndex:(int32_t)index error:(NSError**)error;
- (int32_t)verifyAllSignaturesWithError:(NSError**)error;
- (int32_t)hasTimestampWithError:(NSError**)error;
- (nullable POXDss*)dssWithError:(NSError**)error;

Count signatures, fetch signature info, verify all signatures, check for a document timestamp, and read the Document Security Store.

Lifecycle

- (void)close;

Free the native handle now (idempotent).

---

POXPage

A page handle bound to a POXDocument (0-based). Holds a strong reference to its document so it cannot outlive it.

- (nullable NSString*)text:(NSError**)error;
- (nullable NSString*)markdown:(NSError**)error;
- (nullable NSString*)html:(NSError**)error;
- (nullable NSString*)plainText:(NSError**)error;

Extract this page’s text, Markdown, HTML, or layout-preserving plain text.

---

POXPdf

A PDF produced by a builder or wrapping factory.

Constructors

+ (nullable instancetype)fromMarkdown:(NSString*)markdown error:(NSError**)error;
+ (nullable instancetype)fromHtml:(NSString*)html error:(NSError**)error;
+ (nullable instancetype)fromText:(NSString*)text error:(NSError**)error;

Build a PDF from Markdown, HTML, or plain text.

+ (nullable instancetype)fromImage:(NSString*)path error:(NSError**)error;
+ (nullable instancetype)fromImageBytes:(NSData*)data error:(NSError**)error;

Build a single-page PDF wrapping an image file or in-memory image bytes.

+ (nullable instancetype)fromHtml:(NSString*)html css:(NSString*)css fontBytes:(nullable NSData*)fontBytes error:(NSError**)error;

Build a PDF from HTML + CSS with a single optional embedded font.

+ (nullable instancetype)fromHtml:(NSString*)html css:(NSString*)css families:(NSArray<NSString*>*)families fonts:(NSArray<NSData*>*)fonts error:(NSError**)error;

Build a PDF from HTML + CSS with a multi-font cascade (parallel families/fonts arrays).

Methods

- (BOOL)saveToPath:(NSString*)path error:(NSError**)error;
- (nullable NSData*)toBytesWithError:(NSError**)error;
- (NSInteger)pageCountError:(NSError**)error;
- (void)close;

Save to a path, get the PDF bytes, get the page count (-1 on error), or free the native handle.

---

POXDocumentEditor

A PDF opened for in-place editing. Status-code operations surface failures as NSError; is* queries return BOOL.

Opening

+ (nullable instancetype)openEditor:(NSString*)path error:(NSError**)error;
+ (nullable instancetype)openFromBytes:(NSData*)data error:(NSError**)error;

Open a PDF for editing from a path or in-memory bytes.

State & Metadata

- (NSInteger)pageCountError:(NSError**)error;
- (POXVersion)version;
- (BOOL)isModified;
- (nullable NSString*)sourcePathError:(NSError**)error;

Page count, PDF version, pending-modification flag, and the editor’s source path.

- (nullable NSString*)producerError:(NSError**)error;
- (BOOL)setProducer:(NSString*)value error:(NSError**)error;
- (nullable NSString*)creationDateError:(NSError**)error;
- (BOOL)setCreationDate:(NSString*)date error:(NSError**)error;

Get/set the document /Info.Producer and /Info.CreationDate.

Page Operations

- (BOOL)deletePage:(NSInteger)page error:(NSError**)error;
- (BOOL)movePageFrom:(NSInteger)from to:(NSInteger)to error:(NSError**)error;

Delete or reorder pages.

- (BOOL)rotatePage:(NSInteger)page byDegrees:(NSInteger)degrees error:(NSError**)error;
- (BOOL)rotateAllPages:(NSInteger)degrees error:(NSError**)error;
- (BOOL)setPageRotation:(NSInteger)page degrees:(NSInteger)degrees error:(NSError**)error;
- (NSInteger)pageRotation:(NSInteger)page error:(NSError**)error;

Rotate one page, all pages, set absolute rotation, or read current rotation.

- (BOOL)cropMarginsLeft:(float)left right:(float)right top:(float)top bottom:(float)bottom error:(NSError**)error;

Crop all pages by margins.

- (POXBbox)pageCropBox:(NSInteger)page error:(NSError**)error;
- (BOOL)setPageCropBox:(NSInteger)page box:(POXBbox)box error:(NSError**)error;
- (POXBbox)pageMediaBox:(NSInteger)page error:(NSError**)error;
- (BOOL)setPageMediaBox:(NSInteger)page box:(POXBbox)box error:(NSError**)error;

Get/set the CropBox and MediaBox of a page.

Redaction

- (BOOL)applyAllRedactions:(NSError**)error;
- (BOOL)applyPageRedactions:(NSInteger)page error:(NSError**)error;
- (BOOL)isPageMarkedForRedaction:(NSInteger)page;
- (BOOL)unmarkPageForRedaction:(NSInteger)page error:(NSError**)error;

Apply queued redactions (all or per-page), query, and unmark redaction state.

- (BOOL)redactionAddPage:(NSInteger)page x1:(double)x1 y1:(double)y1 x2:(double)x2 y2:(double)y2 r:(double)r g:(double)g b:(double)b error:(NSError**)error;
- (int32_t)redactionCount:(NSInteger)page error:(NSError**)error;
- (int32_t)redactionApplyScrubMetadata:(BOOL)scrubMetadata r:(double)r g:(double)g b:(double)b error:(NSError**)error;
- (int32_t)redactionScrubMetadataWithError:(NSError**)error;

Geometric redaction: queue a fill rectangle, count queued rects, destructively apply (returning glyphs removed), and standalone metadata/JS/embedded-file scrub.

Erase Regions

- (BOOL)eraseRegion:(NSInteger)page x:(float)x y:(float)y w:(float)w h:(float)h error:(NSError**)error;
- (BOOL)eraseRegions:(NSInteger)page rects:(NSArray<NSValue*>*)rects error:(NSError**)error;
- (BOOL)clearEraseRegions:(NSInteger)page error:(NSError**)error;

Erase a single rectangle, multiple POXBbox-valued rectangles, or clear pending erases.

Flattening

- (BOOL)flattenForms:(NSError**)error;
- (BOOL)flattenFormsOnPage:(NSInteger)page error:(NSError**)error;
- (BOOL)flattenAnnotations:(NSInteger)page error:(NSError**)error;
- (BOOL)flattenAllAnnotations:(NSError**)error;

Flatten all forms, forms on a page, annotations on a page, or all annotations.

- (NSInteger)flattenWarningsCount;
- (nullable NSString*)flattenWarning:(NSInteger)index error:(NSError**)error;
- (BOOL)isPageMarkedForFlatten:(NSInteger)page;
- (BOOL)unmarkPageForFlatten:(NSInteger)page error:(NSError**)error;

Inspect flatten warnings and the per-page flatten mark.

Forms

- (BOOL)setFormField:(NSString*)name value:(NSString*)value error:(NSError**)error;
- (BOOL)importFdfBytes:(NSData*)data error:(NSError**)error;
- (BOOL)importXfdfBytes:(NSData*)data error:(NSError**)error;

Set a form-field value by name; import raw FDF / XFDF bytes.

Merge / Convert / Embed

- (BOOL)mergeFrom:(NSString*)sourcePath error:(NSError**)error;
- (BOOL)mergeFromBytes:(NSData*)data error:(NSError**)error;
- (BOOL)convertToPdfA:(NSInteger)level error:(NSError**)error;
- (BOOL)embedFile:(NSString*)name data:(NSData*)data error:(NSError**)error;
- (nullable NSData*)extractPagesToBytes:(NSArray<NSNumber*>*)pages error:(NSError**)error;

Merge another PDF (path or bytes), convert to PDF/A in place, attach an embedded file, or extract a subset of pages to a new in-memory PDF.

Barcodes

- (BOOL)addBarcode:(POXBarcode*)barcode page:(NSInteger)page x:(float)x y:(float)y width:(float)width height:(float)height error:(NSError**)error;

Place a generated barcode on a page. See POXBarcode.

Saving

- (BOOL)saveToPath:(NSString*)path error:(NSError**)error;
- (nullable NSData*)saveToBytesWithError:(NSError**)error;
- (nullable NSData*)saveToBytesCompress:(BOOL)compress garbageCollect:(BOOL)garbageCollect linearize:(BOOL)linearize error:(NSError**)error;
- (BOOL)saveEncryptedToPath:(NSString*)path userPassword:(NSString*)userPassword ownerPassword:(NSString*)ownerPassword error:(NSError**)error;
- (nullable NSData*)saveEncryptedToBytesWithUserPassword:(NSString*)userPassword ownerPassword:(NSString*)ownerPassword error:(NSError**)error;
- (void)close;

Save to a path or bytes (with optional compression/GC/linearization), save AES-encrypted to a path or bytes, or free the native handle.

---

POXDocumentBuilder

A fluent builder that constructs a brand-new PDF.

+ (nullable instancetype)createWithError:(NSError**)error;

Create a new, empty document builder.

Metadata

- (BOOL)setTitle:(NSString*)title error:(NSError**)error;
- (BOOL)setAuthor:(NSString*)author error:(NSError**)error;
- (BOOL)setSubject:(NSString*)subject error:(NSError**)error;
- (BOOL)setKeywords:(NSString*)keywords error:(NSError**)error;
- (BOOL)setCreator:(NSString*)creator error:(NSError**)error;
- (BOOL)onOpen:(NSString*)script error:(NSError**)error;

Set document metadata and a document-level open JavaScript action.

Tagged / Accessible PDF

- (BOOL)taggedPdfUa1:(NSError**)error;
- (BOOL)language:(NSString*)lang error:(NSError**)error;
- (BOOL)roleMapCustom:(NSString*)custom standard:(NSString*)standard error:(NSError**)error;

Enable PDF/UA-1 tagging, set the document language, and add a custom-to-standard role map entry.

Fonts

- (BOOL)registerEmbeddedFont:(NSString*)name font:(POXEmbeddedFont*)font error:(NSError**)error;

Register a TTF/OTF font under name (transfers ownership of the font’s native handle). See POXEmbeddedFont.

Pages

- (nullable POXPageBuilder*)a4PageWithError:(NSError**)error;
- (nullable POXPageBuilder*)letterPageWithError:(NSError**)error;
- (nullable POXPageBuilder*)pageWithWidth:(float)width height:(float)height error:(NSError**)error;

Begin an A4, US-Letter, or custom-sized page. See POXPageBuilder.

Build / Save

- (nullable NSData*)buildWithError:(NSError**)error;
- (BOOL)saveToPath:(NSString*)path error:(NSError**)error;
- (BOOL)saveEncryptedToPath:(NSString*)path userPassword:(NSString*)userPassword ownerPassword:(NSString*)ownerPassword error:(NSError**)error;
- (nullable NSData*)toBytesEncryptedWithUserPassword:(NSString*)userPassword ownerPassword:(NSString*)ownerPassword error:(NSError**)error;
- (void)close;

Build PDF bytes, save to a path, save AES-encrypted to a path or bytes, or free the native handle.

---

POXPageBuilder

A page being built within a POXDocumentBuilder. Most operations return BOOL and chain via the parent. Call -done: to commit the page or -close to discard it.

Text Layout

- (BOOL)font:(NSString*)name size:(float)size error:(NSError**)error;
- (BOOL)at:(float)x y:(float)y error:(NSError**)error;
- (BOOL)text:(NSString*)text error:(NSError**)error;
- (BOOL)heading:(uint8_t)level text:(NSString*)text error:(NSError**)error;
- (BOOL)paragraph:(NSString*)text error:(NSError**)error;
- (BOOL)space:(float)points error:(NSError**)error;
- (BOOL)horizontalRule:(NSError**)error;
- (BOOL)newline:(NSError**)error;
- (BOOL)newPageSameSize:(NSError**)error;

Set the font, cursor position, and emit text, headings, paragraphs, vertical space, a horizontal rule, a newline, or a fresh same-size page.

- (BOOL)textInRectX:(float)x y:(float)y w:(float)w h:(float)h text:(NSString*)text align:(int32_t)align error:(NSError**)error;

Lay out wrapped, aligned text inside a rectangle.

Inline Runs

- (BOOL)inlineText:(NSString*)text error:(NSError**)error;
- (BOOL)inlineBold:(NSString*)text error:(NSError**)error;
- (BOOL)inlineItalic:(NSString*)text error:(NSError**)error;
- (BOOL)inlineColorR:(float)r g:(float)g b:(float)b text:(NSString*)text error:(NSError**)error;

Append inline text runs (plain, bold, italic, or RGB-colored).

Footnotes / Columns

- (BOOL)footnoteRefMark:(NSString*)refMark noteText:(NSString*)noteText error:(NSError**)error;
- (BOOL)columnsCount:(uint32_t)columnCount gapPt:(float)gapPt text:(NSString*)text error:(NSError**)error;

Add a footnote reference + note, or flow text into multiple columns.

Links & Actions

- (BOOL)linkUrl:(NSString*)url error:(NSError**)error;
- (BOOL)linkPage:(NSInteger)page error:(NSError**)error;
- (BOOL)linkNamed:(NSString*)destination error:(NSError**)error;
- (BOOL)linkJavascript:(NSString*)script error:(NSError**)error;
- (BOOL)onOpen:(NSString*)script error:(NSError**)error;
- (BOOL)onClose:(NSString*)script error:(NSError**)error;

Add URL / page / named-destination / JavaScript links and page open/close actions.

Form-Field JS Actions

- (BOOL)fieldKeystroke:(NSString*)script error:(NSError**)error;
- (BOOL)fieldFormat:(NSString*)script error:(NSError**)error;
- (BOOL)fieldValidate:(NSString*)script error:(NSError**)error;
- (BOOL)fieldCalculate:(NSString*)script error:(NSError**)error;

Attach keystroke / format / validate / calculate JavaScript to the most-recently-added field.

Text Decorations

- (BOOL)highlightR:(float)r g:(float)g b:(float)b error:(NSError**)error;
- (BOOL)underlineR:(float)r g:(float)g b:(float)b error:(NSError**)error;
- (BOOL)strikeoutR:(float)r g:(float)g b:(float)b error:(NSError**)error;
- (BOOL)squigglyR:(float)r g:(float)g b:(float)b error:(NSError**)error;

Apply highlight, underline, strikeout, or squiggly decoration to the previous text element.

Annotations

- (BOOL)stickyNote:(NSString*)text error:(NSError**)error;
- (BOOL)stickyNoteAt:(float)x y:(float)y text:(NSString*)text error:(NSError**)error;
- (BOOL)watermark:(NSString*)text error:(NSError**)error;
- (BOOL)watermarkConfidential:(NSError**)error;
- (BOOL)watermarkDraft:(NSError**)error;
- (BOOL)stamp:(NSString*)typeName error:(NSError**)error;
- (BOOL)freetextAtX:(float)x y:(float)y w:(float)w h:(float)h text:(NSString*)text error:(NSError**)error;

Add sticky notes, watermarks (custom / CONFIDENTIAL / DRAFT), a named stamp, and free-text annotations.

Form Fields

- (BOOL)textFieldName:(NSString*)name x:(float)x y:(float)y w:(float)w h:(float)h defaultValue:(nullable NSString*)defaultValue error:(NSError**)error;
- (BOOL)checkboxName:(NSString*)name x:(float)x y:(float)y w:(float)w h:(float)h checked:(BOOL)checked error:(NSError**)error;
- (BOOL)comboBoxName:(NSString*)name x:(float)x y:(float)y w:(float)w h:(float)h options:(NSArray<NSString*>*)options selected:(nullable NSString*)selected error:(NSError**)error;
- (BOOL)radioGroupName:(NSString*)name values:(NSArray<NSString*>*)values xs:(NSArray<NSNumber*>*)xs ys:(NSArray<NSNumber*>*)ys ws:(NSArray<NSNumber*>*)ws hs:(NSArray<NSNumber*>*)hs selected:(nullable NSString*)selected error:(NSError**)error;
- (BOOL)pushButtonName:(NSString*)name x:(float)x y:(float)y w:(float)w h:(float)h caption:(NSString*)caption error:(NSError**)error;
- (BOOL)signatureFieldName:(NSString*)name x:(float)x y:(float)y w:(float)w h:(float)h error:(NSError**)error;

Add text fields, checkboxes, combo boxes, radio groups, push buttons, and signature fields.

Barcodes

- (BOOL)barcode1d:(int32_t)barcodeType data:(NSString*)data x:(float)x y:(float)y w:(float)w h:(float)h error:(NSError**)error;
- (BOOL)barcodeQrData:(NSString*)data x:(float)x y:(float)y size:(float)size error:(NSError**)error;

Draw a 1D barcode or a QR code directly on the page.

Images

- (BOOL)image:(NSData*)bytes x:(float)x y:(float)y w:(float)w h:(float)h error:(NSError**)error;
- (BOOL)imageWithAlt:(NSData*)bytes x:(float)x y:(float)y w:(float)w h:(float)h altText:(NSString*)altText error:(NSError**)error;
- (BOOL)imageArtifact:(NSData*)bytes x:(float)x y:(float)y w:(float)w h:(float)h error:(NSError**)error;

Place an image, an image with accessibility alt text, or an artifact (decorative) image.

Vector Graphics

- (BOOL)rectX:(float)x y:(float)y w:(float)w h:(float)h error:(NSError**)error;
- (BOOL)filledRectX:(float)x y:(float)y w:(float)w h:(float)h r:(float)r g:(float)g b:(float)b error:(NSError**)error;
- (BOOL)lineX1:(float)x1 y1:(float)y1 x2:(float)x2 y2:(float)y2 error:(NSError**)error;
- (BOOL)strokeRectX:(float)x y:(float)y w:(float)w h:(float)h width:(float)width r:(float)r g:(float)g b:(float)b error:(NSError**)error;
- (BOOL)strokeLineX1:(float)x1 y1:(float)y1 x2:(float)x2 y2:(float)y2 width:(float)width r:(float)r g:(float)g b:(float)b error:(NSError**)error;
- (BOOL)strokeRectDashedX:(float)x y:(float)y w:(float)w h:(float)h width:(float)width r:(float)r g:(float)g b:(float)b dashArray:(NSArray<NSNumber*>*)dashArray phase:(float)phase error:(NSError**)error;
- (BOOL)strokeLineDashedX1:(float)x1 y1:(float)y1 x2:(float)x2 y2:(float)y2 width:(float)width r:(float)r g:(float)g b:(float)b dashArray:(NSArray<NSNumber*>*)dashArray phase:(float)phase error:(NSError**)error;

Draw rectangles (outline / filled / stroked / dashed) and lines (plain / stroked / dashed).

Tables

- (BOOL)tableColumns:(NSArray<NSNumber*>*)widths aligns:(NSArray<NSNumber*>*)aligns rows:(NSArray<NSArray<NSString*>*>*)rows hasHeader:(BOOL)hasHeader error:(NSError**)error;

Render a complete table with column widths, alignments, and rows.

Streaming Tables

- (BOOL)streamingTableBeginHeaders:(NSArray<NSString*>*)headers widths:(NSArray<NSNumber*>*)widths aligns:(NSArray<NSNumber*>*)aligns repeatHeader:(BOOL)repeatHeader error:(NSError**)error;
- (BOOL)streamingTableBeginV2Headers:(NSArray<NSString*>*)headers widths:(NSArray<NSNumber*>*)widths aligns:(NSArray<NSNumber*>*)aligns repeatHeader:(BOOL)repeatHeader mode:(int32_t)mode sampleRows:(NSInteger)sampleRows minColWidthPt:(float)minColWidthPt maxColWidthPt:(float)maxColWidthPt maxRowspan:(NSInteger)maxRowspan error:(NSError**)error;
- (BOOL)streamingTableSetBatchSize:(NSInteger)batchSize error:(NSError**)error;
- (NSInteger)streamingTablePendingRowCount;
- (NSInteger)streamingTableBatchCount;
- (BOOL)streamingTableFlush:(NSError**)error;
- (BOOL)streamingTablePushRow:(NSArray<NSString*>*)cells error:(NSError**)error;
- (BOOL)streamingTablePushRowV2:(NSArray<NSString*>*)cells rowspans:(nullable NSArray<NSNumber*>*)rowspans error:(NSError**)error;
- (BOOL)streamingTableFinish:(NSError**)error;

Begin a streaming table (basic or V2 auto-layout), tune batch size, push rows (with optional rowspans), flush, and finish — for tables too large to materialize at once.

Commit

- (BOOL)done:(NSError**)error;
- (void)close;

Commit the page to its parent builder, or discard it.

---

POXEmbeddedFont

A TTF/OTF font loaded for embedding. Ownership transfers to the builder on a successful registerEmbeddedFont:font:.

+ (nullable instancetype)fromPath:(NSString*)path error:(NSError**)error;
+ (nullable instancetype)fromBytes:(NSData*)data name:(nullable NSString*)name error:(NSError**)error;
- (void)close;

Load a font from a path or bytes (name may be nil to use the PostScript name), or free the native handle.

---

POXBarcode

A generated barcode / QR code image.

+ (nullable instancetype)generateQrCode:(NSString*)data errorCorrection:(int32_t)errorCorrection sizePx:(int32_t)sizePx error:(NSError**)error;
+ (nullable instancetype)generateBarcode:(NSString*)data format:(int32_t)format sizePx:(int32_t)sizePx error:(NSError**)error;

Generate a QR code (with error-correction level) or a 1D/2D barcode of a given format.

- (nullable NSString*)dataError:(NSError**)error;
- (int32_t)formatError:(NSError**)error;
- (float)confidenceError:(NSError**)error;
- (nullable NSData*)imagePngWithSizePx:(int32_t)sizePx error:(NSError**)error;
- (nullable NSString*)svgWithSizePx:(int32_t)sizePx error:(NSError**)error;
- (void)close;

Read the payload, format code, and decode confidence; encode as PNG bytes or an SVG string; or free the native handle.

---

POXOcrEngine

An OCR engine backed by detection/recognition/dictionary model files.

+ (nullable instancetype)createWithDetModelPath:(NSString*)detModelPath recModelPath:(NSString*)recModelPath dictPath:(NSString*)dictPath error:(NSError**)error;
- (nullable void*)POX_engineHandle;
- (void)close;

Create an engine from model + dictionary paths, expose the raw engine handle for ocrExtractText:engine:error:, or free the native handle.

---

POXElementList

A layout-element list for a page.

- (int32_t)count;
- (nullable NSString*)typeAtIndex:(int32_t)index error:(NSError**)error;
- (nullable NSString*)textAtIndex:(int32_t)index error:(NSError**)error;
- (POXBbox)rectAtIndex:(int32_t)index error:(NSError**)error;
- (nullable NSString*)toJsonWithError:(NSError**)error;
- (void)close;

Count elements; read each element’s type string, text, and bounding box; serialize the whole list to JSON; or free the native handle.

---

POXRenderer

A standalone renderer handle (independent of a document).

+ (nullable instancetype)createWithDpi:(int32_t)dpi format:(int32_t)format quality:(int32_t)quality antiAlias:(BOOL)antiAlias error:(NSError**)error;
- (void)close;

Create a configured renderer (DPI, format, quality, anti-aliasing), or free the native handle.

---

Digital Signatures & PKI

POXCertificate

A loaded signing / verifier certificate.

+ (nullable instancetype)loadFromBytes:(NSData*)data password:(NSString*)password error:(NSError**)error;
+ (nullable instancetype)loadFromPemCert:(NSString*)certPem keyPem:(NSString*)keyPem error:(NSError**)error;

Load credentials from PKCS#12 bytes + password, or from PEM certificate + private key.

- (nullable NSString*)subjectError:(NSError**)error;
- (nullable NSString*)issuerError:(NSError**)error;
- (nullable NSString*)serialError:(NSError**)error;
- (BOOL)validityNotBefore:(int64_t*)notBefore notAfter:(int64_t*)notAfter error:(NSError**)error;
- (int32_t)isValidError:(NSError**)error;
- (void)close;

Read subject / issuer / serial, the validity window (Unix epoch seconds), current validity (1/0/-1), or free the native handle.

POXSignatureInfo

Information about a signature read from a document.

- (nullable NSString*)signerNameError:(NSError**)error;
- (nullable NSString*)signingReasonError:(NSError**)error;
- (nullable NSString*)signingLocationError:(NSError**)error;
- (int64_t)signingTimeError:(NSError**)error;
- (nullable POXCertificate*)certificateError:(NSError**)error;
- (int32_t)padesLevelError:(NSError**)error;
- (BOOL)hasTimestampError:(NSError**)error;
- (nullable POXTimestamp*)timestampError:(NSError**)error;
- (BOOL)addTimestamp:(POXTimestamp*)timestamp error:(NSError**)error;
- (int32_t)verifyError:(NSError**)error;
- (int32_t)verifyDetached:(NSData*)pdf error:(NSError**)error;
- (void)close;

Read signer/reason/location/time, the signer certificate, PAdES baseline level, and timestamp; attach a timestamp; crypto-verify (verifyError:) or end-to-end verify against the full PDF bytes (verifyDetached:).

POXTimestamp

A parsed RFC 3161 timestamp token.

+ (nullable instancetype)parse:(NSData*)data error:(NSError**)error;
- (nullable NSData*)tokenError:(NSError**)error;
- (nullable NSData*)messageImprintError:(NSError**)error;
- (int64_t)timeError:(NSError**)error;
- (nullable NSString*)serialError:(NSError**)error;
- (nullable NSString*)tsaNameError:(NSError**)error;
- (nullable NSString*)policyOidError:(NSError**)error;
- (int32_t)hashAlgorithmError:(NSError**)error;
- (BOOL)verifyError:(NSError**)error;
- (void)close;

Parse a DER token; read raw token bytes, message imprint, time, serial, TSA name, policy OID, and hash algorithm; verify; or free the native handle.

POXTsaClient

A TSA (RFC 3161) client.

+ (nullable instancetype)createWithUrl:(NSString*)url username:(nullable NSString*)username password:(nullable NSString*)password timeout:(int32_t)timeout hashAlgo:(int32_t)hashAlgo useNonce:(BOOL)useNonce certReq:(BOOL)certReq error:(NSError**)error;
- (nullable POXTimestamp*)requestTimestamp:(NSData*)data error:(NSError**)error;
- (nullable POXTimestamp*)requestTimestampHash:(NSData*)hash hashAlgo:(int32_t)hashAlgo error:(NSError**)error;
- (void)close;

Create a client, request a timestamp over data or a pre-computed hash, or free the native handle.

POXDss

A Document Security Store read from a document.

- (int32_t)certCount;
- (int32_t)crlCount;
- (int32_t)ocspCount;
- (int32_t)vriCount;
- (nullable NSData*)certAtIndex:(int32_t)index error:(NSError**)error;
- (nullable NSData*)crlAtIndex:(int32_t)index error:(NSError**)error;
- (nullable NSData*)ocspAtIndex:(int32_t)index error:(NSError**)error;
- (void)close;

Count and read the DER certificates, CRLs, and OCSP responses (plus VRI count) in the DSS.

POXSigning

Top-level signing entry points and library log configuration (class methods).

+ (nullable NSData*)signBytes:(NSData*)pdf certificate:(POXCertificate*)certificate reason:(nullable NSString*)reason location:(nullable NSString*)location error:(NSError**)error;

Sign raw PDF bytes with a basic (non-PAdES) signature.

+ (nullable NSData*)signBytesPades:(NSData*)pdf certificate:(POXCertificate*)certificate level:(int32_t)level tsaUrl:(nullable NSString*)tsaUrl reason:(nullable NSString*)reason location:(nullable NSString*)location certs:(NSArray<NSData*>*)certs crls:(NSArray<NSData*>*)crls ocsps:(NSArray<NSData*>*)ocsps error:(NSError**)error;

Sign raw PDF bytes at a PAdES baseline level with revocation material.

+ (nullable NSData*)signBytesPadesOpts:(NSData*)pdf options:(POXPadesSignOptions*)options error:(NSError**)error;

Sign raw PDF bytes using a POXPadesSignOptions config object.

+ (void)setLogLevel:(int32_t)level;
+ (int32_t)logLevel;

Set / get the global log level (0=Off … 5=Trace).

POXPadesSignOptions

PAdES signing options (struct-pointer variant). All fields are properties:

Property	Type	Description
certificate	POXCertificate*	Signing certificate
level	int32_t	PAdES baseline (0=B-B, 1=B-T, 2=B-LT)
tsaUrl	NSString*	TSA URL (nullable)
reason	NSString*	Signing reason (nullable)
location	NSString*	Signing location (nullable)
certs / crls / ocsps	NSArray<NSData*>*	DER-encoded revocation material (B-LT)

---

Conformance Result Types

POXPdfAResults

- (BOOL)isCompliantError:(NSError**)error;
- (int32_t)errorCount;
- (int32_t)warningCount;
- (NSArray<NSString*>*)errors;
- (void)close;

PDF/A validation result: compliance flag, error/warning counts, error messages.

POXUaResults

- (BOOL)isAccessibleError:(NSError**)error;
- (int32_t)errorCount;
- (int32_t)warningCount;
- (NSArray<NSString*>*)errors;
- (NSArray<NSString*>*)warnings;
- (BOOL)stats:(POXUaStats*)stats error:(NSError**)error;
- (void)close;

PDF/UA accessibility result: accessibility flag, error/warning counts and messages, and an element-count POXUaStats struct.

POXPdfXResults

- (BOOL)isCompliantError:(NSError**)error;
- (int32_t)errorCount;
- (NSArray<NSString*>*)errors;
- (void)close;

PDF/X validation result: compliance flag, error count, error messages.

---

Top-Level Utilities

POXTools

+ (nullable NSData*)merge:(NSArray<NSString*>*)paths error:(NSError**)error;
+ (nullable NSData*)addTimestamp:(NSData*)pdfData sigIndex:(int32_t)sigIndex tsaUrl:(NSString*)tsaUrl error:(NSError**)error;

Merge PDFs at the given paths into one in-memory PDF; append an RFC 3161 document timestamp to a signature.

POXCrypto

+ (nullable NSString*)activeProviderWithError:(NSError**)error;
+ (nullable NSString*)cbomWithError:(NSError**)error;
+ (nullable NSString*)inventoryWithError:(NSError**)error;
+ (nullable NSString*)policyWithError:(NSError**)error;
+ (int32_t)fipsAvailable;
+ (int32_t)useFips;
+ (int32_t)setPolicy:(NSString*)spec;

Crypto-provider introspection (active provider, CycloneDX CBOM, inventory, policy) and FIPS policy controls.

POXModels

+ (nullable NSString*)manifestWithError:(NSError**)error;
+ (int32_t)prefetchAvailable;
+ (nullable NSString*)prefetchModels:(NSString*)languagesCsv error:(NSError**)error;

Read the bundled model manifest, check prefetch availability, and prefetch ML models for the given language codes.

POXConfig

+ (int64_t)setMaxOpsPerStream:(int64_t)limit;
+ (int32_t)setPreserveUnmappedGlyphs:(int32_t)preserve;

Process-global knobs: cap operators decoded per content stream, and toggle preserving unmapped glyphs in extracted text. Each returns the previous value.

---

Value Types

These read-only NSObject types are returned by the extraction methods above.

POXChar

Property	Type	Description
character	uint32_t	Unicode codepoint
bbox	POXBbox	Bounding box
fontName	NSString*	PostScript font name
fontSize	float	Font size in points

POXWord

Property	Type	Description
text	NSString*	Word text
bbox	POXBbox	Bounding box
fontName	NSString*	PostScript font name
fontSize	float	Font size in points
bold	BOOL	Whether the word is bold

POXTextLine

Property	Type	Description
text	NSString*	Line text
bbox	POXBbox	Bounding box
wordCount	NSInteger	Number of words on the line

- (nullable NSString*)cellTextAtRow:(NSInteger)row col:(NSInteger)col;  // POXTable

POXTable

Property / Method	Type	Description
rowCount	NSInteger	Number of rows
colCount	NSInteger	Number of columns
hasHeader	BOOL	Whether the table has a header row
cellTextAtRow:col:	NSString*	Cell text at (row, col) (nil if out of range)

POXFont

Property	Type	Description
name	NSString*	Font name
type	NSString*	Font type (e.g. TrueType, Type1)
encoding	NSString*	Font encoding
embedded	BOOL	Whether the font is embedded
subset	BOOL	Whether the font is subset
size	float	Nominal size in points (0 if unknown)

POXImage

Property	Type	Description
width / height	NSInteger	Pixel dimensions
bitsPerComponent	NSInteger	Bits per color component
format	NSString*	Image format
colorspace	NSString*	Color space
data	NSData*	Encoded image bytes

POXAnnotation

Property	Type	Description
type / subtype	NSString*	Annotation type and subtype
content / author	NSString*	Contents and author
rect	POXBbox	Annotation rectangle
borderWidth	float	Border width
color	uint32_t	Color packed as 0xAARRGGBB (0 if absent)
creationDate / modificationDate	int64_t	Unix epoch seconds (0 if absent)
hidden / markedDeleted / printable / readOnly	BOOL	Flags
linkUri	NSString*	Target URI for Link annotations (nullable)
iconName	NSString*	Icon name for Text/note annotations (nullable)
quadPoints	NSArray<NSArray<NSNumber*>*>*	Quad points for Highlight annotations

POXFormField

Property	Type	Description
name	NSString*	Field name
value	NSString*	Current value
type	NSString*	Field type
readonly	BOOL	Whether the field is read-only
required	BOOL	Whether the field is required

POXPath

Property	Type	Description
bbox	POXBbox	Bounding box
strokeWidth	float	Stroke width
hasStroke / hasFill	BOOL	Whether the path is stroked / filled
operationCount	NSInteger	Number of path operations

POXSearchResult

Property	Type	Description
text	NSString*	Matched text
page	NSInteger	Zero-based page index
bbox	POXBbox	Match bounding box

POXRenderedImage

Property / Method	Type	Description
width / height	NSInteger	Pixel dimensions
data	NSData*	Encoded image bytes (e.g. PNG)
saveToPath:error:	BOOL	Write the rendered image to a file
close	void	Free the native handle

---

Error Handling

Failing operations return nil / NO / a negative status and populate the NSError** out-param with an error in the POXErrorDomain:

NSError* error = nil;
POXDocument* doc = [POXDocument openPath:@"input.pdf" error:&error];
if (!doc) {
    NSLog(@"Open failed: %@", error.localizedDescription);
    return;
}

NSString* text = [doc extractText:0 error:&error];
if (!text) {
    NSLog(@"Extraction failed: %@", error.localizedDescription);
}
[doc close];

---

Complete Example

#import <PdfOxide/POXPdfOxide.h>

NSError* error = nil;

// --- Extraction ---
POXDocument* doc = [POXDocument openPath:@"input.pdf" error:&error];
NSInteger pages = [doc pageCountError:&error];
for (NSInteger i = 0; i < pages; i++) {
    NSString* md = [doc toMarkdown:i error:&error];
    NSLog(@"Page %ld: %lu chars", (long)i, (unsigned long)md.length);
}

// Render page 0 to PNG
POXRenderedImage* img = [doc renderPage:0 format:0 error:&error];
[img saveToPath:@"page0.png" error:&error];
[doc close];

// --- Creation ---
POXDocumentBuilder* builder = [POXDocumentBuilder createWithError:&error];
[builder setTitle:@"Report" error:&error];
POXPageBuilder* page = [builder letterPageWithError:&error];
[page heading:1 text:@"Report" error:&error];
[page paragraph:@"Generated by PDF Oxide." error:&error];
[page done:&error];
[builder saveToPath:@"report.pdf" error:&error];

// --- Editing ---
POXDocumentEditor* editor = [POXDocumentEditor openEditor:@"document.pdf" error:&error];
[editor rotateAllPages:90 error:&error];
[editor setFormField:@"name" value:@"John Doe" error:&error];
[editor saveToPath:@"output.pdf" error:&error];
[editor close];

Other Language Bindings

PDF Oxide ships native bindings for every major ecosystem: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, and Elixir.

Next Steps

• Types & Enums — all shared types and enums
• Page API Reference — consistent per-page iteration across bindings
• Getting Started with Objective-C — tutorial