193 lines
6 KiB
C
193 lines
6 KiB
C
/**
|
|
* @file zpdf.h
|
|
* @brief C header for zpdf library FFI
|
|
*
|
|
* This header declares the C API exported by zpdf (https://github.com/Lulzx/zpdf).
|
|
* zpdf is a high-performance PDF text extraction library written in Zig.
|
|
*/
|
|
|
|
#ifndef ZPDF_H
|
|
#define ZPDF_H
|
|
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* Opaque document handle.
|
|
* Created by zpdf_open() or zpdf_open_memory(), freed by zpdf_close().
|
|
*/
|
|
typedef struct ZpdfDocument ZpdfDocument;
|
|
|
|
/**
|
|
* Text span with bounding box information.
|
|
* Used by zpdf_extract_bounds() for layout-aware extraction.
|
|
*/
|
|
typedef struct {
|
|
double x0, y0, x1, y1; /**< Bounding box coordinates */
|
|
const uint8_t* text; /**< Text content (not null-terminated) */
|
|
size_t text_len; /**< Length of text in bytes */
|
|
double font_size; /**< Font size in points */
|
|
} CTextSpan;
|
|
|
|
/* ============================================================================
|
|
* Document Lifecycle
|
|
* ============================================================================ */
|
|
|
|
/**
|
|
* Open a PDF document from a file path.
|
|
*
|
|
* @param path Null-terminated file path
|
|
* @return Document handle, or NULL on error
|
|
*/
|
|
ZpdfDocument* zpdf_open(const char* path);
|
|
|
|
/**
|
|
* Open a PDF document from a memory buffer.
|
|
*
|
|
* @param data Pointer to PDF data
|
|
* @param len Length of data in bytes
|
|
* @return Document handle, or NULL on error
|
|
*/
|
|
ZpdfDocument* zpdf_open_memory(const uint8_t* data, size_t len);
|
|
|
|
/**
|
|
* Close a document and free associated resources.
|
|
*
|
|
* @param handle Document handle (may be NULL)
|
|
*/
|
|
void zpdf_close(ZpdfDocument* handle);
|
|
|
|
/* ============================================================================
|
|
* Page Information
|
|
* ============================================================================ */
|
|
|
|
/**
|
|
* Get the number of pages in the document.
|
|
*
|
|
* @param handle Document handle
|
|
* @return Page count (>= 0), or -1 on error
|
|
*/
|
|
int zpdf_page_count(ZpdfDocument* handle);
|
|
|
|
/**
|
|
* Get information about a specific page.
|
|
*
|
|
* @param handle Document handle
|
|
* @param page_num Page number (0-indexed)
|
|
* @param width Output: page width in points
|
|
* @param height Output: page height in points
|
|
* @param rotation Output: page rotation in degrees (0, 90, 180, 270)
|
|
* @return 0 on success, -1 on error
|
|
*/
|
|
int zpdf_get_page_info(ZpdfDocument* handle, int page_num, double* width, double* height,
|
|
int* rotation);
|
|
|
|
/* ============================================================================
|
|
* Text Extraction
|
|
* ============================================================================ */
|
|
|
|
/**
|
|
* Extract text from a single page.
|
|
*
|
|
* @param handle Document handle
|
|
* @param page_num Page number (0-indexed)
|
|
* @param out_len Output: length of extracted text
|
|
* @return Extracted text (caller must free with zpdf_free_buffer), or NULL on error
|
|
*/
|
|
uint8_t* zpdf_extract_page(ZpdfDocument* handle, int page_num, size_t* out_len);
|
|
|
|
/**
|
|
* Extract text from all pages (sequential processing).
|
|
*
|
|
* @param handle Document handle
|
|
* @param out_len Output: length of extracted text
|
|
* @return Extracted text (caller must free with zpdf_free_buffer), or NULL on error
|
|
*/
|
|
uint8_t* zpdf_extract_all(ZpdfDocument* handle, size_t* out_len);
|
|
|
|
/**
|
|
* Extract text from all pages using parallel processing.
|
|
* This is the fastest extraction method for multi-page documents.
|
|
*
|
|
* @param handle Document handle
|
|
* @param out_len Output: length of extracted text
|
|
* @return Extracted text (caller must free with zpdf_free_buffer), or NULL on error
|
|
*/
|
|
uint8_t* zpdf_extract_all_parallel(ZpdfDocument* handle, size_t* out_len);
|
|
|
|
/* ============================================================================
|
|
* Reading Order Extraction (Experimental)
|
|
* ============================================================================ */
|
|
|
|
/**
|
|
* Extract text from a single page in visual reading order.
|
|
* This attempts to order text as it would be read visually.
|
|
*
|
|
* @param handle Document handle
|
|
* @param page_num Page number (0-indexed)
|
|
* @param out_len Output: length of extracted text
|
|
* @return Extracted text (caller must free with zpdf_free_buffer), or NULL on error
|
|
*/
|
|
uint8_t* zpdf_extract_page_reading_order(ZpdfDocument* handle, int page_num, size_t* out_len);
|
|
|
|
/**
|
|
* Extract text from all pages in visual reading order (sequential).
|
|
*
|
|
* @param handle Document handle
|
|
* @param out_len Output: length of extracted text
|
|
* @return Extracted text (caller must free with zpdf_free_buffer), or NULL on error
|
|
*/
|
|
uint8_t* zpdf_extract_all_reading_order(ZpdfDocument* handle, size_t* out_len);
|
|
|
|
/**
|
|
* Extract text from all pages in visual reading order (parallel).
|
|
*
|
|
* @param handle Document handle
|
|
* @param out_len Output: length of extracted text
|
|
* @return Extracted text (caller must free with zpdf_free_buffer), or NULL on error
|
|
*/
|
|
uint8_t* zpdf_extract_all_reading_order_parallel(ZpdfDocument* handle, size_t* out_len);
|
|
|
|
/* ============================================================================
|
|
* Bounds Extraction
|
|
* ============================================================================ */
|
|
|
|
/**
|
|
* Extract text spans with bounding box information.
|
|
*
|
|
* @param handle Document handle
|
|
* @param page_num Page number (0-indexed)
|
|
* @param out_count Output: number of spans
|
|
* @return Array of text spans (caller must free with zpdf_free_bounds), or NULL on error
|
|
*/
|
|
CTextSpan* zpdf_extract_bounds(ZpdfDocument* handle, int page_num, size_t* out_count);
|
|
|
|
/* ============================================================================
|
|
* Memory Management
|
|
* ============================================================================ */
|
|
|
|
/**
|
|
* Free a text buffer returned by extraction functions.
|
|
*
|
|
* @param ptr Buffer pointer (may be NULL)
|
|
* @param len Buffer length
|
|
*/
|
|
void zpdf_free_buffer(uint8_t* ptr, size_t len);
|
|
|
|
/**
|
|
* Free a text spans array returned by zpdf_extract_bounds().
|
|
*
|
|
* @param ptr Spans array pointer (may be NULL)
|
|
* @param count Number of spans
|
|
*/
|
|
void zpdf_free_bounds(CTextSpan* ptr, size_t count);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* ZPDF_H */
|