mirror of
https://github.com/michaelrsweet/pdfio.git
synced 2024-12-26 05:18:21 +01:00
Update docos.
This commit is contained in:
Michael R Sweet
parent
1d1ff88ebc
commit
b865390b5d
131
doc/pdfio.3
131
doc/pdfio.3
@ -1,4 +1,4 @@
|
||||
.TH pdfio 3 "pdf read/write library" "2021-10-18" "pdf read/write library"
|
||||
.TH pdfio 3 "pdf read/write library" "2021-10-25" "pdf read/write library"
|
||||
.SH NAME
|
||||
pdfio \- pdf read/write library
|
||||
.SH Introduction
|
||||
@ -6,11 +6,15 @@ pdfio \- pdf read/write library
|
||||
PDFio is a simple C library for reading and writing PDF files. The primary goals of pdfio are:
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Read any PDF file with or without encryption or linearization
|
||||
Read and write any version of PDF file
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Write PDF files without encryption or linearization
|
||||
Provide access to pages, objects, and streams within a PDF file
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Support reading and writing of encrypted PDF files
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
@ -809,6 +813,28 @@ Display P3
|
||||
PDFIO_CS_SRGB
|
||||
.br
|
||||
sRGB
|
||||
.SS pdfio_encryption_e
|
||||
PDF encryption modes
|
||||
.TP 5
|
||||
PDFIO_ENCRYPTION_AES_128
|
||||
.br
|
||||
128-bit AES encryption (PDF 1.6)
|
||||
.TP 5
|
||||
PDFIO_ENCRYPTION_AES_256
|
||||
.br
|
||||
256-bit AES encryption (PDF 2.0)
|
||||
.TP 5
|
||||
PDFIO_ENCRYPTION_NONE
|
||||
.br
|
||||
No encryption
|
||||
.TP 5
|
||||
PDFIO_ENCRYPTION_RC4_128
|
||||
.br
|
||||
128-bit RC4 encryption (PDF 1.4)
|
||||
.TP 5
|
||||
PDFIO_ENCRYPTION_RC4_40
|
||||
.br
|
||||
40-bit RC4 encryption (PDF 1.3)
|
||||
.SS pdfio_filter_e
|
||||
Compression/decompression filters for streams
|
||||
.TP 5
|
||||
@ -883,6 +909,51 @@ Miter joint
|
||||
PDFIO_LINEJOIN_ROUND
|
||||
.br
|
||||
Round joint
|
||||
.SS pdfio_permission_e
|
||||
PDF permission bits
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_ALL
|
||||
.br
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_ANNOTATE
|
||||
.br
|
||||
PDF allows annotation
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_ASSEMBLE
|
||||
.br
|
||||
PDF allows assembly (insert, delete, or rotate pages, add document outlines and thumbnails)
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_COPY
|
||||
.br
|
||||
PDF allows copying
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_FORMS
|
||||
.br
|
||||
PDF allows filling in forms
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_MODIFY
|
||||
.br
|
||||
PDF allows modification
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_NONE
|
||||
.br
|
||||
No permissions
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_PRINT
|
||||
.br
|
||||
PDF allows printing
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_PRINT_HIGH
|
||||
.br
|
||||
PDF allows high quality printing
|
||||
.TP 5
|
||||
PDFIO_PERMISSION_READING
|
||||
.br
|
||||
PDF allows screen reading/accessibility (deprecated in PDF 2.0)
|
||||
.TP 5
|
||||
~0
|
||||
.br
|
||||
All permissions
|
||||
.SS pdfio_textrendering_e
|
||||
Text rendering modes
|
||||
.TP 5
|
||||
@ -2308,6 +2379,18 @@ pdfio_obj_t * pdfioFileGetPage (
|
||||
size_t n
|
||||
);
|
||||
.fi
|
||||
.SS pdfioFileGetPermissions
|
||||
Get the access permissions of a PDF file.
|
||||
.PP
|
||||
.nf
|
||||
pdfio_permission_t pdfioFileGetPermissions (
|
||||
pdfio_file_t *pdf,
|
||||
pdfio_encryption_t *encryption
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
This function returns the access permissions of a PDF file and (optionally)
|
||||
the type of encryption that has been used.
|
||||
.SS pdfioFileGetProducer
|
||||
Get the producer string for a PDF file.
|
||||
.PP
|
||||
@ -2401,6 +2484,30 @@ void pdfioFileSetKeywords (
|
||||
const char *value
|
||||
);
|
||||
.fi
|
||||
.SS pdfioFileSetPermissions
|
||||
Set the PDF permissions, encryption mode, and passwords.
|
||||
.PP
|
||||
.nf
|
||||
bool pdfioFileSetPermissions (
|
||||
pdfio_file_t *pdf,
|
||||
pdfio_permission_t permissions,
|
||||
pdfio_encryption_t encryption,
|
||||
const char *owner_password,
|
||||
const char *user_password
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
This function sets the PDF usage permissions, encryption mode, and
|
||||
passwords.
|
||||
.PP
|
||||
.IP 5
|
||||
\fINote\fR: This function must be called before creating or copying any
|
||||
.IP 5
|
||||
objects. Due to fundamental limitations in the PDF format, PDF encryption
|
||||
.IP 5
|
||||
offers little protection from disclosure. Permissions are not enforced in
|
||||
.IP 5
|
||||
any meaningful way.
|
||||
.SS pdfioFileSetSubject
|
||||
Set the subject for a PDF file.
|
||||
.PP
|
||||
@ -2739,6 +2846,12 @@ Key/value dictionary
|
||||
.nf
|
||||
typedef struct _pdfio_dict_s pdfio_dict_t;
|
||||
.fi
|
||||
.SS pdfio_encryption_t
|
||||
PDF encryption modes
|
||||
.PP
|
||||
.nf
|
||||
typedef enum pdfio_encryption_e pdfio_encryption_t;
|
||||
.fi
|
||||
.SS pdfio_error_cb_t
|
||||
Error callback
|
||||
.PP
|
||||
@ -2793,6 +2906,12 @@ Password callback for pdfioFileOpen
|
||||
.nf
|
||||
typedef const char *(*)(void *data const char *filename) pdfio_password_cb_t;
|
||||
.fi
|
||||
.SS pdfio_permission_t
|
||||
PDF permission bitfield
|
||||
.PP
|
||||
.nf
|
||||
typedef int pdfio_permission_t;
|
||||
.fi
|
||||
.SS pdfio_rect_t
|
||||
PDF rectangle
|
||||
.PP
|
||||
@ -2817,6 +2936,12 @@ PDF value types
|
||||
.nf
|
||||
typedef enum pdfio_valtype_e pdfio_valtype_t;
|
||||
.fi
|
||||
.SS state_t[4][4]
|
||||
4x4 AES state table
|
||||
.PP
|
||||
.nf
|
||||
typedef uint8_t state_t[4][4];
|
||||
.fi
|
||||
.SH AUTHOR
|
||||
.PP
|
||||
Michael R Sweet
|
||||
|
||||
@ -394,6 +394,7 @@ span.string {
|
||||
<li><a href="#pdfioFileGetNumPages">pdfioFileGetNumPages</a></li>
|
||||
<li><a href="#pdfioFileGetObj">pdfioFileGetObj</a></li>
|
||||
<li><a href="#pdfioFileGetPage">pdfioFileGetPage</a></li>
|
||||
<li><a href="#pdfioFileGetPermissions">pdfioFileGetPermissions</a></li>
|
||||
<li><a href="#pdfioFileGetProducer">pdfioFileGetProducer</a></li>
|
||||
<li><a href="#pdfioFileGetSubject">pdfioFileGetSubject</a></li>
|
||||
<li><a href="#pdfioFileGetTitle">pdfioFileGetTitle</a></li>
|
||||
@ -403,6 +404,7 @@ span.string {
|
||||
<li><a href="#pdfioFileSetCreationDate">pdfioFileSetCreationDate</a></li>
|
||||
<li><a href="#pdfioFileSetCreator">pdfioFileSetCreator</a></li>
|
||||
<li><a href="#pdfioFileSetKeywords">pdfioFileSetKeywords</a></li>
|
||||
<li><a href="#pdfioFileSetPermissions">pdfioFileSetPermissions</a></li>
|
||||
<li><a href="#pdfioFileSetSubject">pdfioFileSetSubject</a></li>
|
||||
<li><a href="#pdfioFileSetTitle">pdfioFileSetTitle</a></li>
|
||||
<li><a href="#pdfioImageGetBytesPerLine">pdfioImageGetBytesPerLine</a></li>
|
||||
@ -439,6 +441,7 @@ span.string {
|
||||
<li><a href="#pdfio_array_t">pdfio_array_t</a></li>
|
||||
<li><a href="#pdfio_cs_t">pdfio_cs_t</a></li>
|
||||
<li><a href="#pdfio_dict_t">pdfio_dict_t</a></li>
|
||||
<li><a href="#pdfio_encryption_t">pdfio_encryption_t</a></li>
|
||||
<li><a href="#pdfio_error_cb_t">pdfio_error_cb_t</a></li>
|
||||
<li><a href="#pdfio_file_t">pdfio_file_t</a></li>
|
||||
<li><a href="#pdfio_filter_t">pdfio_filter_t</a></li>
|
||||
@ -448,19 +451,23 @@ span.string {
|
||||
<li><a href="#pdfio_obj_t">pdfio_obj_t</a></li>
|
||||
<li><a href="#pdfio_output_cb_t">pdfio_output_cb_t</a></li>
|
||||
<li><a href="#pdfio_password_cb_t">pdfio_password_cb_t</a></li>
|
||||
<li><a href="#pdfio_permission_t">pdfio_permission_t</a></li>
|
||||
<li><a href="#pdfio_rect_t">pdfio_rect_t</a></li>
|
||||
<li><a href="#pdfio_stream_t">pdfio_stream_t</a></li>
|
||||
<li><a href="#pdfio_textrendering_t">pdfio_textrendering_t</a></li>
|
||||
<li><a href="#pdfio_valtype_t">pdfio_valtype_t</a></li>
|
||||
<li><a href="#state_t[4][4]">state_t[4][4]</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#STRUCTURES">Structures</a><ul class="subcontents">
|
||||
<li><a href="#pdfio_rect_s">pdfio_rect_s</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents">
|
||||
<li><a href="#pdfio_cs_e">pdfio_cs_e</a></li>
|
||||
<li><a href="#pdfio_encryption_e">pdfio_encryption_e</a></li>
|
||||
<li><a href="#pdfio_filter_e">pdfio_filter_e</a></li>
|
||||
<li><a href="#pdfio_linecap_e">pdfio_linecap_e</a></li>
|
||||
<li><a href="#pdfio_linejoin_e">pdfio_linejoin_e</a></li>
|
||||
<li><a href="#pdfio_permission_e">pdfio_permission_e</a></li>
|
||||
<li><a href="#pdfio_textrendering_e">pdfio_textrendering_e</a></li>
|
||||
<li><a href="#pdfio_valtype_e">pdfio_valtype_e</a></li>
|
||||
</ul></li>
|
||||
@ -470,9 +477,11 @@ span.string {
|
||||
<h2 class="title" id="introduction">Introduction</h2>
|
||||
<p>PDFio is a simple C library for reading and writing PDF files. The primary goals of pdfio are:</p>
|
||||
<ul>
|
||||
<li><p>Read any PDF file with or without encryption or linearization</p>
|
||||
<li><p>Read and write any version of PDF file</p>
|
||||
</li>
|
||||
<li><p>Write PDF files without encryption or linearization</p>
|
||||
<li><p>Provide access to pages, objects, and streams within a PDF file</p>
|
||||
</li>
|
||||
<li><p>Support reading and writing of encrypted PDF files</p>
|
||||
</li>
|
||||
<li><p>Extract or embed useful metadata (author, creator, page information, etc.)</p>
|
||||
</li>
|
||||
@ -2838,6 +2847,22 @@ size_t pdfioFileGetNumPages(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf);</p>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Object</p>
|
||||
<h3 class="function"><a id="pdfioFileGetPermissions">pdfioFileGetPermissions</a></h3>
|
||||
<p class="description">Get the access permissions of a PDF file.</p>
|
||||
<p class="code">
|
||||
<a href="#pdfio_permission_t">pdfio_permission_t</a> pdfioFileGetPermissions(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, <a href="#pdfio_encryption_t">pdfio_encryption_t</a> *encryption);</p>
|
||||
<h4 class="parameters">Parameters</h4>
|
||||
<table class="list"><tbody>
|
||||
<tr><th>pdf</th>
|
||||
<td class="description">PDF file</td></tr>
|
||||
<tr><th>encryption</th>
|
||||
<td class="description">Type of encryption used or <code>NULL</code> to ignore</td></tr>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Permission bits</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function returns the access permissions of a PDF file and (optionally)
|
||||
the type of encryption that has been used.</p>
|
||||
<h3 class="function"><a id="pdfioFileGetProducer">pdfioFileGetProducer</a></h3>
|
||||
<p class="description">Get the producer string for a PDF file.</p>
|
||||
<p class="code">
|
||||
@ -2958,6 +2983,34 @@ void pdfioFileSetKeywords(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, const c
|
||||
<tr><th>value</th>
|
||||
<td class="description">Value</td></tr>
|
||||
</tbody></table>
|
||||
<h3 class="function"><a id="pdfioFileSetPermissions">pdfioFileSetPermissions</a></h3>
|
||||
<p class="description">Set the PDF permissions, encryption mode, and passwords.</p>
|
||||
<p class="code">
|
||||
bool pdfioFileSetPermissions(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, <a href="#pdfio_permission_t">pdfio_permission_t</a> permissions, <a href="#pdfio_encryption_t">pdfio_encryption_t</a> encryption, const char *owner_password, const char *user_password);</p>
|
||||
<h4 class="parameters">Parameters</h4>
|
||||
<table class="list"><tbody>
|
||||
<tr><th>pdf</th>
|
||||
<td class="description">PDF file</td></tr>
|
||||
<tr><th>permissions</th>
|
||||
<td class="description">Use permissions</td></tr>
|
||||
<tr><th>encryption</th>
|
||||
<td class="description">Type of encryption to use</td></tr>
|
||||
<tr><th>owner_password</th>
|
||||
<td class="description">Owner password, if any</td></tr>
|
||||
<tr><th>user_password</th>
|
||||
<td class="description">User password, if any</td></tr>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description"><code>true</code> on success, <code>false</code> otherwise</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function sets the PDF usage permissions, encryption mode, and
|
||||
passwords.<br>
|
||||
<br>
|
||||
</p><blockquote>
|
||||
<em>Note</em>: This function must be called before creating or copying any
|
||||
objects. Due to fundamental limitations in the PDF format, PDF encryption
|
||||
offers little protection from disclosure. Permissions are not enforced in
|
||||
any meaningful way.</blockquote>
|
||||
<h3 class="function"><a id="pdfioFileSetSubject">pdfioFileSetSubject</a></h3>
|
||||
<p class="description">Set the subject for a PDF file.</p>
|
||||
<p class="code">
|
||||
@ -3397,6 +3450,11 @@ typedef enum <a href="#pdfio_cs_e">pdfio_cs_e</a> pdfio_cs_t;
|
||||
<p class="code">
|
||||
typedef struct _pdfio_dict_s pdfio_dict_t;
|
||||
</p>
|
||||
<h3 class="typedef"><a id="pdfio_encryption_t">pdfio_encryption_t</a></h3>
|
||||
<p class="description">PDF encryption modes</p>
|
||||
<p class="code">
|
||||
typedef enum <a href="#pdfio_encryption_e">pdfio_encryption_e</a> pdfio_encryption_t;
|
||||
</p>
|
||||
<h3 class="typedef"><a id="pdfio_error_cb_t">pdfio_error_cb_t</a></h3>
|
||||
<p class="description">Error callback</p>
|
||||
<p class="code">
|
||||
@ -3442,6 +3500,11 @@ typedef ssize_t (*pdfio_output_cb_t)(void *ctx const void *data size_t datalen);
|
||||
<p class="code">
|
||||
typedef const char *(*pdfio_password_cb_t)(void *data const char *filename);
|
||||
</p>
|
||||
<h3 class="typedef"><a id="pdfio_permission_t">pdfio_permission_t</a></h3>
|
||||
<p class="description">PDF permission bitfield</p>
|
||||
<p class="code">
|
||||
typedef int pdfio_permission_t;
|
||||
</p>
|
||||
<h3 class="typedef"><a id="pdfio_rect_t">pdfio_rect_t</a></h3>
|
||||
<p class="description">PDF rectangle</p>
|
||||
<p class="code">
|
||||
@ -3462,6 +3525,11 @@ typedef enum <a href="#pdfio_textrendering_e">pdfio_textrendering_e</a> pdfio_te
|
||||
<p class="code">
|
||||
typedef enum <a href="#pdfio_valtype_e">pdfio_valtype_e</a> pdfio_valtype_t;
|
||||
</p>
|
||||
<h3 class="typedef"><a id="state_t[4][4]">state_t[4][4]</a></h3>
|
||||
<p class="description">4x4 AES state table</p>
|
||||
<p class="code">
|
||||
typedef uint8_t state_t[4][4];
|
||||
</p>
|
||||
<h2 class="title"><a id="STRUCTURES">Structures</a></h2>
|
||||
<h3 class="struct"><a id="pdfio_rect_s">pdfio_rect_s</a></h3>
|
||||
<p class="description">PDF rectangle</p>
|
||||
@ -3491,6 +3559,16 @@ typedef enum <a href="#pdfio_valtype_e">pdfio_valtype_e</a> pdfio_valtype_t;
|
||||
<tr><th>PDFIO_CS_P3_D65 </th><td class="description">Display P3</td></tr>
|
||||
<tr><th>PDFIO_CS_SRGB </th><td class="description">sRGB</td></tr>
|
||||
</tbody></table>
|
||||
<h3 class="enumeration"><a id="pdfio_encryption_e">pdfio_encryption_e</a></h3>
|
||||
<p class="description">PDF encryption modes</p>
|
||||
<h4 class="constants">Constants</h4>
|
||||
<table class="list"><tbody>
|
||||
<tr><th>PDFIO_ENCRYPTION_AES_128 </th><td class="description">128-bit AES encryption (PDF 1.6)</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_AES_256 </th><td class="description">256-bit AES encryption (PDF 2.0)</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_NONE </th><td class="description">No encryption</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_RC4_128 </th><td class="description">128-bit RC4 encryption (PDF 1.4)</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_RC4_40 </th><td class="description">40-bit RC4 encryption (PDF 1.3)</td></tr>
|
||||
</tbody></table>
|
||||
<h3 class="enumeration"><a id="pdfio_filter_e">pdfio_filter_e</a></h3>
|
||||
<p class="description">Compression/decompression filters for streams</p>
|
||||
<h4 class="constants">Constants</h4>
|
||||
@ -3523,6 +3601,21 @@ typedef enum <a href="#pdfio_valtype_e">pdfio_valtype_e</a> pdfio_valtype_t;
|
||||
<tr><th>PDFIO_LINEJOIN_MITER </th><td class="description">Miter joint</td></tr>
|
||||
<tr><th>PDFIO_LINEJOIN_ROUND </th><td class="description">Round joint</td></tr>
|
||||
</tbody></table>
|
||||
<h3 class="enumeration"><a id="pdfio_permission_e">pdfio_permission_e</a></h3>
|
||||
<p class="description">PDF permission bits</p>
|
||||
<h4 class="constants">Constants</h4>
|
||||
<table class="list"><tbody>
|
||||
<tr><th>PDFIO_PERMISSION_ANNOTATE </th><td class="description">PDF allows annotation</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_ASSEMBLE </th><td class="description">PDF allows assembly (insert, delete, or rotate pages, add document outlines and thumbnails)</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_COPY </th><td class="description">PDF allows copying</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_FORMS </th><td class="description">PDF allows filling in forms</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_MODIFY </th><td class="description">PDF allows modification</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_NONE </th><td class="description">No permissions</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_PRINT </th><td class="description">PDF allows printing</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_PRINT_HIGH </th><td class="description">PDF allows high quality printing</td></tr>
|
||||
<tr><th>PDFIO_PERMISSION_READING </th><td class="description">PDF allows screen reading/accessibility (deprecated in PDF 2.0)</td></tr>
|
||||
<tr><th>~0 </th><td class="description">All permissions</td></tr>
|
||||
</tbody></table>
|
||||
<h3 class="enumeration"><a id="pdfio_textrendering_e">pdfio_textrendering_e</a></h3>
|
||||
<p class="description">Text rendering modes</p>
|
||||
<h4 class="constants">Constants</h4>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user