pdfio Programming Manual

Introduction

pdfio is a simple C library for reading and writing PDF files. The primary goals of pdfio are:

• Read any PDF file with or without encryption or linearization

• Write PDF files without encryption or linearization

• Extract or embed useful metadata (author, creator, page information, etc.)

• "Filter" PDF files, for example to extract a range of pages or to embed fonts that are missing from a PDF

• Provide access to objects used for each page

pdfio is not concerned with rendering or viewing a PDF file, although a PDF RIP or viewer could be written using it.

Functions

pdfioArrayAppendArray

Add an array value to an array.

bool pdfioArrayAppendArray(pdfio_array_t *a, pdfio_array_t *value);

Parameters

a	Array
value	Value

Return Value

true on success, false on failure

pdfioArrayAppendBinary

Add a binary string value to an array.

bool pdfioArrayAppendBinary(pdfio_array_t *a, unsigned char *value, size_t valuelen);

Parameters

a	Array
value	Value
valuelen	Length of value

Return Value

true on success, false on failure

pdfioArrayAppendBoolean

Add a boolean value to an array.

bool pdfioArrayAppendBoolean(pdfio_array_t *a, bool value);

Parameters

a	Array
value	Value

Return Value

true on success, false on failure

pdfioArrayAppendDict

Add a dictionary to an array.

bool pdfioArrayAppendDict(pdfio_array_t *a, pdfio_dict_t *value);

Parameters

a	Array
value	Value

Return Value

true on success, false on failure

pdfioArrayAppendName

Add a name to an array.

bool pdfioArrayAppendName(pdfio_array_t *a, const char *value);

Parameters

a	Array
value	Value

Return Value

true on success, false on failure

pdfioArrayAppendNumber

Add a number to an array.

bool pdfioArrayAppendNumber(pdfio_array_t *a, double value);

Parameters

a	Array
value	Value

Return Value

true on success, false on failure

pdfioArrayAppendObject

Add an indirect object reference to an array.

bool pdfioArrayAppendObject(pdfio_array_t *a, pdfio_obj_t *value);

Parameters

a	Array
value	Value

Return Value

true on success, false on failure

pdfioArrayAppendString

Add a string to an array.

bool pdfioArrayAppendString(pdfio_array_t *a, const char *value);

Parameters

a	Array
value	Value

Return Value

true on success, false on failure

pdfioArrayCopy

Copy an array.

pdfio_array_t *pdfioArrayCopy(pdfio_file_t *pdf, pdfio_array_t *a);

Parameters

pdf	PDF file
a	Original array

Return Value

New array or NULL on error

pdfioArrayCreate

Create an empty array.

pdfio_array_t *pdfioArrayCreate(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

New array or NULL on error

pdfioArrayGetArray

Get an array value from an array.

pdfio_array_t *pdfioArrayGetArray(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value

pdfioArrayGetBinary

Get a binary string value from an array.

unsigned char *pdfioArrayGetBinary(pdfio_array_t *a, size_t n, size_t *length);

Parameters

a	Array
n	Index
length	Length of string

Return Value

Value

pdfioArrayGetBoolean

Get a boolean value from an array.

bool pdfioArrayGetBoolean(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value

pdfioArrayGetDict

Get a dictionary value from an array.

pdfio_dict_t *pdfioArrayGetDict(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value

pdfioArrayGetName

Get a name value from an array.

const char *pdfioArrayGetName(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value

pdfioArrayGetNumber

Get a number from an array.

double pdfioArrayGetNumber(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value

pdfioArrayGetObject

Get an indirect object reference from an array.

pdfio_obj_t *pdfioArrayGetObject(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value

pdfioArrayGetSize

Get the length of an array.

size_t pdfioArrayGetSize(pdfio_array_t *a);

Parameters

a	Array

Return Value

Length of array

pdfioArrayGetString

Get a string value from an array.

const char *pdfioArrayGetString(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value

pdfioArrayGetType

Get a value type from an array.

pdfio_valtype_t pdfioArrayGetType(pdfio_array_t *a, size_t n);

Parameters

a	Array
n	Index

Return Value

Value type

pdfioContentBeginText

Begin a text block.

bool pdfioContentBeginText(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioContentClip

Clip output to the current path.

bool pdfioContentClip(pdfio_stream_t *st, bool even_odd);

Parameters

st	Stream
even_odd	Even/odd fill vs. non-zero winding rule

Return Value

true on success, false on failure

pdfioContentDrawImage

Draw an image object.

bool pdfioContentDrawImage(pdfio_stream_t *st, const char *name, double x, double y, double w, double h);

Parameters

st	Stream
name	Image name
x	X offset of image
y	Y offset of image
w	Width of image
h	Height of image

Return Value

true on success, false on failure

Discussion

The object name must be part of the page dictionary resources, typically using the pdfioPageDictAddImage function.

pdfioContentEndText

End a text block.

bool pdfioContentEndText(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioContentFill

Fill the current path.

bool pdfioContentFill(pdfio_stream_t *st, bool even_odd);

Parameters

st	Stream
even_odd	Even/odd fill vs. non-zero winding rule

Return Value

true on success, false on failure

pdfioContentFillAndStroke

Fill and stroke the current path.

bool pdfioContentFillAndStroke(pdfio_stream_t *st, bool even_odd);

Parameters

st	Stream
even_odd	Even/odd fill vs. non-zero winding

Return Value

true on success, false on failure

pdfioContentMatrixConcat

Concatenate a matrix to the current graphics state.

bool pdfioContentMatrixConcat(pdfio_stream_t *st, pdfio_matrix_t m);

Parameters

st	Stream
m	Transform matrix

Return Value

true on success, false on failure

pdfioContentMatrixRotate

Rotate the current transform matrix.

bool pdfioContentMatrixRotate(pdfio_stream_t *st, double degrees);

Parameters

st	Stream
degrees	Rotation angle in degrees counter-clockwise

Return Value

true on success, false on failure

pdfioContentMatrixScale

Scale the current transform matrix.

bool pdfioContentMatrixScale(pdfio_stream_t *st, double sx, double sy);

Parameters

st	Stream
sx	X scale
sy	Y scale

Return Value

true on success, false on failure

pdfioContentMatrixTranslate

Translate the current transform matrix.

bool pdfioContentMatrixTranslate(pdfio_stream_t *st, double tx, double ty);

Parameters

st	Stream
tx	X offset
ty	Y offset

Return Value

true on success, false on failure

pdfioContentPathClose

Close the current path.

bool pdfioContentPathClose(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioContentPathCurve

Add a Bezier curve with two control points.

bool pdfioContentPathCurve(pdfio_stream_t *st, double x1, double y1, double x2, double y2, double x3, double y3);

Parameters

st	Stream
x1	X position 1
y1	Y position 1
x2	X position 2
y2	Y position 2
x3	X position 3
y3	Y position 3

Return Value

true on success, false on failure

pdfioContentPathCurve13

Add a Bezier curve with an initial control point.

bool pdfioContentPathCurve13(pdfio_stream_t *st, double x1, double y1, double x3, double y3);

Parameters

st	Stream
x1	X position 1
y1	Y position 1
x3	X position 3
y3	Y position 3

Return Value

true on success, false on failure

pdfioContentPathCurve23

Add a Bezier curve with a trailing control point.

bool pdfioContentPathCurve23(pdfio_stream_t *st, double x2, double y2, double x3, double y3);

Parameters

st	Stream
x2	X position 2
y2	Y position 2
x3	X position 3
y3	Y position 3

Return Value

true on success, false on failure

pdfioContentPathLineTo

Add a straight line to the current path.

bool pdfioContentPathLineTo(pdfio_stream_t *st, double x, double y);

Parameters

st	Stream
x	X position
y	Y position

Return Value

true on success, false on failure

pdfioContentPathMoveTo

Start a new subpath.

bool pdfioContentPathMoveTo(pdfio_stream_t *st, double x, double y);

Parameters

st	Stream
x	X position
y	Y position

Return Value

true on success, false on failure

pdfioContentPathRect

Add a rectangle to the current path.

bool pdfioContentPathRect(pdfio_stream_t *st, pdfio_rect_t *rect);

Parameters

st	Stream
rect	Rectangle

Return Value

true on success, false on failure

pdfioContentRestore

Restore a previous graphics state.

bool pdfioContentRestore(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioContentSave

Save the current graphics state.

bool pdfioContentSave(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioContentSetDashPattern

Set the stroke pattern.

bool pdfioContentSetDashPattern(pdfio_stream_t *st, int phase, int on, int off);

Parameters

st	Stream
phase	Phase (offset within pattern)
on	On length
off	Off length

Return Value

true on success, false on failure

pdfioContentSetFillColorDeviceCMYK

Set device CMYK fill color.

bool pdfioContentSetFillColorDeviceCMYK(pdfio_stream_t *st, double c, double m, double y, double k);

Parameters

st	Stream
c	Cyan value (0.0 to 1.0)
m	Magenta value (0.0 to 1.0)
y	Yellow value (0.0 to 1.0)
k	Black value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetFillColorDeviceGray

Set the device gray fill color.

bool pdfioContentSetFillColorDeviceGray(pdfio_stream_t *st, double g);

Parameters

st	Stream
g	Gray value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetFillColorDeviceRGB

Set the device RGB fill color.

bool pdfioContentSetFillColorDeviceRGB(pdfio_stream_t *st, double r, double g, double b);

Parameters

st	Stream
r	Red value (0.0 to 1.0)
g	Green value (0.0 to 1.0)
b	Blue value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetFillColorGray

Set the calibrated gray fill color.

bool pdfioContentSetFillColorGray(pdfio_stream_t *st, double g);

Parameters

st	Stream
g	Gray value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetFillColorRGB

Set the calibrated RGB fill color.

bool pdfioContentSetFillColorRGB(pdfio_stream_t *st, double r, double g, double b);

Parameters

st	Stream
r	Red value (0.0 to 1.0)
g	Green value (0.0 to 1.0)
b	Blue value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetFillColorSpace

Set the fill colorspace.

bool pdfioContentSetFillColorSpace(pdfio_stream_t *st, const char *name);

Parameters

st	Stream
name	Color space name

Return Value

true on success, false on failure

pdfioContentSetFlatness

Set the flatness tolerance.

bool pdfioContentSetFlatness(pdfio_stream_t *st, double flatness);

Parameters

st	Stream
flatness	Flatness value (0.0 to 100.0)

Return Value

true on success, false on failure

pdfioContentSetLineCap

Set the line ends style.

bool pdfioContentSetLineCap(pdfio_stream_t *st, pdfio_linecap_t lc);

Parameters

st	Stream
lc	Line cap value

Return Value

true on success, false on failure

pdfioContentSetLineJoin

Set the line joining style.

bool pdfioContentSetLineJoin(pdfio_stream_t *st, pdfio_linejoin_t lj);

Parameters

st	Stream
lj	Line join value

Return Value

true on success, false on failure

pdfioContentSetLineWidth

Set the line width.

bool pdfioContentSetLineWidth(pdfio_stream_t *st, double width);

Parameters

st	Stream
width	Line width value

Return Value

true on success, false on failure

pdfioContentSetMiterLimit

Set the miter limit.

bool pdfioContentSetMiterLimit(pdfio_stream_t *st, double limit);

Parameters

st	Stream
limit	Miter limit value

Return Value

true on success, false on failure

pdfioContentSetStrokeColorDeviceCMYK

Set the device CMYK stroke color.

bool pdfioContentSetStrokeColorDeviceCMYK(pdfio_stream_t *st, double c, double m, double y, double k);

Parameters

st	Stream
c	Cyan value (0.0 to 1.0)
m	Magenta value (0.0 to 1.0)
y	Yellow value (0.0 to 1.0)
k	Black value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetStrokeColorDeviceGray

Set the device gray stroke color.

bool pdfioContentSetStrokeColorDeviceGray(pdfio_stream_t *st, double g);

Parameters

st	Stream
g	Gray value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetStrokeColorDeviceRGB

Set the device RGB stroke color.

bool pdfioContentSetStrokeColorDeviceRGB(pdfio_stream_t *st, double r, double g, double b);

Parameters

st	Stream
r	Red value (0.0 to 1.0)
g	Green value (0.0 to 1.0)
b	Blue value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetStrokeColorGray

Set the calibrated gray stroke color.

bool pdfioContentSetStrokeColorGray(pdfio_stream_t *st, double g);

Parameters

st	Stream
g	Gray value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetStrokeColorRGB

Set the calibrated RGB stroke color.

bool pdfioContentSetStrokeColorRGB(pdfio_stream_t *st, double r, double g, double b);

Parameters

st	Stream
r	Red value (0.0 to 1.0)
g	Green value (0.0 to 1.0)
b	Blue value (0.0 to 1.0)

Return Value

true on success, false on failure

pdfioContentSetStrokeColorSpace

Set the stroke color space.

bool pdfioContentSetStrokeColorSpace(pdfio_stream_t *st, const char *name);

Parameters

st	Stream
name	Color space name

Return Value

true on success, false on failure

pdfioContentSetTextCharacterSpacing

Set the spacing between characters.

bool pdfioContentSetTextCharacterSpacing(pdfio_stream_t *st, double spacing);

Parameters

st	Stream
spacing	Character spacing

Return Value

true on success, false on failure

pdfioContentSetTextFont

Set the text font and size.

bool pdfioContentSetTextFont(pdfio_stream_t *st, const char *name, double size);

Parameters

st	Stream
name	Font name
size	Font size

Return Value

true on success, false on failure

pdfioContentSetTextLeading

Set text leading (line height) value.

bool pdfioContentSetTextLeading(pdfio_stream_t *st, double leading);

Parameters

st	Stream
leading	Leading (line height) value

Return Value

true on success, false on failure

pdfioContentSetTextMatrix

Set the text transform matrix.

bool pdfioContentSetTextMatrix(pdfio_stream_t *st, pdfio_matrix_t m);

Parameters

st	Stream
m	Transform matrix

Return Value

true on success, false on failure

pdfioContentSetTextRenderingMode

Set the text rendering mode.

bool pdfioContentSetTextRenderingMode(pdfio_stream_t *st, pdfio_textrendering_t mode);

Parameters

st	Stream
mode	Text rendering mode

Return Value

true on success, false on failure

pdfioContentSetTextRise

Set the text baseline offset.

bool pdfioContentSetTextRise(pdfio_stream_t *st, double rise);

Parameters

st	Stream
rise	Y offset

Return Value

true on success, false on failure

pdfioContentSetTextWordSpacing

Set the inter-word spacing.

bool pdfioContentSetTextWordSpacing(pdfio_stream_t *st, double spacing);

Parameters

st	Stream
spacing	Spacing between words

Return Value

true on success, false on failure

pdfioContentSetTextXScaling

Set the horizontal scaling value.

bool pdfioContentSetTextXScaling(pdfio_stream_t *st, double percent);

Parameters

st	Stream
percent	Horizontal scaling in percent

Return Value

true on success, false on failure

pdfioContentStroke

Stroke the current path.

bool pdfioContentStroke(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioContentTextMoveLine

Move to the next line and offset.

bool pdfioContentTextMoveLine(pdfio_stream_t *st, double tx, double ty);

Parameters

st	Stream
tx	X offset
ty	Y offset

Return Value

true on success, false on failure

pdfioContentTextMoveTo

Offset within the current line.

bool pdfioContentTextMoveTo(pdfio_stream_t *st, double tx, double ty);

Parameters

st	Stream
tx	X offset
ty	Y offset

Return Value

true on success, false on failure

pdfioContentTextNextLine

Move to the next line.

bool pdfioContentTextNextLine(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioContentTextShow

Show text.

bool pdfioContentTextShow(pdfio_stream_t *st, const char *s, bool new_line);

Parameters

st	Stream
s	String to show
new_line	Advance to the next line afterwards

Return Value

true on success, false on failure

pdfioContentTextShowJustified

Show justified text.

bool pdfioContentTextShowJustified(pdfio_stream_t *st, size_t num_fragments, const double *offsets, const char *const *fragments);

Parameters

st	Stream
num_fragments	Number of text fragments
offsets	Text offsets before fragments
fragments	Text fragments

Return Value

true on success, false on failure

pdfioDictCopy

Copy a dictionary to a PDF file.

pdfio_dict_t *pdfioDictCopy(pdfio_file_t *pdf, pdfio_dict_t *dict);

Parameters

pdf	PDF file
dict	Original dictionary

Return Value

New dictionary

pdfioDictCreate

Create a dictionary to hold key/value pairs.

pdfio_dict_t *pdfioDictCreate(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

New dictionary

pdfioDictGetArray

Get a key array value from a dictionary.

pdfio_array_t *pdfioDictGetArray(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value

pdfioDictGetBinary

Get a key binary string value from a dictionary.

unsigned char *pdfioDictGetBinary(pdfio_dict_t *dict, const char *key, size_t *length);

Parameters

dict	Dictionary
key	Key
length	Length of value

Return Value

Value

pdfioDictGetBoolean

Get a key boolean value from a dictionary.

bool pdfioDictGetBoolean(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value

pdfioDictGetDict

Get a key dictionary value from a dictionary.

pdfio_dict_t *pdfioDictGetDict(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value

pdfioDictGetName

Get a key name value from a dictionary.

const char *pdfioDictGetName(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value

pdfioDictGetNumber

Get a key number value from a dictionary.

double pdfioDictGetNumber(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value

pdfioDictGetObject

Get a key indirect object value from a dictionary.

pdfio_obj_t *pdfioDictGetObject(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value

pdfioDictGetRect

Get a key rectangle value from a dictionary.

pdfio_rect_t *pdfioDictGetRect(pdfio_dict_t *dict, const char *key, pdfio_rect_t *rect);

Parameters

dict	Dictionary
key	Key
rect	Rectangle

Return Value

Rectangle

pdfioDictGetString

Get a key string value from a dictionary.

const char *pdfioDictGetString(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value

pdfioDictGetType

Get a key value type from a dictionary.

pdfio_valtype_t pdfioDictGetType(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

Value type

pdfioDictSetArray

Set a key array in a dictionary.

bool pdfioDictSetArray(pdfio_dict_t *dict, const char *key, pdfio_array_t *value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetBinary

Set a key binary string in a dictionary.

bool pdfioDictSetBinary(pdfio_dict_t *dict, const char *key, unsigned char *value, size_t valuelen);

Parameters

dict	Dictionary
key	Key
value	Value
valuelen	Length of value

Return Value

true on success, false on failure

pdfioDictSetBoolean

Set a key boolean in a dictionary.

bool pdfioDictSetBoolean(pdfio_dict_t *dict, const char *key, bool value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetDict

Set a key dictionary in a dictionary.

bool pdfioDictSetDict(pdfio_dict_t *dict, const char *key, pdfio_dict_t *value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetName

Set a key name in a dictionary.

bool pdfioDictSetName(pdfio_dict_t *dict, const char *key, const char *value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetNull

Set a key null in a dictionary.

bool pdfioDictSetNull(pdfio_dict_t *dict, const char *key);

Parameters

dict	Dictionary
key	Key

Return Value

true on success, false on failure

pdfioDictSetNumber

Set a key number in a dictionary.

bool pdfioDictSetNumber(pdfio_dict_t *dict, const char *key, double value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetObject

Set a key indirect object reference in a dictionary.

bool pdfioDictSetObject(pdfio_dict_t *dict, const char *key, pdfio_obj_t *value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetRect

Set a key rectangle in a dictionary.

bool pdfioDictSetRect(pdfio_dict_t *dict, const char *key, pdfio_rect_t *value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetString

Set a key literal string in a dictionary.

bool pdfioDictSetString(pdfio_dict_t *dict, const char *key, const char *value);

Parameters

dict	Dictionary
key	Key
value	Value

Return Value

true on success, false on failure

pdfioDictSetStringf

Set a key formatted string in a dictionary.

bool pdfioDictSetStringf(pdfio_dict_t *dict, const char *key, const char *format, ...);

Parameters

dict	Dictionary
key	Key
format	printf-style format string
...	Additional arguments as needed

Return Value

true on success, false on failure

pdfioFileClose

Close a PDF file and free all memory used for it.

bool pdfioFileClose(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

true on success and false on failure

pdfioFileCreate

Create a PDF file.

pdfio_file_t *pdfioFileCreate(const char *filename, const char *version, pdfio_rect_t *media_box, pdfio_rect_t *crop_box, pdfio_error_cb_t error_cb, void *error_data);

Parameters

filename	Filename
version	PDF version number or NULL for default (2.0)
media_box	Default MediaBox for pages
crop_box	Default CropBox for pages
error_cb	Error callback or NULL for default
error_data	Error callback data, if any

Return Value

PDF file or NULL on error

pdfioFileCreateFontObject

Add a font object to a PDF file.

pdfio_obj_t *pdfioFileCreateFontObject(pdfio_file_t *pdf, const char *filename);

Parameters

pdf	PDF file
filename	Filename

Return Value

Object

pdfioFileCreateICCProfileObject

Add an ICC profile object to a PDF file.

pdfio_obj_t *pdfioFileCreateICCProfileObject(pdfio_file_t *pdf, const char *filename);

Parameters

pdf	PDF file
filename	Filename

Return Value

Object

pdfioFileCreateImageObject

Add an image object to a PDF file.

pdfio_obj_t *pdfioFileCreateImageObject(pdfio_file_t *pdf, const char *filename, bool interpolate);

Parameters

pdf	PDF file
filename	Filename
interpolate	Interpolate image data?

Return Value

Object

Discussion

Currently only GIF, JPEG, and PNG files are supported.

pdfioFileCreateObject

Create a new object in a PDF file.

pdfio_obj_t *pdfioFileCreateObject(pdfio_file_t *pdf, pdfio_dict_t *dict);

Parameters

pdf	PDF file
dict	Object dictionary

Return Value

New object

pdfioFileCreatePage

Create a page in a PDF file.

pdfio_stream_t *pdfioFileCreatePage(pdfio_file_t *pdf, pdfio_dict_t *dict);

Parameters

pdf	PDF file
dict	Page dictionary

Return Value

Contents stream

pdfioFileFindObject

Find an object using its object number.

pdfio_obj_t *pdfioFileFindObject(pdfio_file_t *pdf, size_t number);

Parameters

pdf	PDF file
number	Object number (1 to N)

Return Value

Object or NULL if not found

Discussion

This differs from pdfioFileGetObject which takes an index into the list of objects while this function takes the object number.

pdfioFileGetID

Get the PDF file's ID strings.

pdfio_array_t *pdfioFileGetID(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

Array with binary strings

pdfioFileGetName

Get a PDF's filename.

const char *pdfioFileGetName(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

Filename

pdfioFileGetNumObjects

Get the number of objects in a PDF file.

size_t pdfioFileGetNumObjects(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

Number of objects

pdfioFileGetNumPages

Get the number of pages in a PDF file.

size_t pdfioFileGetNumPages(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

Number of pages

pdfioFileGetObject

Get an object from a PDF file.

pdfio_obj_t *pdfioFileGetObject(pdfio_file_t *pdf, size_t n);

Parameters

pdf	PDF file
n	Object index (starting at 0)

Return Value

Object

pdfioFileGetPage

Get a page object from a PDF file.

pdfio_obj_t *pdfioFileGetPage(pdfio_file_t *pdf, size_t n);

Parameters

pdf	PDF file
n	Page index (starting at 0)

Return Value

Object

pdfioFileGetVersion

Get the PDF version number for a PDF file.

const char *pdfioFileGetVersion(pdfio_file_t *pdf);

Parameters

pdf	PDF file

Return Value

Version number or NULL

pdfioFileOpen

Open a PDF file for reading.

pdfio_file_t *pdfioFileOpen(const char *filename, pdfio_error_cb_t error_cb, void *error_data);

Parameters

filename	Filename
error_cb	Error callback or NULL for default
error_data	Error callback data, if any

Return Value

PDF file

pdfioImageGetHeight

Get the height of an image object.

double pdfioImageGetHeight(pdfio_obj_t *obj);

Parameters

obj	Image object

Return Value

Height in lines

pdfioImageGetWidth

Get the width of an image object.

double pdfioImageGetWidth(pdfio_obj_t *obj);

Parameters

obj	Image object

Return Value

Width in columns

pdfioObjClose

Close an object, writing any data as needed to the PDF file.

bool pdfioObjClose(pdfio_obj_t *obj);

Parameters

obj	Object

Return Value

true on success, false on failure

pdfioObjCopy

Copy an object to another PDF file.

pdfio_obj_t *pdfioObjCopy(pdfio_file_t *pdf, pdfio_obj_t *srcobj);

Parameters

pdf	PDF file
srcobj	Object to copy

Return Value

New object or NULL on error

pdfioObjCreateStream

Create an object (data) stream for writing.

pdfio_stream_t *pdfioObjCreateStream(pdfio_obj_t *obj, pdfio_filter_t filter);

Parameters

obj	Object
filter	Type of compression to apply

Return Value

Stream or NULL on error

pdfioObjGetArray

Get the array associated with an object.

pdfio_array_t *pdfioObjGetArray(pdfio_obj_t *obj);

Parameters

obj	Object

Return Value

Array or NULL on error

pdfioObjGetDict

Get the dictionary associated with an object.

pdfio_dict_t *pdfioObjGetDict(pdfio_obj_t *obj);

Parameters

obj	Object

Return Value

Dictionary or NULL on error

pdfioObjGetGeneration

Get the object's generation number.

unsigned short pdfioObjGetGeneration(pdfio_obj_t *obj);

Parameters

obj	Object

Return Value

Generation number (0 to 65535)

pdfioObjGetLength

Get the length of the object's (data) stream.

size_t pdfioObjGetLength(pdfio_obj_t *obj);

Parameters

obj	Object

Return Value

Length in bytes or 0 for none

pdfioObjGetNumber

Get the object's number.

size_t pdfioObjGetNumber(pdfio_obj_t *obj);

Parameters

obj	Object

Return Value

Object number (1 to 9999999999)

pdfioObjGetType

Get an object's type.

const char *pdfioObjGetType(pdfio_obj_t *obj);

Parameters

obj	Object

Return Value

Object type

pdfioObjOpenStream

Open an object's (data) stream for reading.

pdfio_stream_t *pdfioObjOpenStream(pdfio_obj_t *obj, bool decode);

Parameters

obj	Object
decode	Decode/decompress data?

Return Value

Stream or NULL on error

pdfioPageCopy

Copy a page to a PDF file.

bool pdfioPageCopy(pdfio_file_t *pdf, pdfio_obj_t *srcpage);

Parameters

pdf	PDF file
srcpage	Source page

Return Value

true on success, false on failure

pdfioPageDictAddCalibratedColorSpace

Add a calibrated color space to the page dictionary.

bool pdfioPageDictAddCalibratedColorSpace(pdfio_dict_t *dict, const char *name, size_t num_colors, const double *white_point, double gamma);

Parameters

dict	Page dictionary
name	Color space name
num_colors	Number of color components
white_point	CIE XYZ white point
gamma	Gamma value

Return Value

true on success, false on failure

pdfioPageDictAddFont

Add a font object to the page dictionary.

bool pdfioPageDictAddFont(pdfio_dict_t *dict, const char *name, pdfio_obj_t *obj);

Parameters

dict	Page dictionary
name	Font name
obj	Font object

Return Value

true on success, false on failure

pdfioPageDictAddICCColorSpace

Add an ICC color space to the page dictionary.

bool pdfioPageDictAddICCColorSpace(pdfio_dict_t *dict, const char *name, pdfio_obj_t *obj);

Parameters

dict	Page dictionary
name	Color space name
obj	ICC profile object

Return Value

true on success, false on failure

pdfioPageDictAddImage

Add an image object to the page dictionary.

bool pdfioPageDictAddImage(pdfio_dict_t *dict, const char *name, pdfio_obj_t *obj);

Parameters

dict	Page dictionary
name	Image name
obj	Image object

Return Value

true on success, false on failure

pdfioStreamClose

Close a (data) stream in a PDF file.

bool pdfioStreamClose(pdfio_stream_t *st);

Parameters

st	Stream

Return Value

true on success, false on failure

pdfioStreamConsume

Consume bytes from the stream.

bool pdfioStreamConsume(pdfio_stream_t *st, size_t bytes);

Parameters

st	Stream
bytes	Number of bytes to consume

Return Value

true on success, false on EOF

pdfioStreamGetToken

Read a single PDF token from a stream.

bool pdfioStreamGetToken(pdfio_stream_t *st, char *buffer, size_t bufsize);

Parameters

st	Stream
buffer	String buffer
bufsize	Size of string buffer

Return Value

true on success, false on EOF

pdfioStreamPeek

Peek at data in a stream.

ssize_t pdfioStreamPeek(pdfio_stream_t *st, void *buffer, size_t bytes);

Parameters

st	Stream
buffer	Buffer
bytes	Size of buffer

Return Value

Bytes returned or -1 on error

pdfioStreamPrintf

Write a formatted string to a stream.

bool pdfioStreamPrintf(pdfio_stream_t *st, const char *format, ...);

Parameters

st	Stream
format	printf-style format string
...	Additional arguments as needed

Return Value

true on success, false on failure

pdfioStreamPuts

Write a literal string to a stream.

bool pdfioStreamPuts(pdfio_stream_t *st, const char *s);

Parameters

st	Stream
s	Literal string

Return Value

true on success, false on failure

pdfioStreamRead

Read data from a stream.

ssize_t pdfioStreamRead(pdfio_stream_t *st, void *buffer, size_t bytes);

Parameters

st	Stream
buffer	Buffer
bytes	Bytes to read

Return Value

Number of bytes read or -1 on error

pdfioStreamWrite

Write data to a stream.

bool pdfioStreamWrite(pdfio_stream_t *st, const void *buffer, size_t bytes);

Parameters

st	Stream
buffer	Data to write
bytes	Number of bytes to write

Return Value

true on success or false on failure

pdfioStringCreate

Create a durable literal string.

char *pdfioStringCreate(pdfio_file_t *pdf, const char *s);

Parameters

pdf	PDF file
s	Nul-terminated string

Return Value

Durable string pointer or NULL on error

Discussion

This function creates a literal string associated with the PDF file "pwg". The "s" string points to a nul-terminated C string.

NULL is returned on error, otherwise a char * that is valid until pdfioFileClose is called.

pdfioStringCreatef

Create a durable formatted string.

char *pdfioStringCreatef(pdfio_file_t *pdf, const char *format, ...);

Parameters

pdf	PDF file
format	printf-style format string
...	Additional args as needed

Return Value

Durable string pointer or NULL on error

Discussion

This function creates a formatted string associated with the PDF file "pwg". The "format" string contains printf-style format characters.

NULL is returned on error, otherwise a char * that is valid until pdfioFileClose is called.

Data Types

pdf_value_t

PDF value of any type

typedef struct _pdfio_value_s pdf_value_t;

pdfio_array_t

Array of PDF values

typedef struct _pdfio_array_s pdfio_array_t;

pdfio_dict_t

Key/value dictionary

typedef struct _pdfio_dict_s pdfio_dict_t;

pdfio_error_cb_t

Error callback

typedef bool (*pdfio_error_cb_t)(pdfio_file_t *pdf, const char *message, void *data);

pdfio_file_t

PDF file

typedef struct _pdfio_file_s pdfio_file_t;

pdfio_filter_t

Compression/decompression filters for streams

typedef enum pdfio_filter_e pdfio_filter_t;

pdfio_obj_t

Numbered object in PDF file

typedef struct _pdfio_obj_s pdfio_obj_t;

pdfio_rect_t

PDF rectangle

typedef struct pdfio_rect_s pdfio_rect_t;

pdfio_stream_t

Object data stream in PDF file

typedef struct _pdfio_stream_s pdfio_stream_t;

pdfio_valtype_t

PDF value types

typedef enum pdfio_valtype_e pdfio_valtype_t;

Structures

pdfio_rect_s

PDF rectangle

struct pdfio_rect_s {
    double x1;
    double x2;
    double y1;
    double y2;
};

Members

x1	Lower-left X coordinate
x2	Upper-right X coordinate
y1	Lower-left Y coordinate
y2	Upper-right Y coordinate

Constants

pdfio_filter_e

Compression/decompression filters for streams

Constants

PDFIO_FILTER_ASCII85	ASCII85Decode filter (reading only)
PDFIO_FILTER_ASCIIHEX	ASCIIHexDecode filter (reading only)
PDFIO_FILTER_CCITTFAX	CCITTFaxDecode filter
PDFIO_FILTER_CRYPT	Encryption filter
PDFIO_FILTER_DCT	DCTDecode (JPEG) filter
PDFIO_FILTER_FLATE	FlateDecode filter
PDFIO_FILTER_JBIG2	JBIG2Decode filter
PDFIO_FILTER_JPX	JPXDecode filter (reading only)
PDFIO_FILTER_LZW	LZWDecode filter (reading only)
PDFIO_FILTER_NONE	No filter
PDFIO_FILTER_RUNLENGTH	RunLengthDecode filter (reading only)

pdfio_valtype_e

PDF value types

Constants

PDFIO_VALTYPE_ARRAY	Array
PDFIO_VALTYPE_BINARY	Binary data
PDFIO_VALTYPE_BOOLEAN	Boolean
PDFIO_VALTYPE_DATE	Date/time
PDFIO_VALTYPE_DICT	Dictionary
PDFIO_VALTYPE_INDIRECT	Indirect object (N G obj)
PDFIO_VALTYPE_NAME	Name
PDFIO_VALTYPE_NONE	No value, not set
PDFIO_VALTYPE_NULL	Null object
PDFIO_VALTYPE_NUMBER	Number (integer or real)
PDFIO_VALTYPE_STRING	String