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, one
34must destroy the library with `FPDF_DestroyLibrary()` when finished. When
35initializing the library, 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`. Older versions works for
56backwards compatibility, but will be deprecated eventually.
57
58`m_pUserFontPaths` can be used to override the font paths searched by PDFium. To
59use a custom font paths, pass a `NULL` terminated list of `const char*` paths to
60use.
61
62`m_pIsolate` and `m_v8EmbedderSlot` are both used to configure the V8
63JavaScript engine. For the V8 isolate, either provide an isolate through
64`m_pIsolate` for PDFium to use to store per-isolate data, or pass `NULL` to tell
65PDFium to allocate a new isolate. `m_v8EmbedderSlot` is the embedder data slot
66to use in the v8::Isolate to store PDFium data. The value must be in the range
67[0, `v8::Internals::kNumIsolateDataSlots`). Typically, 0 is a good choice.
68
69For more information on using Javascript see the [V8 Getting Started][pdfium-v8]
70guide.
71
72*** aside
73PDFium is built as a set of static libraries. You'll need to specify them all on
74the link line in order to compile. My build line was:
75
76```
77PDF_LIBS="-lpdfium -lfpdfapi -lfxge -lfpdfdoc -lfxcrt -lfx_agg \
78-lfxcodec -lfx_lpng -lfx_libopenjpeg -lfx_lcms2 -lfx_freetype -ljpeg \
79-lfdrm -lpwl -lbigint -lformfiller -ljavascript -lfxedit"
80PDF_DIR=<path/to/pdfium>
81
82clang -I $PDF_DIR/public -o init init.c -L $PDF_DIR/out/Debug -lstdc++ -framework AppKit $PDF_LIBS
83```
84
85The `-framework AppKit` as needed as I'm building on a Mac. Internally PDFium
86uses C++, which is why `-lstdc++` is required on the link line.
87***
88
89## Loading a Document
90
91One of the main objects in PDFium is the `FPDF_DOCUMENT`. The object will allow
92access to information from PDFs. There are four ways to to create a
93`FPDF_DOCUMENT`. `FPDF_CreateNewDocument` will create an empty object which
94can be used to create PDFs. For more information see the
95[PDF Editing Guide][pdfium-edit-guide].
96
97Loading an existing document is done in one of three ways: loading from file,
98loading from memory, or loading via a custom loader. In all three cases you'll
99provide a `FPDF_BYTESTRING` which is the password needed to unlock the PDF, if
100encrypted. If the file is not encrypted the password can be `NULL`.
101
102The two simplest methods are loading from file and loading from memory. To load
103from file, you'll provide the name of the file to open, including extension. For
104loading from memory you'll provide a data buffer containing the PDF and its
105length.
106
107```c
108FPDF_STRING test_doc = "test_doc.pdf";
109FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL);
110if (!doc) {
111  return 1;
112}
113
114FPDF_CloseDocument(doc);
115
116```
117
118In all three cases, `FPDF_LoadDocument`, `FPDF_LoadMemDocument`,
119`FPDF_LoadCustomDocument` a return of `NULL` indicates an error opening the
120document or that the file was not found.
121
122You can use `FPDF_GetLastError` to determine what went wrong.
123
124```c
125#include <fpdfview.h>
126#include <unistd.h>
127#include <stdio.h>
128
129int main() {
130  FPDF_LIBRARY_CONFIG config;
131  config.version = 2;
132  config.m_pUserFontPaths = NULL;
133  config.m_pIsolate = NULL;
134  config.m_v8EmbedderSlot = 0;
135
136  FPDF_InitLibraryWithConfig(&config);
137
138  FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL);
139  if (!doc) {
140    unsigned long err = FPDF_GetLastError();
141    fprintf(stderr, "Load pdf docs unsuccessful: ");
142    switch (err) {
143      case FPDF_ERR_SUCCESS:
144        fprintf(stderr, "Success");
145        break;
146      case FPDF_ERR_UNKNOWN:
147        fprintf(stderr, "Unknown error");
148        break;
149      case FPDF_ERR_FILE:
150        fprintf(stderr, "File not found or could not be opened");
151        break;
152      case FPDF_ERR_FORMAT:
153        fprintf(stderr, "File not in PDF format or corrupted");
154        break;
155      case FPDF_ERR_PASSWORD:
156        fprintf(stderr, "Password required or incorrect password");
157        break;
158      case FPDF_ERR_SECURITY:
159        fprintf(stderr, "Unsupported security scheme");
160        break;
161      case FPDF_ERR_PAGE:
162        fprintf(stderr, "Page not found or content error");
163        break;
164      default:
165        fprintf(stderr, "Unknown error %ld", err);
166    }
167    fprintf(stderr, ".\n");
168    goto EXIT;
169  }
170
171  FPDF_CloseDocument(doc);
172EXIT:
173  FPDF_DestroyLibrary();
174  return 0;
175```
176
177While the above are simple, the preferable technique is to use a custom loader.
178This makes it possible to load pieces of the document only as needed. This is
179useful for loading documents over the network.
180
181
182
183
184[chrome-plugin]: https://chromium.googlesource.com/chromium/src/+/master/pdf/
185[pdfium-public]: https://pdfium.googlesource.com/pdfium/+/master/public/
186[pdfium-v8]: /docs/v8-getting-started.md
187[pdfium-edit-guide]: /docs/pdfium-edit-guide.md
188