1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
.. _using-library:
Using the QPDF Library
======================
.. _using.from-cxx:
Using QPDF from C++
-------------------
The source tree for the qpdf package has an
:file:`examples` directory that contains a few
example programs. The :file:`libqpdf/QPDFJob.cc` source
file also serves as a useful example since it exercises almost all of
the qpdf library's public interface. The best source of documentation on
the library itself is reading comments in
:file:`include/qpdf/QPDF.hh`,
:file:`include/qpdf/QPDFWriter.hh`, and
:file:`include/qpdf/QPDFObjectHandle.hh`.
All header files are installed in the
:file:`include/qpdf` directory. It is recommend that
you use ``#include <qpdf/QPDF.hh>`` rather than adding
:file:`include/qpdf` to your include path.
qpdf installs a ``pkg-config`` configuration with package name
``libqpdf`` and a ``cmake`` configuration with package name ``qpdf``.
The ``libqpdf`` target is exported in the ``qpdf::`` namespace. The
following is an example of a :file:`CMakeLists.txt` file for a
single-file executable that links with qpdf:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.16)
project(some-application LANGUAGES CXX)
find_package(qpdf)
add_executable(some-application some-application.cc)
target_link_libraries(some-application qpdf::libqpdf)
The qpdf library is safe to use in a multithreaded program, but no
individual ``QPDF`` object instance (including ``QPDF``,
``QPDFObjectHandle``, or ``QPDFWriter``) can be used in more than one
thread at a time. Multiple threads may simultaneously work with
different instances of these and all other QPDF objects.
.. _using.other-languages:
Using QPDF from other languages
-------------------------------
The qpdf library is implemented in C++, which makes it hard to use
directly in other languages. There are a few things that can help.
"C"
The qpdf library includes a "C" language interface that provides a
subset of the overall capabilities. The header file
:file:`qpdf/qpdf-c.h` includes information about
its use. As long as you use a C++ linker, you can link C programs
with qpdf and use the C API. For languages that can directly load
methods from a shared library, the C API can also be useful. People
have reported success using the C API from other languages on Windows
by directly calling functions in the DLL.
Python
A Python module called
`pikepdf <https://pypi.org/project/pikepdf/>`__ provides a clean and
highly functional set of Python bindings to the qpdf library. Using
pikepdf, you can work with PDF files in a natural way and combine
qpdf's capabilities with other functionality provided by Python's
rich standard library and available modules.
Other Languages Starting with version 11.0.0, the :command:`qpdf`
command-line tool can produce an unambiguous JSON representation of
a PDF file and can also create or update PDF files using this JSON
representation. qpdf versions from 8.3.0 through 10.6.3 had a more
limited JSON output format. The qpdf JSON format makes it possible
to inspect and modify the structure of a PDF file down to the
object level from the command-line or from any language that can
handle JSON data. Please see :ref:`json` for details.
Wrappers
The `qpdf Wiki <https://github.com/qpdf/qpdf/wiki>`__ contains a
list of `Wrappers around qpdf
<https://github.com/qpdf/qpdf/wiki/qpdf-Wrappers>`__. These may
have varying degrees of functionality or completeness. If you know
of (or have written) a wrapper that you'd like include, open an
issue at https://github.com/qpdf/qpdf/issues/new and ask for it to
be added to the list.
.. _unicode-files:
A Note About Unicode File Names
-------------------------------
When strings are passed to qpdf library routines either as ``char*`` or
as ``std::string``, they are treated as byte arrays except where
otherwise noted. When Unicode is desired, qpdf wants UTF-8 unless
otherwise noted in comments in header files. In modern UNIX/Linux
environments, this generally does the right thing. In Windows, it's a
bit more complicated. Starting in qpdf 8.4.0, passwords that contain
Unicode characters are handled much better, and starting in qpdf 8.4.1,
the library attempts to properly handle Unicode characters in filenames.
In particular, in Windows, if a UTF-8 encoded string is used as a
filename in either ``QPDF`` or ``QPDFWriter``, it is internally
converted to ``wchar_t*``, and Unicode-aware Windows APIs are used. As
such, qpdf will generally operate properly on files with non-ASCII
characters in their names as long as the filenames are UTF-8 encoded for
passing into the qpdf library API, but there are still some rough edges,
such as the encoding of the filenames in error messages or CLI output
messages. Patches or bug reports are welcome for any continuing issues
with Unicode file names in Windows.
|
