1# Getting Started with PDFium
2
3[TOC]
4
5This guide walks through some examples of using the PDFium library. For an
6example of using PDFium see the [Chromium PDF Plugin][chrome-plugin].
7
8## Prerequisites
9
10You will need the PDFium library on your computer. You can see the
11[README](/README.md) for instructions on getting and installing PDFium.
12
13*** note
14You must compile PDFium without both V8 and XFA support for the examples
15here to work. V8 can be disabled by setting `pdf_enable_v8 = false` in the
16GN args.
17
18See the [V8 Getting Started][pdfium-v8] guide for how to
19initialize PDFium when V8 is compiled into the binary.
20***
21
22## PDFium Headers
23
24PDFium's API has been broken up over several headers. You only need to include
25the headers for functionality you use in your application. The full set of
26headers can be found in the [public/ folder of the repository][pdfium-public].
27
28In all cases you'll need to include `fpdfview.h` as it defines the needed
29methods for initialization and destruction of the library.
30
31## Initializing PDFium
32
33The first step to using PDFium is to initialize the library. Having done so,
34you'll need to destroy the library when you're finished. When initializing the
35library you provide the `FPDF_LIBRARY_CONFIG` parameters to
36`FPDF_InitLibraryWithConfig`.
37
38```c
39#include <fpdfview.h>
40
41int main() {
42  FPDF_LIBRARY_CONFIG config;
43  config.version = 2;
44  config.m_pUserFontPaths = NULL;
45  config.m_pIsolate = NULL;
46  config.m_v8EmbedderSlot = 0;
47
48  FPDF_InitLibraryWithConfig(&config);
49
50  FPDF_DestroyLibrary();
51  return 0;
52}
53```
54
55Currently the `config.version` must be set to `2`. `m_pUserFontPaths` can be
56used to override the font paths searched by PDFium. If you wish to use your
57own font paths pass a `NULL` terminated list of `const char*` paths to use.
58
59`m_pIsolate` and `m_v8EmbedderSlot` are both used to configure the V8
60javascript engine. In the first case, you can provide an isolate through
61`m_pIsolate` for PDFium to use to store per-isolate data. Passing `NULL` will
62case PDFium to allocate a new isolate. `m_v8EmbedderSlot` is the embedder data
63slot to use in the v8::Isolate to store PDFium data. The value must be between
640 and v8::Internals::kNumIsolateDataSlots. Typically, 0 is a good choice.
65
66For more information on using Javascript see the [V8 Getting Started][pdfium-v8]
67guide.
68
69*** aside
70PDFium is built as a set of static libraries. You'll need to specify them all on
71the link line in order to compile. My build line was:
72
73```
74PDF_LIBS="-lpdfium -lfpdfapi -lfxge -lfpdfdoc -lfxcrt -lfx_agg \
75-lfxcodec -lfx_lpng -lfx_libopenjpeg -lfx_lcms2 -lfx_freetype -ljpeg \
76-lfdrm -lpwl -lbigint -lformfiller -ljavascript -lfxedit"
77PDF_DIR=<path/to/pdfium>
78
79clang -I $PDF_DIR/public -o init init.c -L $PDF_DIR/out/Debug -lstdc++ -framework AppKit $PDF_LIBS
80```
81
82The `-framework AppKit` as needed as I'm building on a Mac. Internally PDFium
83uses C++, which is why `-lstdc++` is required on the link line.
84***
85
86## Loading a Document
87
88One of the main objects in PDFium is the `FPDF_DOCUMENT`. The object will allow
89access to information from PDFs. There are four ways to to create a
90`FPDF_DOCUMENT`. `FPDF_CreateNewDocument` will create an empty object which
91can be used to create PDFs. For more information see the
92[PDF Editing Guide][pdfium-edit-guide].
93
94Loading an existing document is done in one of three ways: loading from file,
95loading from memory, or loading via a custom loader. In all three cases you'll
96provide a `FPDF_BYTESTRING` which is the password needed to unlock the PDF, if
97encrypted. If the file is not encrypted the password can be `NULL`.
98
99The two simplest methods are loading from file and loading from memory. To load
100from file, you'll provide the name of the file to open, including extension. For
101loading from memory you'll provide a data buffer containing the PDF and its
102length.
103
104```c
105FPDF_STRING test_doc = "test_doc.pdf";
106FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL);
107if (!doc) {
108  return 1;
109}
110
111FPDF_CloseDocument(doc);
112
113```
114
115In all three cases, `FPDF_LoadDocument`, `FPDF_LoadMemDocument`,
116`FPDF_LoadCustomDocument` a return of `NULL` indicates an error opening the
117document or that the file was not found.
118
119You can use `FPDF_GetLastError` to determine what went wrong.
120
121```c
122#include <fpdfview.h>
123#include <unistd.h>
124#include <stdio.h>
125
126int main() {
127  FPDF_LIBRARY_CONFIG config;
128  config.version = 2;
129  config.m_pUserFontPaths = NULL;
130  config.m_pIsolate = NULL;
131  config.m_v8EmbedderSlot = 0;
132
133  FPDF_InitLibraryWithConfig(&config);
134
135  FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL);
136  if (!doc) {
137    unsigned long err = FPDF_GetLastError();
138    fprintf(stderr, "Load pdf docs unsuccessful: ");
139    switch (err) {
140      case FPDF_ERR_SUCCESS:
141        fprintf(stderr, "Success");
142        break;
143      case FPDF_ERR_UNKNOWN:
144        fprintf(stderr, "Unknown error");
145        break;
146      case FPDF_ERR_FILE:
147        fprintf(stderr, "File not found or could not be opened");
148        break;
149      case FPDF_ERR_FORMAT:
150        fprintf(stderr, "File not in PDF format or corrupted");
151        break;
152      case FPDF_ERR_PASSWORD:
153        fprintf(stderr, "Password required or incorrect password");
154        break;
155      case FPDF_ERR_SECURITY:
156        fprintf(stderr, "Unsupported security scheme");
157        break;
158      case FPDF_ERR_PAGE:
159        fprintf(stderr, "Page not found or content error");
160        break;
161      default:
162        fprintf(stderr, "Unknown error %ld", err);
163    }
164    fprintf(stderr, ".\n");
165    goto EXIT;
166  }
167
168  FPDF_CloseDocument(doc);
169EXIT:
170  FPDF_DestroyLibrary();
171  return 0;
172```
173
174While the above are simple, the preferable technique is to use a custom loader.
175This makes it possible to load pieces of the document only as needed. This is
176useful for loading documents over the network.
177
178
179
180
181[chrome-plugin]: https://chromium.googlesource.com/chromium/src/+/master/pdf/
182[pdfium-public]: https://pdfium.googlesource.com/pdfium/+/master/public/
183[pdfium-v8]: /docs/v8-getting-started.md
184[pdfium-edit-guide]: /docs/pdfium-edit-guide.md
185