C technical notes

Learn about the specifics and technical details of the Pdftools SDK for C.

tip

For the full API reference for the Pdftools SDK, see the C API reference.

Namespaces, classes, and methods

The C programming language uses function prefixes and handles instead of namespaces and classes to model interfaces. All types in the Pdftools SDK, including handles and enumerations, are defined in the PdfTools_Types.h header file.

Types have the following naming scheme:

T‹prefix›_‹type›

where ‹prefix› is a shortened namespace prefix and ‹type› is the name of the type.

Similarly, the Pdftools SDK defines functions, collected in header files Pdftools_‹sub-prefix›.h with the following naming convention:

‹prefix›_‹type›_‹name›

where ‹type› is the class name and ‹name› is the name of the function.

Objects

Objects in the Pdftools SDK for C package interface are represented by object handles. Some types are disposable, which means you must close them by calling ‹prefix›_‹type›_Close. Release all other types by calling ‹prefix›_Release.

Type casting

The Pdftools SDK uses a class hierarchy to model parent-child relationships, where a parent type T‹prefix›_‹parentType› can have derived child types T‹prefix›_‹childType›.

Downcasting is necessary, for example, to call the functions of an object’s parent class. In this case, you can cast a handle of the child type using a C-style cast:

(T‹prefix›_‹parentType›*)pChildTypeHandle

Upcasting is also possible using a C-style cast. Before casting, you can determine the child type using the GetType function of the parent class:

(T‹prefix›_‹parentType›Type) iChildType = ‹prefix›_‹parentType›_GetType(pParentTypeHandle);

Properties

Properties are modeled with setter and getter functions ‹prefix›_‹type›_Get‹name› and ‹prefix›_‹type›_Set‹name›, where ‹name› is the name of the property.

Error handling

After calling a function, detect any errors as follows:

1. If the return type of the function is BOOL or a pointer, and the return value is FALSE or NULL respectively, call the PdfTools_GetLastError function. If this method returns ePdfTools_Error_Success, then no error occurred and the return value is legitimate.
2. If the return type of the function isn’t a Boolean or a pointer, call the PdfTools_GetLastError function. If this method returns ePdfTools_Error_Success, then no error occurred.

To get more information about the error, use the PdfToolsGetLastErrorMessage function.

Strings

All functions involving strings are provided in two different flavors:

• UTF-16 function with suffix W that uses WCHAR as the parameter type.
• Multi-byte character set function with suffix A that uses char as the parameter type. The concrete character set that’s used depends on the platform:
  • On Windows, the current ANSI code page (CP_ACP) is assumed.
  • On Linux or macOS, the current C encoding (LC_CTYPE) is used.

In addition to the function names with suffix, there’s a macro without suffix for each function pair. The macro resolves to one of the function variants:

• W if _UNICODE is defined.
• A if _UNICODE isn’t defined.

Example

Signature example of an API string property setter, where ‹name› stands for the property’s name:

// Multibyte encoding:
void ‹prefix›_‹type›_Set‹name›A(T‹prefix›_‹type›* pHandle, const char* szString);
// UTF-16:
void ‹prefix›_‹type›_Set‹name›W(T‹prefix›_‹type›* pHandle, const WCHAR* szString);
#ifdef _UNICODE
#define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›W
#else
#define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›A
#endif

String return values

In C, functions that return a string have a special behavior. Instead of returning the string, those functions take a buffer and a size as the last parameters and write into that buffer. The return value is the amount of data written to the buffer.

To determine the required buffer size, call the function with NULL as the buffer argument. Calling a function with a buffer size that’s too small results in an error.

Multibyte character set functions (with the suffix A) that return a string may fail to correctly encode the string in the encoding of the current operating system. In this case, the return value is 0 and no error code is set.

To prevent such failures, use the UTF-16 (W) functions on Windows or use operating systems with a Unicode code page.

Example

Signature example usage of an API string property getter:

size_t PdfTools_Sdk_GetVersionA(char* pBuffer, size_t nBufferSize);

size_t nBufferSize = PdfTools_Sdk_GetVersionA(NULL, 0);
char* pBuffer = malloc(nBufferSize * sizeof (char));
nBufferSize = PdfTools_Sdk_GetVersionA(pBuffer, nBufferSize);

Streams

Streams use a set of callbacks and a context pointer, grouped in a struct TPdfToolsSys_StreamDescriptor. An implementation for FILE* is provided in the header file PdfTools_PdfToolsSys.h. Search for the PdfToolsSysCreateFILEStreamDescriptor function.

Arrays

In C, arrays work similarly to strings. Array parameters consist of a pointer to a buffer and a size parameter specifying the number of array elements. Functions that return an array take a buffer and a size as last parameters and write into that buffer. The return value is the number of elements written to the buffer. A return value of (size_t)-1 indicates an error. To determine the required buffer size, call the function with NULL as the buffer argument. Calling the function with a buffer size that’s too small results in an error.

Lists

Every list type T‹prefix›_‹list› provides a subset of the following functions, where T‹prefix›_‹eltype› stands for the type of the contained elements:

Function	Description	Possible errors
int ‹prefix›_‹list›_GetCount(T‹prefix›_‹list›*)	Get the number of elements in the list.	ePdfTools_Error_IllegalState
T‹prefix›_‹eltype›* ‹prefix›_‹list›_Get(T‹prefix›_‹list›*, int index)	Get an element of the list.	ePdfTools_Error_IllegalState, ePdfTools_Error_IllegalArgument, ePdfTools_Error_UnsupportedOperation
BOOL ‹prefix›_‹list›_Add(T‹prefix›_‹list›*, T‹prefix›_‹eltype›*)	Add an element to the end of the list.	ePdfTools_Error_IllegalState, ePdfTools_Error_IllegalArgument, ePdfTools_Error_UnsupportedOperation

Maps

A map is a dictionary with unique keys and associated values. Currently, the only key type in all maps in the API is a string. Every map type T‹pre›_‹map› provides a subset of the following functions, where T‹pre›_‹eltype› is the type of the contained values.

Function	Description	Possible errors
int ‹pre›_‹map›_GetSize(T‹pre›_‹map›*)	The number of key-­value pairs in the map.	ePdfTools_Error_IllegalState
int ‹pre›_‹map›_GetBegin(T‹pre›_‹map›*)	Get the position of the first entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from ‹pre›_‹map›_GetEnd, then the position can be used to retrieve the map entry with ‹pre›_‹map›_GetKey and ‹pre›_‹map›_GetValue. Use ‹pre›_‹map›_GetNext to get the position of the next entry.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation
int ‹pre›_‹map›_GetEnd(T‹pre›_‹map›*)	Get the end position of the map. This position doesn’t correspond to an actual entry in the map. It must be used to determine whether the end of the map has been reached when using ‹pre›_‹map›_GetBegin and ‹pre›_‹map›_GetNext.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation
int ‹pre›_‹map›_GetNext(T‹pre›_‹map›*, int it)	Get the position of the next entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from ‹pre›_‹map›_GetEnd, then the position can be used to retrieve the map entry with ‹pre›_‹map›_GetKey and ‹pre›_‹map›_GetValue.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation
int ‹pre›_‹map›_GetA(T‹pre›_‹map›*, const char* szKey)	Get the position of a key in the map. If no error occurred, then the position can be used to get the corresponding value with ‹pre›_‹map›_GetValue.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation, ePdfTools_Error_IllegalArgument, ePdfTools_Error_NotFound
size_t ‹pre›_‹map›_GetKeyA(T‹pre›_‹map›*, int it, char*, size_t)	Get the key of the entry given a position.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation, ePdfTools_Error_IllegalArgument
T‹pre›_‹eltype›* ‹pre›_‹map›_GetValue(T‹pre›_‹map›*, int it)	Get the value of the entry given a position.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation, ePdfTools_Error_IllegalArgument
BOOL ‹pre›_‹map›_SetA(T‹pre›_‹map›*, const char* szKey, T‹pre›_‹eltype›* pValue)	Set the value of an entry for a given key. This operation invalidates all positions previously returned by ‹pre›_‹map›_GetBegin, ‹pre›_‹map›_GetEnd, ‹pre›_‹map›_GetNext, and ‹pre›_‹map›_Get.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation, ePdfTools_Error_IllegalArgument
BOOL ‹pre›_‹map›_SetValue(T‹pre›_‹map›*, int it, T‹pre›_‹eltype›* pValue)	Set the value of the entry at a position in the map.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation, ePdfTools_Error_IllegalArgument
BOOL ‹pre›_‹map›_Clear(T‹pre›_‹map›*)	Remove all entries from the map.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation, ePdfTools_Error_IllegalArgument
BOOL ‹pre›_‹map›_Remove(T‹pre›_‹map›*, int it)	Remove the entry at a position in the map.	ePdfTools_Error_IllegalState, ePdfTools_Error_UnsupportedOperation, ePdfTools_Error_IllegalArgument