From 23863e4c86a99381c1bd83e76c9055b10a8bf6c4 Mon Sep 17 00:00:00 2001 From: dsinclair Date: Fri, 1 Apr 2016 13:54:37 -0700 Subject: Starting to add some documentation. This CL adds the beginnings of a Geting Started document for PDFium and adds the navbar.md file to get navigation on the markdown files when rendered by Gitiles. Review URL: https://codereview.chromium.org/1840793002 --- docs/getting-started.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 docs/getting-started.md (limited to 'docs/getting-started.md') diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000000..b80e56683b --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,185 @@ +# Getting Started with PDFium + +[TOC] + +This guide walks through some examples of using the PDFium library. For an +example of using PDFium see the [Chromium PDF Plugin][chrome-plugin]. + +## Prerequisites + +You will need the PDFium library on your computer. You can see the +[README](/README.md) for instructions on getting and installing PDFium. + +*** note +You must compile PDFium without both V8 and XFA support for the examples +here to work. V8 can be compiled out by providing +`GYP_DEFINES="pdf_enable_v8=0 pdf_enable_xfa=0" build/gyp_pdfium`. + +See the [V8 Getting Started][pdfium-v8] guide for how to +initialize PDFium when V8 is compiled into the binary. +*** + +## PDFium Headers + +PDFium's API has been broken up over several headers. You only need to include +the headers for functionality you use in your application. The full set of +headers can be found in the [public/ folder of the repository][pdfium-public]. + +In all cases you'll need to include `fpdfview.h` as it defines the needed +methods for initialization and destruction of the library. + +## Initializing PDFium + +The first step to using PDFium is to initialize the library. Having done so, +you'll need to destroy the library when you're finished. When initializing the +library you provide the `FPDF_LIBRARY_CONFIG` parameters to +`FPDF_InitLibraryWithConfig`. + +```c +#include + +int main() { + FPDF_LIBRARY_CONFIG config; + config.version = 2; + config.m_pUserFontPaths = NULL; + config.m_pIsolate = NULL; + config.m_v8EmbedderSlot = 0; + + FPDF_InitLibraryWithConfig(&config); + + FPDF_DestroyLibrary(); + return 0; +} +``` + +Currently the `config.version` must be set to `2`. `m_pUserFontPaths` can be +used to override the font paths searched by PDFium. If you wish to use your +own font paths pass a `NULL` terminated list of `const char*` paths to use. + +`m_pIsolate` and `m_v8EmbedderSlot` are both used to configure the V8 +javascript engine. In the first case, you can provide an isolate through +`m_pIsolate` for PDFium to use to store per-isolate data. Passing `NULL` will +case PDFium to allocate a new isolate. `m_v8EmbedderSlot` is the embedder data +slot to use in the v8::Isolate to store PDFium data. The value must be between +0 and v8::Internals::kNumIsolateDataSlots. Typically, 0 is a good choice. + +For more information on using Javascript see the [V8 Getting Started][pdfium-v8] +guide. + +*** aside +PDFium is built as a set of static libraries. You'll need to specify them all on +the link line in order to compile. My build line was: + +``` +PDF_LIBS="-lpdfium -lfpdfapi -lfxge -lfpdfdoc -lfxcrt -lfx_agg \ +-lfxcodec -lfx_lpng -lfx_libopenjpeg -lfx_lcms2 -lfx_freetype -ljpeg \ +-lfx_zlib -lfdrm -lpdfwindow -lbigint -lformfiller -ljavascript \ +-lfxedit" +PDF_DIR= + +clang -I $PDF_DIR/public -o init init.c -L $PDF_DIR/out/Debug -lstdc++ -framework AppKit $PDF_LIBS +``` + +The `-framework AppKit` as needed as I'm building on a Mac. Internally PDFium +uses C++, which is why `-lstdc++` is required on the link line. +*** + +## Loading a Document + +One of the main objects in PDFium is the `FPDF_DOCUMENT`. The object will allow +access to information from PDFs. There are four ways to to create a +`FPDF_DOCUMENT`. `FPDF_CreateNewDocument` will create an empty object which +can be used to create PDFs. For more information see the +[PDF Editing Guide][pdfium-edit-guide]. + +Loading an existing document is done in one of three ways: loading from file, +loading from memory, or loading via a custom loader. In all three cases you'll +provide a `FPDF_BYTESTRING` which is the password needed to unlock the PDF, if +encrypted. If the file is not encrypted the password can be `NULL`. + +The two simplest methods are loading from file and loading from memory. To load +from file, you'll provide the name of the file to open, including extension. For +loading from memory you'll provide a data buffer containing the PDF and its +length. + +```c +FPDF_STRING test_doc = "test_doc.pdf"; +FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL); +if (!doc) { + return 1; +} + +FPDF_CloseDocument(doc); + +``` + +In all three cases, `FPDF_LoadDocument`, `FPDF_LoadMemDocument`, +`FPDF_LoadCustomDocument` a return of `NULL` indicates an error opening the +document or that the file was not found. + +You can use `FPDF_GetLastError` to determine what went wrong. + +```c +#include +#include +#include + +int main() { + FPDF_LIBRARY_CONFIG config; + config.version = 2; + config.m_pUserFontPaths = NULL; + config.m_pIsolate = NULL; + config.m_v8EmbedderSlot = 0; + + FPDF_InitLibraryWithConfig(&config); + + FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL); + if (!doc) { + unsigned long err = FPDF_GetLastError(); + fprintf(stderr, "Load pdf docs unsuccessful: "); + switch (err) { + case FPDF_ERR_SUCCESS: + fprintf(stderr, "Success"); + break; + case FPDF_ERR_UNKNOWN: + fprintf(stderr, "Unknown error"); + break; + case FPDF_ERR_FILE: + fprintf(stderr, "File not found or could not be opened"); + break; + case FPDF_ERR_FORMAT: + fprintf(stderr, "File not in PDF format or corrupted"); + break; + case FPDF_ERR_PASSWORD: + fprintf(stderr, "Password required or incorrect password"); + break; + case FPDF_ERR_SECURITY: + fprintf(stderr, "Unsupported security scheme"); + break; + case FPDF_ERR_PAGE: + fprintf(stderr, "Page not found or content error"); + break; + default: + fprintf(stderr, "Unknown error %ld", err); + } + fprintf(stderr, ".\n"); + goto EXIT; + } + + FPDF_CloseDocument(doc); +EXIT: + FPDF_DestroyLibrary(); + return 0; +``` + +While the above are simple, the preferable technique is to use a custom loader. +This makes it possible to load pieces of the document only as needed. This is +useful for loading documents over the network. + + + + +[chrome-plugin]: https://chromium.googlesource.com/chromium/src/+/master/pdf/ +[pdfium-public]: https://pdfium.googlesource.com/pdfium/+/master/public/ +[pdfium-v8]: /docs/v8-getting-started.md +[pdfium-edit-guide]: /docs/pdfium-edit-guide.md -- cgit v1.2.3