Get started with C

This guide walks you through the steps to use a sample project, and then explains how to integrate the Pdftools SDK into your application with the C programming language.

Getting started with a sample project

Learn how to use the Pdftools SDK using a C sample project and convert a PDF file to an image.

Prerequisites

This sample project uses GCC toolset 4.8+ and CMake version 3.16 or higher.

Compile and run the sample

1. Download a sample project, and then unzip the file.

2. Navigate to the root directory of the unzipped sample project, and then run:

   cmake .

3. Build the sample:

   cmake --build .

4. The sample project contains a PDF file PdfPrimerWhitePaper.pdf. To render it in multi-page TIFF image format, run:

   ./pdftoolspdf2imgsimple PdfPrimerWhitePaper.pdf PdfPrimerWhitePaper.tiff

The code sample takes:

• The input and output files represented as a file name or a file path with the file name.
• Both file paths (input and output) can be relative or absolute.

Review the following snippet with a placeholder and compare it to the last step of the previous procedure:

./pdftoolspdf2imgsimple INPUT_FILE OUTPUT_FILE

note

You can apply a similar procedure as described in this tutorial for other code samples. For more information, see Code samples page.

Integrate the SDK into your application

Integrate and initialize the Pdftools SDK into your application by following the instructions in the next sections.

Add the SDK to your project

1. Click the download link to get the latest version of the Pdftools SDK for C in a zip archive.

   Optional: For older Linux distributions running glibc 2.12+, download the SDK from a separate download.

2. Unzip the file on your machine into a local directory recommended for your operating system. For example:

   Windows

   C:\Program Files\PDF Tools AG\

   Included subdirectories are:

   Subdirectory	Description
   ~	Containts important information in the README.md file.
   lib	Runtime executable binaries and runtime import libraries: win-x86\PdfToolsSdk.dll and win-x86\PdfToolsSdk.lib for 32-bit Windows win-x64\PdfToolsSdk.dll and win-x64\PdfToolsSdk.lib for 64-bit Windows
   include	Header files to include in your C or C++ project. The main header PdfTools.h includes all the other headers.

   Linux

   /opt/pdftools.com/

   Included subdirectories are:

   Subdirectory	Description
   ~	Contains important information in the README.md file.
   lib	Runtime executable binaries for all supported platforms: linux-x64/libPdfToolsSdk.so for 64-bit Linux
   include	Header files to include in your C or C++ project. The main header PdfTools.h includes all the other headers.

   macOS

   /opt/pdftools.com/

   Included subdirectories are:

   Subdirectory	Description
   ~	Contains important information in the README.md file.
   lib	Runtime executable binaries: osx-x64/libPdfToolsSdk.dylib for 64-bit (Intel) macOS osx-arm64/libPdfToolsSdk.dylib for ARM (Apple Silicon) macOS
   include	Header files to include in your C or C++ project. The main header PdfTools.h includes all the other headers.

3. Optional: The native libraries must be available in your compiler's library path. This step is only required if your build process doesn't resolve it automatically:

   Windows

   Add the lib\win-x64 or lib\win-x86 subdirectory to the %PATH% environment variable.

   Linux

   Create a link to the shared library from one of the standard library directories, e.g:

   ln -s /opt/pdf-tools.com/lib/linux-x64/libPdfToolsSdk.so /usr/lib

   macOS

   Create a link to the shared library from one of the standard library directories. For example (for an Intel processor Mac):

   ln -s /opt/pdf-tools.com/lib/osx-x64/libPdfToolsSdk.dylib /usr/lib

Initialize the SDK

To initialize the Pdftools SDK with your license key, follow these steps:

1. Copy your license key. For more information, review Find the license key.

2. Replace the <PDFSDK,V1,include-your-key-here> in the following function with the value of your license key:

   // Initialize library
   PdfTools_Initialize();
   
   // Optional: Without a license key the Pdftools SDK returns watermarked results.
   // Initialize the Pdftools SDK with a license key to remove the watermark.
   // The Pdftools SDK returns an error if you use an invalid license key.
   GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfTools_Sdk_Initialize(_T("$<PDFSDK,V1,include-your-key-here>$"), NULL), _T("Failed to set the license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError());

   Use the license key in the same format as you copied it. Include the less-than (<) and greater-than (>) signs.

Try it without license key

You can try the Pdftools SDK without a license with watermarked results. For more information, review Pdftools SDK license management. Without a valid license key the output files are watermarked. Get in touch with the Pdftools sales team through the Contact page to get a full license.

Uninitialize the SDK

After processing files with the Pdftools SDK, call the Uninitialize function to unload the library correctly:

// Uninitialize library
PdfTools_Uninitialize();

Implement your use case

• Find more use cases and sample projects at the Code samples page.
• For more technical information about the Pdftools SDK for C, consult the C technical notes.