Get started with C
This guide walks you through the steps to use a sample project, and then explains how to integrate the Toolbox add-on into your application with the C programming language.
Request trial or full license
Unlike the Pdftools SDK or the Pdftools SDK Shell Tool, the Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps:
- Reach out to 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.
Getting started with a sample project
Learn how to use the Toolbox add-on using a C sample project and extract all images and image masks from a PDF document.
Prerequisites
This sample project uses GCC toolset 4.8+ and CMake version 3.16 or higher.
Compile and run the sample
-
Download a sample project, and then unzip the file.
-
Copy your license key. For more information, review Find the license key.
-
In the
toolboximageextraction.c
file, replace the string"insert-license-key-here"
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 as you copied it. Include the less-than (
<
) and greater-than (>
) signs. -
In the command line, navigate to the root directory of the unzipped sample project, and then run the following command:
cmake .
-
Build the sample:
cmake --build .
-
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 sample 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 the following snippet with a placeholder and compare it to the last step of the previous procedure:
./toolboximageextraction INPUT_FILE OUTPUT_FILE
You can apply a similar procedure as described in this tutorial for other code samples. 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
-
Click the download link to get the latest version of the Toolbox add-on for C in a zip archive.
-
Unzip the file on your machine into a local directory recommended for your operating system. For example:
- Windows
- Linux
- macOS
C:\Program Files\PDF Tools AG\
Included subdirectories are:
Subdirectory Description lib
Runtime executable binaries and runtime import libraries:
win-x86\PdfTools_Toolbox.dll
andwin-x86\PdfTools_Toolbox.lib
for 32-bit Windows
win-x64\PdfTools_Toolbox.dll
andwin-x64\PdfTools_Toolbox.lib
for 64-bit Windowsinclude
Header files to include in your C or C++ project. The main header PdfTools_Toolbox.h
includes all the other headers./opt/pdftools.com/
Included subdirectories are:
Subdirectory Description lib
Runtime executable binaries for all supported platforms: linux-x64/libPdfTools_Toolbox.so
for 64-bit Linuxinclude
Header files to include in your C or C++ project. The main header PdfTools_Toolbox.h
includes all the other headers./opt/pdftools.com/
Included subdirectories are:
Subdirectory Description lib
Runtime executable binaries:
osx-x64/libPdfTools_Toolbox.dylib
for 64-bit (Intel) macOS
osx-arm64/libPdfTools_Toolbox.dylib
for ARM (Apple Silicon) macOSinclude
Header files to include in your C or C++ project. The main header PdfTools_Toolbox.h includes all the other headers. -
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
- Linux
- macOS
Add the
lib\win-x64
orlib\win-x86
subdirectory to the%PATH%
environment variable.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/libPdfTools_Toolbox.so /usr/lib
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/libPdfTools_Toolbox.dylib /usr/lib
Initialize the SDK
The Toolbox add-on requires a license key even in a trial version (unlike the Pdftools SDK which you can try without a license key). To initialize the Toolbox add-on with your license key, follow these steps:
-
Copy your license key. For more information, review Find the license key.
-
Find the following code, and then replace the
insert-license-key-here
with the value of 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 as you copied it. Include the less-than (
<
) and greater-than (>
) signs.
Without a valid license key the Toolbox add-on returns an error. 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 Toolbox add-on, call the Uninitialize
function to unload the library correctly:
// Uninitialize library
Ptx_Uninitialize();
Implement your use case
- Find more use cases and sample projects at the Toolbox add-on Code samples page.
- For more technical information about the Toolbox add-on for C, consult the C technical notes.