PDFio Programming Manual v0.1
Michael R Sweet
Copyright © 2021 by Michael R Sweet
Michael R Sweet
Copyright © 2021 by Michael R Sweet
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.
PDFio is Copyright © 2021 by Michael R Sweet and is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software. See the files "LICENSE" and "NOTICE" for more information.
PDFio requires the following to build the software:
A C99 compiler such as Clang, GCC, or MS Visual C
A POSIX-compliant make program
ZLIB (https://www.zlib.net) 1.0 or higher
IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
PDFio comes with a portable makefile that will work on any POSIX-compliant system with ZLIB installed. To make it, run:
make all
To test it, run:
make test
To install it, run:
make install
If you want a shared library, run:
make all-shared
make install-shared
The default installation location is "/usr/local". Pass the prefix variable to make to install it to another location:
make install prefix=/some/other/directory
The makefile installs the pdfio header to "${prefix}/include", the library to "${prefix}/lib", the pkg-config file to "${prefix}/lib/pkgconfig", the man page to "${prefix}/share/man/man3", and the documentation to "${prefix}/share/doc/pdfio".
The makefile supports the following variables that can be specified in the make command or as environment variables:
AR: the library archiver (default "ar")
ARFLAGS: options for the library archiver (default "cr")
CC: the C compiler (default "cc")
CFLAGS: options for the C compiler (default "")
CODESIGN_IDENTITY: the identity to use when code signing the shared library on macOS (default "Developer ID")
COMMONFLAGS: options for the C compiler and linker (typically architecture and optimization options, default is "-Os -g")
CPPFLAGS: options for the C preprocessor (default "")
DESTDIR" and "DSTROOT: specifies a root directory when installing (default is "", specify only one)
DSOFLAGS: options for the C compiler when linking the shared library (default "")
LDFLAGS: options for the C compiler when linking the test programs (default "")
LIBS: library options when linking the test programs (default "-lz")
RANLIB: program that generates a table-of-contents in a library (default "ranlib")
prefix: specifies the installation directory (default "/usr/local")
Note: I haven't yet added this...
The Visual Studio solution ("pdfio.sln") is provided for Windows developers generates both a static library and DLL.
There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which generates a static library that will be installed under "/usr/local" with:
sudo xcodebuild install
You can reproduce this with the makefile using:
sudo make 'COMMONFLAGS="-Os -mmacosx-version-min=10.14 -arch x86_64 -arch arm64"' install
PDFio can be detected using the pkg-config command, for example:
if pkg-config --exists pdfio; then
...
fi
In a makefile you can add the necessary compiler and linker options with:
CFLAGS += `pkg-config --cflags pdfio`
LIBS += `pkg-config --libs pdfio`
PDFio provides a primary header file that is always used:
#include <pdfio.h>
PDFio also provides content helper functions that are defined in a separate header file:
#include <pdfio-content.h>
PDFio exposes several types:
pdfio_file_t: A PDF file (for reading or writing)
pdfio_array_t: An array of values
pdfio_dict_t: A dictionary of key/value pairs in a PDF file, object, etc.
pdfio_obj_t: An object in a PDF file
pdfio_stream_t: An object stream
Add an array value to an array.
bool pdfioArrayAppendArray(pdfio_array_t *a, pdfio_array_t *value);
| a | Array |
|---|---|
| value | Value |
true on success, false on failure
Add a binary string value to an array.
bool pdfioArrayAppendBinary(pdfio_array_t *a, const unsigned char *value, size_t valuelen);
| a | Array |
|---|---|
| value | Value |
| valuelen | Length of value |
true on success, false on failure
Add a boolean value to an array.
bool pdfioArrayAppendBoolean(pdfio_array_t *a, bool value);
| a | Array |
|---|---|
| value | Value |
true on success, false on failure
Add a dictionary to an array.
bool pdfioArrayAppendDict(pdfio_array_t *a, pdfio_dict_t *value);
| a | Array |
|---|---|
| value | Value |
true on success, false on failure
Add a name to an array.
bool pdfioArrayAppendName(pdfio_array_t *a, const char *value);
| a | Array |
|---|---|
| value | Value |
true on success, false on failure
Add a number to an array.
bool pdfioArrayAppendNumber(pdfio_array_t *a, double value);
| a | Array |
|---|---|
| value | Value |
true on success, false on failure
Add an indirect object reference to an array.
bool pdfioArrayAppendObj(pdfio_array_t *a, pdfio_obj_t *value);
| a | Array |
|---|---|
| value | Value |
true on success, false on failure
Add a string to an array.
bool pdfioArrayAppendString(pdfio_array_t *a, const char *value);
| a | Array |
|---|---|
| value | Value |
true on success, false on failure
Copy an array.
pdfio_array_t *pdfioArrayCopy(pdfio_file_t *pdf, pdfio_array_t *a);
| PDF file | |
| a | Original array |
New array or NULL on error
Create an empty array.
pdfio_array_t *pdfioArrayCreate(pdfio_file_t *pdf);
| PDF file |
New array or NULL on error
Create a calibrated color space array using a CIE XYZ transform matrix.
pdfio_array_t *pdfioArrayCreateCalibratedColorFromMatrix(pdfio_file_t *pdf, size_t num_colors, double gamma, const double matrix[3][3], const double white_point[3]);
| PDF file | |
| num_colors | Number of colors (1 or 3) |
| gamma | Gamma value |
| matrix[3][3] | XYZ transform |
| white_point[3] | White point |
Color space array
Create a calibrated color sapce array using CIE xy primary chromacities.
pdfio_array_t *pdfioArrayCreateCalibratedColorFromPrimaries(pdfio_file_t *pdf, size_t num_colors, double gamma, double wx, double wy, double rx, double ry, double gx, double gy, double bx, double by);
| PDF file | |
| num_colors | Number of colors (1 or 3) |
| gamma | Gama value |
| wx | White point X chromacity |
| wy | White point Y chromacity |
| rx | Red X chromacity |
| ry | Red Y chromacity |
| gx | Green X chromacity |
| gy | Green Y chromacity |
| bx | Blue X chromacity |
| by | Blue Y chromacity |
Color space array
Create an ICC-based color space array.
pdfio_array_t *pdfioArrayCreateICCBasedColor(pdfio_file_t *pdf, pdfio_obj_t *icc_object);
| PDF file | |
| icc_object | ICC profile object |
Color array
Create an indexed color space array.
pdfio_array_t *pdfioArrayCreateIndexedColor(pdfio_file_t *pdf, size_t num_colors, const unsigned char *colors);
| PDF file | |
| num_colors | Number of colors |
| colors | RGB values for colors |
Color array
Get an array value from an array.
pdfio_array_t *pdfioArrayGetArray(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value
Get a binary string value from an array.
unsigned char *pdfioArrayGetBinary(pdfio_array_t *a, size_t n, size_t *length);
| a | Array |
|---|---|
| n | Index |
| length | Length of string |
Value
Get a boolean value from an array.
bool pdfioArrayGetBoolean(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value
Get a dictionary value from an array.
pdfio_dict_t *pdfioArrayGetDict(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value
Get a name value from an array.
const char *pdfioArrayGetName(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value
Get a number from an array.
double pdfioArrayGetNumber(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value
Get an indirect object reference from an array.
pdfio_obj_t *pdfioArrayGetObj(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value
Get the length of an array.
size_t pdfioArrayGetSize(pdfio_array_t *a);
| a | Array |
|---|
Length of array
Get a string value from an array.
const char *pdfioArrayGetString(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value
Get a value type from an array.
pdfio_valtype_t pdfioArrayGetType(pdfio_array_t *a, size_t n);
| a | Array |
|---|---|
| n | Index |
Value type
Clip output to the current path.
bool pdfioContentClip(pdfio_stream_t *st, bool even_odd);
| st | Stream |
|---|---|
| even_odd | Even/odd fill vs. non-zero winding rule |
true on success, false on failure
Draw an image object.
bool pdfioContentDrawImage(pdfio_stream_t *st, const char *name, double x, double y, double width, double height);
| st | Stream |
|---|---|
| name | Image name |
| x | X offset of image |
| y | Y offset of image |
| width | Width of image |
| height | Height of image |
true on success, false on failure
The object name must be part of the page dictionary resources, typically
using the pdfioPageDictAddImage function.
Fill the current path.
bool pdfioContentFill(pdfio_stream_t *st, bool even_odd);
| st | Stream |
|---|---|
| even_odd | Even/odd fill vs. non-zero winding rule |
true on success, false on failure
Fill and stroke the current path.
bool pdfioContentFillAndStroke(pdfio_stream_t *st, bool even_odd);
| st | Stream |
|---|---|
| even_odd | Even/odd fill vs. non-zero winding |
true on success, false on failure
Concatenate a matrix to the current graphics state.
bool pdfioContentMatrixConcat(pdfio_stream_t *st, pdfio_matrix_t m);
| st | Stream |
|---|---|
| m | Transform matrix |
true on success, false on failure
Rotate the current transform matrix.
bool pdfioContentMatrixRotate(pdfio_stream_t *st, double degrees);
| st | Stream |
|---|---|
| degrees | Rotation angle in degrees counter-clockwise |
true on success, false on failure
Scale the current transform matrix.
bool pdfioContentMatrixScale(pdfio_stream_t *st, double sx, double sy);
| st | Stream |
|---|---|
| sx | X scale |
| sy | Y scale |
true on success, false on failure
Translate the current transform matrix.
bool pdfioContentMatrixTranslate(pdfio_stream_t *st, double tx, double ty);
| st | Stream |
|---|---|
| tx | X offset |
| ty | Y offset |
true on success, false on failure
Close the current path.
bool pdfioContentPathClose(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
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);
| 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 |
true on success, false on failure
Add a Bezier curve with an initial control point.
bool pdfioContentPathCurve13(pdfio_stream_t *st, double x1, double y1, double x3, double y3);
| st | Stream |
|---|---|
| x1 | X position 1 |
| y1 | Y position 1 |
| x3 | X position 3 |
| y3 | Y position 3 |
true on success, false on failure
Add a Bezier curve with a trailing control point.
bool pdfioContentPathCurve23(pdfio_stream_t *st, double x2, double y2, double x3, double y3);
| st | Stream |
|---|---|
| x2 | X position 2 |
| y2 | Y position 2 |
| x3 | X position 3 |
| y3 | Y position 3 |
true on success, false on failure
Add a straight line to the current path.
bool pdfioContentPathLineTo(pdfio_stream_t *st, double x, double y);
| st | Stream |
|---|---|
| x | X position |
| y | Y position |
true on success, false on failure
Start a new subpath.
bool pdfioContentPathMoveTo(pdfio_stream_t *st, double x, double y);
| st | Stream |
|---|---|
| x | X position |
| y | Y position |
true on success, false on failure
Add a rectangle to the current path.
bool pdfioContentPathRect(pdfio_stream_t *st, double x, double y, double width, double height);
| st | Stream |
|---|---|
| x | X offset |
| y | Y offset |
| width | Width |
| height | Height |
true on success, false on failure
Restore a previous graphics state.
bool pdfioContentRestore(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
Save the current graphics state.
bool pdfioContentSave(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
Set the stroke pattern.
bool pdfioContentSetDashPattern(pdfio_stream_t *st, int phase, int on, int off);
| st | Stream |
|---|---|
| phase | Phase (offset within pattern) |
| on | On length |
| off | Off length |
true on success, false on failure
Set device CMYK fill color.
bool pdfioContentSetFillColorDeviceCMYK(pdfio_stream_t *st, double c, double m, double y, double k);
| 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) |
true on success, false on failure
Set the device gray fill color.
bool pdfioContentSetFillColorDeviceGray(pdfio_stream_t *st, double g);
| st | Stream |
|---|---|
| g | Gray value (0.0 to 1.0) |
true on success, false on failure
Set the device RGB fill color.
bool pdfioContentSetFillColorDeviceRGB(pdfio_stream_t *st, double r, double g, double b);
| 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) |
true on success, false on failure
Set the calibrated gray fill color.
bool pdfioContentSetFillColorGray(pdfio_stream_t *st, double g);
| st | Stream |
|---|---|
| g | Gray value (0.0 to 1.0) |
true on success, false on failure
Set the calibrated RGB fill color.
bool pdfioContentSetFillColorRGB(pdfio_stream_t *st, double r, double g, double b);
| 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) |
true on success, false on failure
Set the fill colorspace.
bool pdfioContentSetFillColorSpace(pdfio_stream_t *st, const char *name);
| st | Stream |
|---|---|
| name | Color space name |
true on success, false on failure
Set the flatness tolerance.
bool pdfioContentSetFlatness(pdfio_stream_t *st, double flatness);
| st | Stream |
|---|---|
| flatness | Flatness value (0.0 to 100.0) |
true on success, false on failure
Set the line ends style.
bool pdfioContentSetLineCap(pdfio_stream_t *st, pdfio_linecap_t lc);
| st | Stream |
|---|---|
| lc | Line cap value |
true on success, false on failure
Set the line joining style.
bool pdfioContentSetLineJoin(pdfio_stream_t *st, pdfio_linejoin_t lj);
| st | Stream |
|---|---|
| lj | Line join value |
true on success, false on failure
Set the line width.
bool pdfioContentSetLineWidth(pdfio_stream_t *st, double width);
| st | Stream |
|---|---|
| width | Line width value |
true on success, false on failure
Set the miter limit.
bool pdfioContentSetMiterLimit(pdfio_stream_t *st, double limit);
| st | Stream |
|---|---|
| limit | Miter limit value |
true on success, false on failure
Set the device CMYK stroke color.
bool pdfioContentSetStrokeColorDeviceCMYK(pdfio_stream_t *st, double c, double m, double y, double k);
| 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) |
true on success, false on failure
Set the device gray stroke color.
bool pdfioContentSetStrokeColorDeviceGray(pdfio_stream_t *st, double g);
| st | Stream |
|---|---|
| g | Gray value (0.0 to 1.0) |
true on success, false on failure
Set the device RGB stroke color.
bool pdfioContentSetStrokeColorDeviceRGB(pdfio_stream_t *st, double r, double g, double b);
| 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) |
true on success, false on failure
Set the calibrated gray stroke color.
bool pdfioContentSetStrokeColorGray(pdfio_stream_t *st, double g);
| st | Stream |
|---|---|
| g | Gray value (0.0 to 1.0) |
true on success, false on failure
Set the calibrated RGB stroke color.
bool pdfioContentSetStrokeColorRGB(pdfio_stream_t *st, double r, double g, double b);
| 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) |
true on success, false on failure
Set the stroke color space.
bool pdfioContentSetStrokeColorSpace(pdfio_stream_t *st, const char *name);
| st | Stream |
|---|---|
| name | Color space name |
true on success, false on failure
Set the spacing between characters.
bool pdfioContentSetTextCharacterSpacing(pdfio_stream_t *st, double spacing);
| st | Stream |
|---|---|
| spacing | Character spacing |
true on success, false on failure
Set the text font and size.
bool pdfioContentSetTextFont(pdfio_stream_t *st, const char *name, double size);
| st | Stream |
|---|---|
| name | Font name |
| size | Font size |
true on success, false on failure
Set text leading (line height) value.
bool pdfioContentSetTextLeading(pdfio_stream_t *st, double leading);
| st | Stream |
|---|---|
| leading | Leading (line height) value |
true on success, false on failure
Set the text transform matrix.
bool pdfioContentSetTextMatrix(pdfio_stream_t *st, pdfio_matrix_t m);
| st | Stream |
|---|---|
| m | Transform matrix |
true on success, false on failure
Set the text rendering mode.
bool pdfioContentSetTextRenderingMode(pdfio_stream_t *st, pdfio_textrendering_t mode);
| st | Stream |
|---|---|
| mode | Text rendering mode |
true on success, false on failure
Set the text baseline offset.
bool pdfioContentSetTextRise(pdfio_stream_t *st, double rise);
| st | Stream |
|---|---|
| rise | Y offset |
true on success, false on failure
Set the inter-word spacing.
bool pdfioContentSetTextWordSpacing(pdfio_stream_t *st, double spacing);
| st | Stream |
|---|---|
| spacing | Spacing between words |
true on success, false on failure
Set the horizontal scaling value.
bool pdfioContentSetTextXScaling(pdfio_stream_t *st, double percent);
| st | Stream |
|---|---|
| percent | Horizontal scaling in percent |
true on success, false on failure
Stroke the current path.
bool pdfioContentStroke(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
Begin a text block.
bool pdfioContentTextBegin(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
End a text block.
bool pdfioContentTextEnd(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
Move to the next line and offset.
bool pdfioContentTextMoveLine(pdfio_stream_t *st, double tx, double ty);
| st | Stream |
|---|---|
| tx | X offset |
| ty | Y offset |
true on success, false on failure
Offset within the current line.
bool pdfioContentTextMoveTo(pdfio_stream_t *st, double tx, double ty);
| st | Stream |
|---|---|
| tx | X offset |
| ty | Y offset |
true on success, false on failure
Move to the next line.
bool pdfioContentTextNextLine(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
Show text.
bool pdfioContentTextShow(pdfio_stream_t *st, const char *s);
| st | Stream |
|---|---|
| s | String to show |
true on success, false on failure
Show justified text.
bool pdfioContentTextShowJustified(pdfio_stream_t *st, size_t num_fragments, const double *offsets, const char *const *fragments);
| st | Stream |
|---|---|
| num_fragments | Number of text fragments |
| offsets | Text offsets before fragments |
| fragments | Text fragments |
true on success, false on failure
bool pdfioContentTextShowf(pdfio_stream_t *st, const char *format, ...);
| st | Stream |
|---|---|
| format | printf-style format string |
| ... | Additional arguments as needed |
Show formatted text.
Copy a dictionary to a PDF file.
pdfio_dict_t *pdfioDictCopy(pdfio_file_t *pdf, pdfio_dict_t *dict);
| PDF file | |
| dict | Original dictionary |
New dictionary
Create a dictionary to hold key/value pairs.
pdfio_dict_t *pdfioDictCreate(pdfio_file_t *pdf);
| PDF file |
New dictionary
Get a key array value from a dictionary.
pdfio_array_t *pdfioDictGetArray(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value
Get a key binary string value from a dictionary.
unsigned char *pdfioDictGetBinary(pdfio_dict_t *dict, const char *key, size_t *length);
| dict | Dictionary |
|---|---|
| key | Key |
| length | Length of value |
Value
Get a key boolean value from a dictionary.
bool pdfioDictGetBoolean(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value
Get a key dictionary value from a dictionary.
pdfio_dict_t *pdfioDictGetDict(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value
Get a key name value from a dictionary.
const char *pdfioDictGetName(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value
Get a key number value from a dictionary.
double pdfioDictGetNumber(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value
Get a key indirect object value from a dictionary.
pdfio_obj_t *pdfioDictGetObj(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value
Get a key rectangle value from a dictionary.
pdfio_rect_t *pdfioDictGetRect(pdfio_dict_t *dict, const char *key, pdfio_rect_t *rect);
| dict | Dictionary |
|---|---|
| key | Key |
| rect | Rectangle |
Rectangle
Get a key string value from a dictionary.
const char *pdfioDictGetString(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value
Get a key value type from a dictionary.
pdfio_valtype_t pdfioDictGetType(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
Value type
Set a key array in a dictionary.
bool pdfioDictSetArray(pdfio_dict_t *dict, const char *key, pdfio_array_t *value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key binary string in a dictionary.
bool pdfioDictSetBinary(pdfio_dict_t *dict, const char *key, const unsigned char *value, size_t valuelen);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
| valuelen | Length of value |
true on success, false on failure
Set a key boolean in a dictionary.
bool pdfioDictSetBoolean(pdfio_dict_t *dict, const char *key, bool value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key dictionary in a dictionary.
bool pdfioDictSetDict(pdfio_dict_t *dict, const char *key, pdfio_dict_t *value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key name in a dictionary.
bool pdfioDictSetName(pdfio_dict_t *dict, const char *key, const char *value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key null in a dictionary.
bool pdfioDictSetNull(pdfio_dict_t *dict, const char *key);
| dict | Dictionary |
|---|---|
| key | Key |
true on success, false on failure
Set a key number in a dictionary.
bool pdfioDictSetNumber(pdfio_dict_t *dict, const char *key, double value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key indirect object reference in a dictionary.
bool pdfioDictSetObj(pdfio_dict_t *dict, const char *key, pdfio_obj_t *value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key rectangle in a dictionary.
bool pdfioDictSetRect(pdfio_dict_t *dict, const char *key, pdfio_rect_t *value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key literal string in a dictionary.
bool pdfioDictSetString(pdfio_dict_t *dict, const char *key, const char *value);
| dict | Dictionary |
|---|---|
| key | Key |
| value | Value |
true on success, false on failure
Set a key formatted string in a dictionary.
bool pdfioDictSetStringf(pdfio_dict_t *dict, const char *key, const char *format, ...);
| dict | Dictionary |
|---|---|
| key | Key |
| format | printf-style format string |
| ... | Additional arguments as needed |
true on success, false on failure
Close a PDF file and free all memory used for it.
bool pdfioFileClose(pdfio_file_t *pdf);
| PDF file |
true on success and false on failure
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);
| 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 |
PDF file or NULL on error
Create one of the base 14 PDF fonts.
pdfio_obj_t *pdfioFileCreateBaseFontObj(pdfio_file_t *pdf, const char *name);
| PDF file | |
| name | Font name |
Font object
This function creates one of the base 14 PDF fonts. The "name" parameter specifies the font nane:
Courier
Courier-Bold
Courier-BoldItalic
Courier-Italic
Helvetica
Helvetica-Bold
Helvetica-BoldOblique
Helvetica-Oblique
Symbol
Times-Bold
Times-BoldItalic
Times-Italic
Times-Roman
ZapfDingbatsAdd a font object to a PDF file.
pdfio_obj_t *pdfioFileCreateFontObj(pdfio_file_t *pdf, const char *filename, bool unicode);
| PDF file | |
| filename | Filename |
| unicode | Unicode font? |
Font object
Add an ICC profile object to a PDF file.
pdfio_obj_t *pdfioFileCreateICCProfileObj(pdfio_file_t *pdf, const char *filename);
| PDF file | |
| filename | Filename |
Object
Add an image object to a PDF file.
pdfio_obj_t *pdfioFileCreateImageObj(pdfio_file_t *pdf, const char *filename, bool interpolate);
| PDF file | |
| filename | Filename |
| interpolate | Interpolate image data? |
Object
Currently only GIF, JPEG, and PNG files are supported.
Create a new object in a PDF file.
pdfio_obj_t *pdfioFileCreateObj(pdfio_file_t *pdf, pdfio_dict_t *dict);
| PDF file | |
| dict | Object dictionary |
New object
Create a page in a PDF file.
pdfio_stream_t *pdfioFileCreatePage(pdfio_file_t *pdf, pdfio_dict_t *dict);
| PDF file | |
| dict | Page dictionary |
Contents stream
Find an object using its object number.
pdfio_obj_t *pdfioFileFindObj(pdfio_file_t *pdf, size_t number);
| PDF file | |
| number | Object number (1 to N) |
Object or NULL if not found
This differs from pdfioFileGetObj which takes an index into the
list of objects while this function takes the object number.
Get the PDF file's ID strings.
pdfio_array_t *pdfioFileGetID(pdfio_file_t *pdf);
| PDF file |
Array with binary strings
Get a PDF's filename.
const char *pdfioFileGetName(pdfio_file_t *pdf);
| PDF file |
Filename
Get the number of objects in a PDF file.
size_t pdfioFileGetNumObjs(pdfio_file_t *pdf);
| PDF file |
Number of objects
Get the number of pages in a PDF file.
size_t pdfioFileGetNumPages(pdfio_file_t *pdf);
| PDF file |
Number of pages
Get an object from a PDF file.
pdfio_obj_t *pdfioFileGetObj(pdfio_file_t *pdf, size_t n);
| PDF file | |
| n | Object index (starting at 0) |
Object
Get a page object from a PDF file.
pdfio_obj_t *pdfioFileGetPage(pdfio_file_t *pdf, size_t n);
| PDF file | |
| n | Page index (starting at 0) |
Object
Get the PDF version number for a PDF file.
const char *pdfioFileGetVersion(pdfio_file_t *pdf);
| PDF file |
Version number or NULL
Open a PDF file for reading.
pdfio_file_t *pdfioFileOpen(const char *filename, pdfio_error_cb_t error_cb, void *error_data);
| filename | Filename |
|---|---|
| error_cb | Error callback or NULL for default |
| error_data | Error callback data, if any |
PDF file
Get the number of bytes to read for each line.
size_t pdfioImageGetBytesPerLine(pdfio_obj_t *obj);
| obj | Image object |
|---|
Number of bytes per line
Get the height of an image object.
double pdfioImageGetHeight(pdfio_obj_t *obj);
| obj | Image object |
|---|
Height in lines
Get the width of an image object.
double pdfioImageGetWidth(pdfio_obj_t *obj);
| obj | Image object |
|---|
Width in columns
Close an object, writing any data as needed to the PDF file.
bool pdfioObjClose(pdfio_obj_t *obj);
| obj | Object |
|---|
true on success, false on failure
Copy an object to another PDF file.
pdfio_obj_t *pdfioObjCopy(pdfio_file_t *pdf, pdfio_obj_t *srcobj);
| PDF file | |
| srcobj | Object to copy |
New object or NULL on error
Create an object (data) stream for writing.
pdfio_stream_t *pdfioObjCreateStream(pdfio_obj_t *obj, pdfio_filter_t filter);
| obj | Object |
|---|---|
| filter | Type of compression to apply |
Stream or NULL on error
Get the array associated with an object.
pdfio_array_t *pdfioObjGetArray(pdfio_obj_t *obj);
| obj | Object |
|---|
Array or NULL on error
Get the dictionary associated with an object.
pdfio_dict_t *pdfioObjGetDict(pdfio_obj_t *obj);
| obj | Object |
|---|
Dictionary or NULL on error
Get the object's generation number.
unsigned short pdfioObjGetGeneration(pdfio_obj_t *obj);
| obj | Object |
|---|
Generation number (0 to 65535)
Get the length of the object's (data) stream.
size_t pdfioObjGetLength(pdfio_obj_t *obj);
| obj | Object |
|---|
Length in bytes or 0 for none
Get the object's number.
size_t pdfioObjGetNumber(pdfio_obj_t *obj);
| obj | Object |
|---|
Object number (1 to 9999999999)
Get an object's subtype.
const char *pdfioObjGetSubtype(pdfio_obj_t *obj);
| obj | Object |
|---|
Object subtype
Get an object's type.
const char *pdfioObjGetType(pdfio_obj_t *obj);
| obj | Object |
|---|
Object type
Open an object's (data) stream for reading.
pdfio_stream_t *pdfioObjOpenStream(pdfio_obj_t *obj, bool decode);
| obj | Object |
|---|---|
| decode | Decode/decompress data? |
Stream or NULL on error
Copy a page to a PDF file.
bool pdfioPageCopy(pdfio_file_t *pdf, pdfio_obj_t *srcpage);
| PDF file | |
| srcpage | Source page |
true on success, false on failure
Add a color space to the page dictionary.
bool pdfioPageDictAddColorSpace(pdfio_dict_t *dict, const char *name, pdfio_array_t *data);
| dict | Page dictionary |
|---|---|
| name | Color space name |
| data | Color space array |
true on success, false on failure
This function adds a named color space to the page dictionary.
The names "DefaultCMYK", "DefaultGray", and "DefaultRGB" specify the default
device color space used for the page.
The "data" array contains a calibrated, indexed, or ICC-based color space
array that was created using the
pdfioArrayCreateCalibratedColorFromMatrix,
pdfioArrayCreateCalibratedColorFromPrimaries,
pdfioArrayCreateICCBasedColor, or
pdfioArrayCreateIndexedColor functions.
Add a font object to the page dictionary.
bool pdfioPageDictAddFont(pdfio_dict_t *dict, const char *name, pdfio_obj_t *obj);
| dict | Page dictionary |
|---|---|
| name | Font name |
| obj | Font object |
true on success, false on failure
Add an image object to the page dictionary.
bool pdfioPageDictAddImage(pdfio_dict_t *dict, const char *name, pdfio_obj_t *obj);
| dict | Page dictionary |
|---|---|
| name | Image name |
| obj | Image object |
true on success, false on failure
Close a (data) stream in a PDF file.
bool pdfioStreamClose(pdfio_stream_t *st);
| st | Stream |
|---|
true on success, false on failure
Consume bytes from the stream.
bool pdfioStreamConsume(pdfio_stream_t *st, size_t bytes);
| st | Stream |
|---|---|
| bytes | Number of bytes to consume |
true on success, false on EOF
Read a single PDF token from a stream.
bool pdfioStreamGetToken(pdfio_stream_t *st, char *buffer, size_t bufsize);
| st | Stream |
|---|---|
| buffer | String buffer |
| bufsize | Size of string buffer |
true on success, false on EOF
Peek at data in a stream.
ssize_t pdfioStreamPeek(pdfio_stream_t *st, void *buffer, size_t bytes);
| st | Stream |
|---|---|
| buffer | Buffer |
| bytes | Size of buffer |
Bytes returned or -1 on error
Write a formatted string to a stream.
bool pdfioStreamPrintf(pdfio_stream_t *st, const char *format, ...);
| st | Stream |
|---|---|
| format | printf-style format string |
| ... | Additional arguments as needed |
true on success, false on failure
Write a literal string to a stream.
bool pdfioStreamPuts(pdfio_stream_t *st, const char *s);
| st | Stream |
|---|---|
| s | Literal string |
true on success, false on failure
Read data from a stream.
ssize_t pdfioStreamRead(pdfio_stream_t *st, void *buffer, size_t bytes);
| st | Stream |
|---|---|
| buffer | Buffer |
| bytes | Bytes to read |
Number of bytes read or -1 on error
This function reads data from a stream. When reading decoded image data
from a stream, you must read whole scanlines. The
pdfioImageGetBytesPerLine function can be used to determine the
proper read length.
Write data to a stream.
bool pdfioStreamWrite(pdfio_stream_t *st, const void *buffer, size_t bytes);
| st | Stream |
|---|---|
| buffer | Data to write |
| bytes | Number of bytes to write |
true on success or false on failure
Create a durable literal string.
char *pdfioStringCreate(pdfio_file_t *pdf, const char *s);
| PDF file | |
| s | Nul-terminated string |
Durable string pointer or NULL on error
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.
Create a durable formatted string.
char *pdfioStringCreatef(pdfio_file_t *pdf, const char *format, ...);
| PDF file | |
| format | printf-style format string |
| ... | Additional args as needed |
Durable string pointer or NULL on error
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.
PDF value of any type
typedef struct _pdfio_value_s pdf_value_t;
Array of PDF values
typedef struct _pdfio_array_s pdfio_array_t;
Key/value dictionary
typedef struct _pdfio_dict_s pdfio_dict_t;
Error callback
typedef bool (*pdfio_error_cb_t)(pdfio_file_t *pdf, const char *message, void *data);
PDF file
typedef struct _pdfio_file_s pdfio_file_t;
Compression/decompression filters for streams
typedef enum pdfio_filter_e pdfio_filter_t;
Numbered object in PDF file
typedef struct _pdfio_obj_s pdfio_obj_t;
PDF rectangle
typedef struct pdfio_rect_s pdfio_rect_t;
Object data stream in PDF file
typedef struct _pdfio_stream_s pdfio_stream_t;
PDF value types
typedef enum pdfio_valtype_e pdfio_valtype_t;
PDF rectangle
struct pdfio_rect_s {
double x1;
double x2;
double y1;
double y2;
};
| x1 | Lower-left X coordinate |
|---|---|
| x2 | Upper-right X coordinate |
| y1 | Lower-left Y coordinate |
| y2 | Upper-right Y coordinate |
Compression/decompression filters for streams
| 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) |
PDF value types
| 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 |