# PDFio Programming Manual v0.1

Michael R Sweet

Copyright © 2021 by Michael R Sweet

## Contents

- Introduction
  - Requirements
  - Installing pdfio
  - Visual Studio Project
  - Xcode Project
  - Detecting PDFio
  - Header Files
- API Overview
  - PDF Files
  - PDF Values
  - PDF Objects
  - PDF Streams
- Functions
  - pdfioArrayAppendArray
  - pdfioArrayAppendBinary
  - pdfioArrayAppendBoolean
  - pdfioArrayAppendDict
  - pdfioArrayAppendName
  - pdfioArrayAppendNumber
  - pdfioArrayAppendObj
  - pdfioArrayAppendString
  - pdfioArrayCopy
  - pdfioArrayCreate
  - pdfioArrayCreateCalibratedColorFromMatrix
  - pdfioArrayCreateCalibratedColorFromPrimaries
  - pdfioArrayCreateICCBasedColor
  - pdfioArrayCreateIndexedColor
  - pdfioArrayGetArray
  - pdfioArrayGetBinary
  - pdfioArrayGetBoolean
  - pdfioArrayGetDict
  - pdfioArrayGetName
  - pdfioArrayGetNumber
  - pdfioArrayGetObj
  - pdfioArrayGetSize
  - pdfioArrayGetString
  - pdfioArrayGetType
  - pdfioContentClip
  - pdfioContentDrawImage
  - pdfioContentFill
  - pdfioContentFillAndStroke
  - pdfioContentMatrixConcat
  - pdfioContentMatrixRotate
  - pdfioContentMatrixScale
  - pdfioContentMatrixTranslate
  - pdfioContentPathClose
  - pdfioContentPathCurve
  - pdfioContentPathCurve13
  - pdfioContentPathCurve23
  - pdfioContentPathLineTo
  - pdfioContentPathMoveTo
  - pdfioContentPathRect
  - pdfioContentRestore
  - pdfioContentSave
  - pdfioContentSetDashPattern
  - pdfioContentSetFillColorDeviceCMYK
  - pdfioContentSetFillColorDeviceGray
  - pdfioContentSetFillColorDeviceRGB
  - pdfioContentSetFillColorGray
  - pdfioContentSetFillColorRGB
  - pdfioContentSetFillColorSpace
  - pdfioContentSetFlatness
  - pdfioContentSetLineCap
  - pdfioContentSetLineJoin
  - pdfioContentSetLineWidth
  - pdfioContentSetMiterLimit
  - pdfioContentSetStrokeColorDeviceCMYK
  - pdfioContentSetStrokeColorDeviceGray
  - pdfioContentSetStrokeColorDeviceRGB
  - pdfioContentSetStrokeColorGray
  - pdfioContentSetStrokeColorRGB
  - pdfioContentSetStrokeColorSpace
  - pdfioContentSetTextCharacterSpacing
  - pdfioContentSetTextFont
  - pdfioContentSetTextLeading
  - pdfioContentSetTextMatrix
  - pdfioContentSetTextRenderingMode
  - pdfioContentSetTextRise
  - pdfioContentSetTextWordSpacing
  - pdfioContentSetTextXScaling
  - pdfioContentStroke
  - pdfioContentTextBegin
  - pdfioContentTextEnd
  - pdfioContentTextMoveLine
  - pdfioContentTextMoveTo
  - pdfioContentTextNextLine
  - pdfioContentTextShow
  - pdfioContentTextShowJustified
  - pdfioContentTextShowf
  - pdfioDictCopy
  - pdfioDictCreate
  - pdfioDictGetArray
  - pdfioDictGetBinary
  - pdfioDictGetBoolean
  - pdfioDictGetDict
  - pdfioDictGetName
  - pdfioDictGetNumber
  - pdfioDictGetObj
  - pdfioDictGetRect
  - pdfioDictGetString
  - pdfioDictGetType
  - pdfioDictSetArray
  - pdfioDictSetBinary
  - pdfioDictSetBoolean
  - pdfioDictSetDict
  - pdfioDictSetName
  - pdfioDictSetNull
  - pdfioDictSetNumber
  - pdfioDictSetObj
  - pdfioDictSetRect
  - pdfioDictSetString
  - pdfioDictSetStringf
  - pdfioFileClose
  - pdfioFileCreate
  - pdfioFileCreateBaseFontObj
  - pdfioFileCreateFontObj
  - pdfioFileCreateICCProfileObj
  - pdfioFileCreateImageObj
  - pdfioFileCreateObj
  - pdfioFileCreatePage
  - pdfioFileFindObj
  - pdfioFileGetID
  - pdfioFileGetName
  - pdfioFileGetNumObjs
  - pdfioFileGetNumPages
  - pdfioFileGetObj
  - pdfioFileGetPage
  - pdfioFileGetVersion
  - pdfioFileOpen
  - pdfioImageGetBytesPerLine
  - pdfioImageGetHeight
  - pdfioImageGetWidth
  - pdfioObjClose
  - pdfioObjCopy
  - pdfioObjCreateStream
  - pdfioObjGetArray
  - pdfioObjGetDict
  - pdfioObjGetGeneration
  - pdfioObjGetLength
  - pdfioObjGetNumber
  - pdfioObjGetSubtype
  - pdfioObjGetType
  - pdfioObjOpenStream
  - pdfioPageCopy
  - pdfioPageDictAddColorSpace
  - pdfioPageDictAddFont
  - pdfioPageDictAddImage
  - pdfioStreamClose
  - pdfioStreamConsume
  - pdfioStreamGetToken
  - pdfioStreamPeek
  - pdfioStreamPrintf
  - pdfioStreamPuts
  - pdfioStreamRead
  - pdfioStreamWrite
  - pdfioStringCreate
  - pdfioStringCreatef
- Data Types
  - pdf_value_t
  - pdfio_array_t
  - pdfio_dict_t
  - pdfio_error_cb_t
  - pdfio_file_t
  - pdfio_filter_t
  - pdfio_obj_t
  - pdfio_rect_t
  - pdfio_stream_t
  - pdfio_valtype_t
- Structures
  - pdfio_rect_s
- Enumerations
  - pdfio_filter_e
  - pdfio_valtype_e

## 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.

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.

### Requirements

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.

### Installing pdfio

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")

### Visual Studio Project

> 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.

### Xcode Project

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

### Detecting PDFio

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`

### Header Files

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>

## API Overview

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

### PDF Files

### PDF Values

### PDF Objects

### PDF Streams

## 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, const 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

### pdfioArrayAppendObj

Add an indirect object reference to an array.

bool pdfioArrayAppendObj(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

### pdfioArrayCreateCalibratedColorFromMatrix

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]);

#### Parameters

pdf | PDF file
num_colors | Number of colors (1 or 3)
gamma | Gamma value
matrix[3][3] | XYZ transform
white_point[3] | White point

#### Return Value

Color space array

### pdfioArrayCreateCalibratedColorFromPrimaries

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);

#### Parameters

pdf | 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

#### Return Value

Color space array

### pdfioArrayCreateICCBasedColor

Create an ICC-based color space array.

pdfio_array_t *pdfioArrayCreateICCBasedColor(pdfio_file_t *pdf, pdfio_obj_t *icc_object);

#### Parameters

pdf | PDF file
icc_object | ICC profile object

#### Return Value

Color array

### pdfioArrayCreateIndexedColor

Create an indexed color space array.

pdfio_array_t *pdfioArrayCreateIndexedColor(pdfio_file_t *pdf, size_t num_colors, const unsigned char *colors);

#### Parameters

pdf | PDF file
num_colors | Number of colors
colors | RGB values for colors

#### Return Value

Color array

### 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

### pdfioArrayGetObj

Get an indirect object reference from an array.

pdfio_obj_t *pdfioArrayGetObj(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

### 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 width, double height);

#### Parameters

st | Stream
name | Image name
x | X offset of image
y | Y offset of image
width | Width of image
height | 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.

### 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, double x, double y, double width, double height);

#### Parameters

st | Stream
x | X offset
y | Y offset
width | Width
height | Height

#### 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

### pdfioContentTextBegin

Begin a text block.

bool pdfioContentTextBegin(pdfio_stream_t *st);

#### Parameters

st | Stream

#### Return Value

`true` on success, `false` on failure

### pdfioContentTextEnd

End a text block.

bool pdfioContentTextEnd(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);

#### Parameters

st | Stream
s | String to show

#### 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

### pdfioContentTextShowf

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

#### Parameters

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

#### Return Value

Show formatted text.

### 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

### pdfioDictGetObj

Get a key indirect object value from a dictionary.

pdfio_obj_t *pdfioDictGetObj(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, const 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

### pdfioDictSetObj

Set a key indirect object reference in a dictionary.

bool pdfioDictSetObj(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

### pdfioFileCreateBaseFontObj

Create one of the base 14 PDF fonts.

pdfio_obj_t *pdfioFileCreateBaseFontObj(pdfio_file_t *pdf, const char *name);

#### Parameters

pdf | PDF file
name | Font name

#### Return Value

Font object

#### Discussion

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`
- `ZapfDingbats`

### pdfioFileCreateFontObj

Add a font object to a PDF file.

pdfio_obj_t *pdfioFileCreateFontObj(pdfio_file_t *pdf, const char *filename, bool unicode);

#### Parameters

pdf | PDF file
filename | Filename
unicode | Unicode font?

#### Return Value

Font object

### pdfioFileCreateICCProfileObj

Add an ICC profile object to a PDF file.

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

#### Parameters

pdf | PDF file
filename | Filename

#### Return Value

Object

### pdfioFileCreateImageObj

Add an image object to a PDF file.

pdfio_obj_t *pdfioFileCreateImageObj(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.

### pdfioFileCreateObj

Create a new object in a PDF file.

pdfio_obj_t *pdfioFileCreateObj(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

### pdfioFileFindObj

Find an object using its object number.

pdfio_obj_t *pdfioFileFindObj(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 `pdfioFileGetObj` 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

### pdfioFileGetNumObjs

Get the number of objects in a PDF file.

size_t pdfioFileGetNumObjs(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

### pdfioFileGetObj

Get an object from a PDF file.

pdfio_obj_t *pdfioFileGetObj(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

### pdfioImageGetBytesPerLine

Get the number of bytes to read for each line.

size_t pdfioImageGetBytesPerLine(pdfio_obj_t *obj);

#### Parameters

obj | Image object

#### Return Value

Number of bytes per line

### 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)

### pdfioObjGetSubtype

Get an object's subtype.

const char *pdfioObjGetSubtype(pdfio_obj_t *obj);

#### Parameters

obj | Object

#### Return Value

Object subtype

### 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

### pdfioPageDictAddColorSpace

Add a color space to the page dictionary.

bool pdfioPageDictAddColorSpace(pdfio_dict_t *dict, const char *name, pdfio_array_t *data);

#### Parameters

dict | Page dictionary
name | Color space name
data | Color space array

#### Return Value

`true` on success, `false` on failure

#### Discussion

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.

### 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

### 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

#### Discussion

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.

### 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