Skip to main content

Get started with C

This guide walks you through the steps to use a code example, and then explains how to integrate the Toolbox add-on into your application with the C programming language.

Request trial or full license​

The Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps:

  1. Contact the sales team through the Contact page and mark the Toolbox add-on as the product of your interest for a trial license.

If you already have a license key and you need to copy it, review Find the license key.

Get started with a sample project​

Learn how to use the Toolbox add-on using a C code example. The ImageExtraction example extracts all images and image masks from a PDF document. Use similar steps to run any other code example from the toolbox-examples-c repository.

Prerequisites​

This code example uses GCC toolset 4.8+ and CMake version 3.16 or higher.

Compile and run the sample​

  1. Clone the toolbox-examples-c repository:

    git clone https://github.com/pdf-tools/toolbox-examples-c.git

  2. Navigate to the ImageExtraction code example:

    cd toolbox-examples-c/ImageExtraction

  3. Find your license key. For more information, review Find the license key.

  4. In the toolboximageextraction.c file, replace the "insert-license-key-here" placeholder in the Ptx_Sdk_Initialize call with your license key:

    GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(Ptx_Sdk_Initialize(_T("insert-license-key-here"), NULL),
                                      _T("Failed to set license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff,
                                      Ptx_GetLastError());

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

  5. Configure the project:

    cmake .

  6. Build the sample:

    cmake --build .

  7. To extract all images and image masks from the sample PDF file ImageCollection.pdf to the output directory /tmp/images, run:

    ./toolboximageextraction ImageCollection.pdf /tmp/images

The code example takes:

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

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

./toolboximageextraction INPUT_FILE OUTPUT_FILE
note

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

Integrate the Toolbox add-on into your application​

Integrate and initialize the Toolbox add-on into your application by following the instructions in the next sections.

Add the Toolbox add-on to your project​

  1. Click the download link to get the latest version of the Toolbox add-on for C in a zip archive.

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

    C:\Program Files\PDF Tools AG\

    Included subdirectories are:

    SubdirectoryDescription
    libRuntime executable binaries and runtime import libraries:
    • win-x86\PdfTools_Toolbox.dll and win-x86\PdfTools_Toolbox.lib for 32-bit Windows.
    • win-x64\PdfTools_Toolbox.dll and win-x64\PdfTools_Toolbox.lib for 64-bit Windows.
    • win-arm64\PdfTools_Toolbox.dll and win-arm64\PdfTools_Toolbox.lib for 64-bit Windows ARM.
    includeHeader files to add to your C or C++ project. The main header PdfTools_Toolbox.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:

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

Initialize the Toolbox add-on​

The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK). Without a valid license, every Toolbox add-on function call fails with LicenseError: No license key was set.

Getting a license key

Contact the Pdftools sales team through the Contact page to get a trial or full license.

To initialize the Toolbox add-on with your license key, follow these steps:

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

  2. Call Ptx_Sdk_Initialize once at application startup, before any other Toolbox add-on function call:

    GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(Ptx_Sdk_Initialize(_T("YOUR_LICENSE_KEY"), NULL),
                                      _T("Failed to set license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff,
                                      Ptx_GetLastError());

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

To get a working reference with the Ptx_Sdk_Initialize function, follow these steps:

  1. Clone the toolbox-examples-c repository and navigate to a sample directory. For example, toolbox-examples-c/ImageExtraction.
  2. Open the main C file and find the Ptx_Sdk_Initialize call. For example, the ImageExtraction C sample includes it in toolboximageextraction.c.
  3. Replace the "insert-license-key-here" placeholder with your license key.

Uninitialize the Toolbox add-on​

After processing files with the Toolbox add-on, call Ptx_Uninitialize to unload the library correctly:

// Uninitialize library
Ptx_Uninitialize();

Implement your use case​

  • Find more use cases and code examples on the Toolbox add-on Code samples page.
  • For more technical information about the Toolbox add-on for C, consult the C technical notes.