C technical notes

Learn about specifics and technical details about 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. In the PdfTools SDK, all the types used, 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, meaning that 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, a handle of the child type can be cast using a simple C-style cast:

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

Upcasting is also possible using a C-style cast. Prior to casting, the child type of the handle can be determined 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 has occurred and the return value is legitimate.
2. If the return type of the function is not a Boolean or a pointer, call the PdfTools_GetLastError function. If this method returns ePdfTools_Error_Success, then no error has occurred.

More information about the error can be acquired from 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 is 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 is not 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 is 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 (Error handling is omitted):

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 are modeled by means of 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 is 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 does not 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