PDF Toolbox SDK for C

The PDF Toolbox SDK for C lets you create PDF files using C.

note

For more information on the document model, graphics model, and thread safety, see About the PDF Toolbox SDK.

Namespaces, classes, and methods

In most languages, namespaces and classes are used to model the interfaces. The exception is C, where this is modeled with function prefixes and functions operating on handles.

The PDF Toolbox SDK defines all its used types such as handles and enumerations in the PdfToolbox_Types.h header file.

Types are named according to the following naming scheme:

T‹prefix›_‹name›

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

Similarly, the PDF Toolbox SDK defines functions, collected in header files PdfToolbox_‹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.

Library initialization

The first method called must be Ptx_Initialize. Failing to invoke this function results in undefined behavior. Similarly, the last method must be Ptx_Uninitialize.

Before calling any of the other functions, a license key must be set by calling Ptx_Sdk_Initialize.

Objects

Objects in the C interface are represented by object handles. Some types are disposable, which means that they must be closed by calling ‹prefix›_‹type›_Close. All other types must be released by calling ‹prefix›_Release.

Type casting

The PDF Toolbox SDK uses a hierarchical class hierarchy, 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 casted 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 (a C# term) 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 having called a function, an error should be detected as follows:

1. If the function’s return type isBOOL or a pointer and the return value isFALSE or NULL, respectively, then an error may have occurred. Then Ptx_GetLastError must be called. If this method returns ePtx_Error_Success, no error has occurred and the return value is legitimate.
2. If the function’s return type is other than Boolean or a pointer, then Ptx_GetLastError must be called. If this method returns ePtx_Error_Success, then no error has occurred.

More information about the error can be acquired from PtxGetLastErrorMessage.

Strings

All functions involving strings are provided in two different flavors:

• UTF-16 function with suffix W, using WCHAR as parameter type.
• Multi-byte character set function with suffix A, using char as 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 effective function names with suffix, there’s a macro without suffix for each function pair. It either resolves to the W variant (if _UNICODE is defined), or to the A variant (if _UNICODE is not defined).

Example: Signature of an API string property setter, where ‹String› 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 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, the function has to be called with NULL as buffer argument. Calling the function with a buffer size that is too small results in an error.

Multi-byte character set functions (with suffix A) that return a string can fail to encode the string in the current operating systems’ encoding. In case of such a failure, the return value is 0 and no error code is set. To prevent such failures, you should use the UTF-16 (W) functions on Windows or use operating systems with a Unicode code page.

Example: Signature and usage of an API string property getter (Error handling is omitted)

size_t Ptx_Sdk_GetVersionA(char* pBuffer, size_t nBufferSize);

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

Streams

Streams are modeled by means of a set of callbacks and a context pointer, grouped in a struct TPtxSys_StreamDescriptor. An implementation for FILE* is provided in the header file PdfToolbox_PtxSys.h. (Search for function PtxSysCreateFILEStreamDescriptor.)

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, the function has to be called with NULL as 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.	ePtx_Error_IllegalState
T‹prefix›_‹eltype›* ‹prefix›_‹list›_Get(T‹prefix›_‹list›*, int index)	Get an element of the list.	ePtx_Error_IllegalState, ePtx_Error_IllegalArgument, ePtx_Error_UnsupportedOperation
BOOL ‹prefix›_‹list›_Add(T‹prefix›_‹list›*, T‹prefix›_‹eltype›*)	Add an element to the end of the list.	ePtx_Error_IllegalState, ePtx_Error_IllegalArgument, ePtx_Error_UnsupportedOperation

Enumerables

Enumerables (C# jargon) are lists that only allow iterating. For every enumerable type T‹prefix›_‹type›, an additional iterator type T‹prefix›_‹type›Iterator is defined. Every enumerable type provides the following function:

Function	Description	Possible errors
T‹prefix›_‹type›Iterator* ‹prefix›_‹type›_GetIterator(T‹prefix›_‹type›*)	Get an iterator for this enumerable.	ePtx_Error_IllegalState

Every iterator type provides the following functions, where T‹prefix›_‹eltype› is the type of the contained element:

Function	Description	Possible errors
BOOL ‹prefix›_‹type›Iterator_MoveNext(T‹prefix›_‹type›Iterator*)	Move the iterator to the next element. Returns: 1 if the current value is available, 0 if the end has been reached and the current value is NULL.	ePtx_Error_IllegalState
T‹prefix›_‹eltype›* ‹prefix›_‹type›Iterator_GetValue(T‹prefix›_‹type›Iterator*)	Get the current element or NULL if no elements are left.	ePtx_Error_IllegalState

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.	ePtx_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.	ePtx_Error_IllegalState, ePtx_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.	ePtx_Error_IllegalState, ePtx_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.	ePtx_Error_IllegalState, ePtx_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.	ePtx_Error_IllegalState, ePtx_Error_UnsupportedOperation, ePtx_Error_IllegalArgument, ePtx_Error_NotFound
size_t ‹pre›_‹map›_GetKeyA(T‹pre›_‹map›*, int it, char*, size_t)	Get the key of the entry given a position.	ePtx_Error_IllegalState, ePtx_Error_UnsupportedOperation, ePtx_Error_IllegalArgument
T‹pre›_‹eltype›* ‹pre›_‹map›_GetValue(T‹pre›_‹map›*, int it)	Get the value of the entry given a position.	ePtx_Error_IllegalState, ePtx_Error_UnsupportedOperation, ePtx_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.	ePtx_Error_IllegalState, ePtx_Error_UnsupportedOperation, ePtx_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.	ePtx_Error_IllegalState, ePtx_Error_UnsupportedOperation, ePtx_Error_IllegalArgument
BOOL ‹pre›_‹map›_Clear(T‹pre›_‹map›*)	Remove all entries from the map.	ePtx_Error_IllegalState, ePtx_Error_UnsupportedOperation, ePtx_Error_IllegalArgument
BOOL ‹pre›_‹map›_Remove(T‹pre›_‹map›*, int it)	Remove the entry at a position in the map.	ePtx_Error_IllegalState, ePtx_Error_UnsupportedOperation, ePtx_Error_IllegalArgument