Update docos.

This commit is contained in:
Michael R Sweet 2021-10-25 22:00:25 -04:00
parent 1d1ff88ebc
commit b865390b5d
No known key found for this signature in database
GPG Key ID: 999559A027815955
2 changed files with 223 additions and 5 deletions

View File

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

View File

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