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