From b865390b5de2deee90e0cbf6ada49fa2e3c0f8a2 Mon Sep 17 00:00:00 2001
From: Michael R Sweet
Date: Mon, 25 Oct 2021 22:00:25 -0400
Subject: [PATCH] Update docos.
---
doc/pdfio.3 | 131 +++++++++++++++++++++++++++++++++++++++++++++++--
doc/pdfio.html | 97 +++++++++++++++++++++++++++++++++++-
2 files changed, 223 insertions(+), 5 deletions(-)
diff --git a/doc/pdfio.3 b/doc/pdfio.3
index 25e7fc0..667b494 100644
--- a/doc/pdfio.3
+++ b/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
diff --git a/doc/pdfio.html b/doc/pdfio.html
index b32cfd7..7cf94de 100644
--- a/doc/pdfio.html
+++ b/doc/pdfio.html
@@ -394,6 +394,7 @@ span.string {
pdfioFileGetNumPages
pdfioFileGetObj
pdfioFileGetPage
+pdfioFileGetPermissions
pdfioFileGetProducer
pdfioFileGetSubject
pdfioFileGetTitle
@@ -403,6 +404,7 @@ span.string {
pdfioFileSetCreationDate
pdfioFileSetCreator
pdfioFileSetKeywords
+pdfioFileSetPermissions
pdfioFileSetSubject
pdfioFileSetTitle
pdfioImageGetBytesPerLine
@@ -439,6 +441,7 @@ span.string {
pdfio_array_t
pdfio_cs_t
pdfio_dict_t
+pdfio_encryption_t
pdfio_error_cb_t
pdfio_file_t
pdfio_filter_t
@@ -448,19 +451,23 @@ span.string {
pdfio_obj_t
pdfio_output_cb_t
pdfio_password_cb_t
+pdfio_permission_t
pdfio_rect_t
pdfio_stream_t
pdfio_textrendering_t
pdfio_valtype_t
+state_t[4][4]
Structures
Enumerations
@@ -470,9 +477,11 @@ span.string {
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
+Read and write any version of PDF file
-Write PDF files without encryption or linearization
+Provide access to pages, objects, and streams within a PDF file
+
+Support reading and writing of encrypted PDF files
Extract or embed useful metadata (author, creator, page information, etc.)
@@ -2838,6 +2847,22 @@ size_t pdfioFileGetNumPages(pdfio_file_t *pdf);
Return Value
Object
+
+Get the access permissions of a PDF file.
+
+pdfio_permission_t pdfioFileGetPermissions(pdfio_file_t *pdf, pdfio_encryption_t *encryption);
+Parameters
+
+pdf |
+PDF file |
+encryption |
+Type of encryption used or NULL to ignore |
+
+Return Value
+Permission bits
+Discussion
+This function returns the access permissions of a PDF file and (optionally)
+the type of encryption that has been used.
Get the producer string for a PDF file.
@@ -2958,6 +2983,34 @@ void pdfioFileSetKeywords(pdfio_file_t *pdf, const c
value |
Value |
+
+Set the PDF permissions, encryption mode, and passwords.
+
+bool pdfioFileSetPermissions(pdfio_file_t *pdf, pdfio_permission_t permissions, pdfio_encryption_t encryption, const char *owner_password, const char *user_password);
+Parameters
+
+pdf |
+PDF file |
+permissions |
+Use permissions |
+encryption |
+Type of encryption to use |
+owner_password |
+Owner password, if any |
+user_password |
+User password, if any |
+
+Return Value
+true
on success, false
otherwise
+Discussion
+This function sets the PDF usage permissions, encryption mode, and
+passwords.
+
+
+Note: 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.
Set the subject for a PDF file.
@@ -3397,6 +3450,11 @@ typedef enum pdfio_cs_e pdfio_cs_t;
typedef struct _pdfio_dict_s pdfio_dict_t;
+
+PDF encryption modes
+
+typedef enum pdfio_encryption_e pdfio_encryption_t;
+
Error callback
@@ -3442,6 +3500,11 @@ typedef ssize_t (*pdfio_output_cb_t)(void *ctx const void *data size_t datalen);
typedef const char *(*pdfio_password_cb_t)(void *data const char *filename);
+
+PDF permission bitfield
+
+typedef int pdfio_permission_t;
+
PDF rectangle
@@ -3462,6 +3525,11 @@ typedef enum pdfio_textrendering_e pdfio_te
typedef enum pdfio_valtype_e pdfio_valtype_t;
+
+4x4 AES state table
+
+typedef uint8_t state_t[4][4];
+
PDF rectangle
@@ -3491,6 +3559,16 @@ typedef enum pdfio_valtype_e pdfio_valtype_t;
PDFIO_CS_P3_D65 | Display P3 |
PDFIO_CS_SRGB | sRGB |
+
+PDF encryption modes
+Constants
+
+PDFIO_ENCRYPTION_AES_128 | 128-bit AES encryption (PDF 1.6) |
+PDFIO_ENCRYPTION_AES_256 | 256-bit AES encryption (PDF 2.0) |
+PDFIO_ENCRYPTION_NONE | No encryption |
+PDFIO_ENCRYPTION_RC4_128 | 128-bit RC4 encryption (PDF 1.4) |
+PDFIO_ENCRYPTION_RC4_40 | 40-bit RC4 encryption (PDF 1.3) |
+
Compression/decompression filters for streams
Constants
@@ -3523,6 +3601,21 @@ typedef enum pdfio_valtype_e pdfio_valtype_t;
PDFIO_LINEJOIN_MITER | Miter joint |
PDFIO_LINEJOIN_ROUND | Round joint |
+
+PDF permission bits
+Constants
+
+PDFIO_PERMISSION_ANNOTATE | PDF allows annotation |
+PDFIO_PERMISSION_ASSEMBLE | PDF allows assembly (insert, delete, or rotate pages, add document outlines and thumbnails) |
+PDFIO_PERMISSION_COPY | PDF allows copying |
+PDFIO_PERMISSION_FORMS | PDF allows filling in forms |
+PDFIO_PERMISSION_MODIFY | PDF allows modification |
+PDFIO_PERMISSION_NONE | No permissions |
+PDFIO_PERMISSION_PRINT | PDF allows printing |
+PDFIO_PERMISSION_PRINT_HIGH | PDF allows high quality printing |
+PDFIO_PERMISSION_READING | PDF allows screen reading/accessibility (deprecated in PDF 2.0) |
+~0 | All permissions |
+
Text rendering modes
Constants