CIB pdf toolbox technical guide (EN)

12. Technical interfaces

This chapter gives a quick overview about the available API and its parameters. In general, you can use the CibPdfSetProperty function to set your desired parameters in the CIB pdf toolbox and then call a CibPdfJoin or CibPdfMerge function.

CibPdfSetProperty
CibPdfGetProperty
CibPdfJoin
CibPdfMerge
CibPdfGetVersion
CibPdfGetError
CibPdfGetErrorText
CibPdfGetLastError
CibPdfGetLastErrorText
CibPdfEventNotifier
CibPDFshowPageSetupDialog
CibPdfShowPrintDialog
CibPdfShowPrintSetupDialog
MemoryOutputCallback
AbortDocCallback
CibPdfJobCreate
CibPdfJobFree
CibPdfJobMerge
CibPdfJobJoin
CibPdfJobShowPrintDialog
CibPdfJobShowPrintSetupDialog
CibPdfJobShowPageSetupDialog
CibPdfJobGetProperty
CibPdfJobSetProperty
CibPdfJobGetPropertyW
CibPdfJobSetPropertyW
CibPdfJobGetError
CibPdfJobGetErrorText
CibPdfJobCancel

CibPdfSetProperty

BOOL EXPORTFUNC CibPdfSetProperty (const char* a_pOptionName,

void* a_pOptionValue)

This function sets properties for the CIB pdf toolbox. The properties InputFilename, OutputFilename and Data must be set before calling CibPdfMerge. The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

Parameters:

Type	Variable	Description
char*	a_pOptionName	Name of the desired configuration parameter
void*	a_pOptionValue	Value of the desired configuration parameter
		Attention: Notice the data type of the respective value.

CibPdfGetProperty

BOOL EXPORTFUNC CibPdfGetProperty(const char* a_pOptionName,

void* a_pOptionValue, long a_lBufferLength)

This function can be used to query the currently set properties of the CIB pdf toolbox component. The function returns TRUE if no error occurred. Otherwise FALSE will be returned.

Parameters:

Type	Variable	Description
char*	a_pOptionName	Name of the desired configuration parameter
void*	a_pOptionValue	Value of the desired configuration parameter
long	a_lBufferLength	Length of the buffer for the option content

CibPdfJoin

BOOL EXPORTFUNC CibPdfJoin()

This method starts the join functionality. With the function CibPdfSetProperty at least the properties InputFilename and OutputFilename have to be set before. When joining encrypted PDFs, the corresponding owner password has to be specified for each file. This can be done using the property EncryptOwnerPassword. The function has no parameters. It returns TRUE if no error occurred when executing this function. Otherwise FALSE will be returned.

CibPdfMerge

BOOL EXPORTFUNC CibPdfMerge()

This method starts the merge process. With the function CibPdfSetProperty at least the properties InputFilename, OutputFilename and Data have to be set before. The function has no parameters. It returns TRUE if no error occurred when executing this function. Otherwise FALSE will be returned.

CibPdfGetVersion

BOOL EXPORTFUNC CibPdfGetVersion(unsigned long *a_iVersion)

The function returns the current version number of the Cib pdfm component. This allows you to ensure that a minimum version is available in your application, for example, if you use special program features that have only been made available since a certain release. The function returns TRUE if no error occurred. Otherwise FALSE will be returned.

Parameters:

Type	Variable	Description
unsigned long &	a_lVersion	a_lVersion returns the current version number of the CIB pdfm component. The unsigned long-value returns the information in two ranges. The first two bytes contain the version counter of the main release. The bytes 3 and 4 contain the corresponding current release counter. Depending on the programming language, the high and low ranges have to be considered accordingly.

CibPdfGetError

BOOL EXPORTFUNC CibPdfGetError (CibPdfHandle a_hJob, int*a_pErrorCode)

With this function the current error text for a job can be queried after a function has been executed.

Parameters:

Type	Variable	Description
long	a_hJob	Handle of the request to be executed
int *	a_iError	Placeholder for the current error code

CibPdfGetErrorText

BOOL EXPORTFUNC CibPdfGetErrorText(int a_iErrorId, char* a_pTextBuffer,

long a_lBufferLength)

This function can be used to query the current error text for a job after a function has been executed. The function returns TRUE if no error occurred while retrieving the error text. Otherwise FALSE will be returned.

Parameters:

Type	Variable	Description
int	a_iErrorId	error code
char	a_pTextBuffer	Text buffer for the error text
long	a_lBufferLength	Length of the available text buffer

CibPdfGetLastError

BOOL EXPORTFUNC CibPdfGetLastError(int *a_iError)

With this function the current error status of the CIB pdf component can be queried after the execution of various functions. The function returns TRUE if no error occurred while executing this function. Otherwise FALSE will be returned.

Parameters:

Type	Variable	Description
int	a_iError	Place holder for the current error code

CibPdfGetLastErrorText

BOOL EXPORTFUNC CibPdfGetLastErrorText(char* a_pTextBuffer,

long a_lBufferLength)

With this function the current error text of the CIB pdf toolbox component can be queried after a function has been executed. The function returns TRUE if no error occurred while retrieving the error text. Otherwise FALSE will be returned.

Parameters:

Type	Variable	Description
int	a_pTextBuffer	Text buffer for the error text
long	a_lBufferLength	Length of the available text buffer

CibPdfEventNotifier

(from CIB pdf toolbox Version 1.24.0 onwards)

To enable the use of callbacks, a derived class must be implemented in the used application for the CibPdfEventNotifier class defined in "CibPdfEventNotifier.h" of the CIB pdf toolbox.

Additionally, their abstract methods
CibPdfEventNotifier::OnPageStart(...) and
CibPdfEventNotifier::OnPageImageOutput(...),
have to be implemented to be able to retrieve the callback data.

The pointer to the instance of the derived class (converted to an integer and represented as a string) is assigned to the "EventNotifier" property.

The method „CibPdfEventNotifier::OnPageStart(...)“is used by the CIB pdf toolbox at the beginning of the processing of each page. It returns the „CibPdfEventPageInfo“ data structure and a flag that can be used to abort further processing.

The method „CibPdfEventNotifier::OnPageImageOutput(...)“ is used by the CIB pdf toolbox after rendering a page and before saving the image. It returns the „CibPdfEventPageImageInfo“ data structure and a flag that can prevent saving the image.

class CibPdfEventNotifier
{
public:
   virtual void OnPageStart(CibPdfEventPageInfo* pageInfo, bool& abort) = 0;
   virtual void OnPageImageOutput(CibPdfEventPageImageInfo* imageInfo, bool&
   skipFileOutput) = 0;
};

CibPdfEventPageInfo

The "CibPdfEventPageInfo" data structure delivered by the CIB pdf toolbox at the beginning of the processing of each page has the following form:

struct CibPdfEventPageInfo
{
int pageIndex;
size_t pageWidth;
size_t pageHeight;
};

Parameters:

Type	Variable	Description
int	pageIndex	Index of the current page (0-based)
size_t	pageWidth pageHeight	width and height of the current page in pixels and the standard resolution of 72dpi

CibPdfEventPageImageInfo

The "CibPdfEventPageImageInfo" data structure delivered by the CIB pdf toolbox after rendering a page and before saving the image has the following form:

struct CibPdfEventPageImageInfo
{
int pageIndex;
size_t imageWidth;
size_t imageHeight;
size_t imageStride;
size_t imageLength;
Format imageFormat; 
const unsigned char* data;
};
enum Format {fRGB565, fRGB888, fBMP};

Parameters:

Type	Variable	Description
int	pageIndex	Index of the current page (0-based)
size_t	imageWidth imageHeight imageStride	The standard parameters of a bitmap in DIB format (DIB = device independent bitmap format)
char*	Data	Complete bitmap in DIB format
size_t	imageLength	Their length in bytes

CibPDFshowPageSetupDialog

(from CIB pdf toolbox 1.10.0 onwards)

BOOL EXPORTFUNC CibPdfShowPageSetupDialog(int *a_iButtonID);

On Windows this function starts with the standard printer driver dialog of the operating system. With this dialog you can configure the printer driver to be used for printing. This function is interesting for applications that always want to print with a user dialog.

Parameters:

Type	Variable	Description
int*	a_iButtonId	Returns the ButtonId of the button clicked within the print selection. 1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards) 3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately) 2 (CIB_ID_CANCEL) Cancel button

Type

Variable

Description

int*

a_iButtonId

Returns the ButtonId of the button clicked within the print selection.

1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards)

3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately)

2 (CIB_ID_CANCEL) Cancel button

The function returns TRUE if no error has occurred.

CibPdfShowPrintDialog

BOOL EXPORTFUNC CibPdfShowPrintDialog(int *a_iButtonID);

On Windows this function starts with the standard page selection/printer driver dialog of the operating system. This allows you to make appropriate printer configurations and page selections that will be taken into account during subsequent printing. This function is interesting for applications that always want to print with a user dialog.

Parameters:

Type	Variable	Description
int*	a_iButtonId	Returns the ButtonId of the button clicked within the print selection. CIB_ID_OK OK button (à you should call CibPrPrint afterwards) CIB_ID_CLOSE Close button (à the user has changed the printer but does not want to print immediately) CIB_ID_CANCEL Cancel button

Type

Variable

Description

int*

a_iButtonId

Returns the ButtonId of the button clicked within the print selection.

CIB_ID_OK OK button (à you should call CibPrPrint afterwards)

CIB_ID_CLOSE Close button (à the user has changed the printer but does not want to print immediately)

CIB_ID_CANCEL Cancel button

The function returns TRUE if no error has occurred.

CibPdfShowPrintSetupDialog

(from CIB pdf toolbox 1.10.0 onwards)

BOOL EXPORTFUNC CibPdfShowPrintSetupDialog(int *a_iButtonID);

On Windows this function starts with the standard page selection/printer driver dialog of the operating system. With this dialog, you can configure the printer to be used for the subsequent printing process. This function is of interest for applications that always want to print with a user dialog.

Parameters:

Type	Variable	Description
int*	a_iButtonId	Returns the ButtonId of the button clicked within the print selection. CIB_ID_OK OK button (à you should call CibPrPrint afterwards) CIB_ID_CLOSE Close button (à the user has changed the printer but does not want to print immediately) CIB_ID_CANCEL Cancel button

Type

Variable

Description

int*

a_iButtonId

Returns the ButtonId of the button clicked within the print selection.

CIB_ID_OK OK button (à you should call CibPrPrint afterwards)

CIB_ID_CLOSE Close button (à the user has changed the printer but does not want to print immediately)

CIB_ID_CANCEL Cancel button

The function returns TRUE if no error has occurred.

MemoryOutputCallback

COMOD_CALLBACK_TYPE(COMOD_BOOL, MemoryOutputCallbackType) (const char* a_TextOutput, size_t a_Length, void*a_pUserdata, int a_Error)

Callback prototype for data output in memory.

Parameters:

Type	Variable	Description
char*	a_TextOutput	The data that is transferred via the callback function.
size_t	a_Length	The number of bytes of the data.
void*	a_pUserdata	Pointer to any user data. Specific type depends on the implementation of the callback function.
Int*	a_Error	Error code which is transferred to the callback function by the caller.

The function returns FALSE if an error has occurred.

AbortDocCallback

(from CIB pdf toolbox 1.10.0 onwards)

BOOL EXPORTFUNC AbortDocCallback(const ABORTDOCINFO* a_AbortDocInfo, void* a_pUserData)

typedef struct _abortdoc {unsigned long ulCurrentPage;unsigned long ulPageCount;} ABORTDOCINFO;

Callback prototype for data output in memory. The callback is executed after each page of the document with information about current page number and total page number. The conversion is continued by returning the value "true", false causes the conversion to be aborted with return value 1000(userbreak).

Parameters:

Type	Variable	Description
ABORTDOCINFO*	a_AbortDocInfo	The data that is transferred via the callback function.
void*	a_pUserdata	Pointer to any user data. Specific type depends on the implementation of the callback function.

The function returns FALSE if an abort is desired.

CibPdfJobCreate

COMOD_BOOL COMOD_API CibPdfJobCreate(CibPdfJobHandle*a_pJob, const char* a_pReserved)

This method creates a JobHandle, which is then released again via CibPdfJobFree.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_pJob	Handle of the request to be executed.
char*	a_pReserved

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobFree

COMOD_BOOL COMOD_API CibPdfJobFree(CibPdfJobHandle*a_pJob);

This method releases a JobHandle created with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_pJob	Handle of the request to be executed.

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobMerge

COMOD_BOOL COMOD_API CibPdfJobMerge(CibPdfJobHandle a_hJob);

This method is used to execute a PDF merge job. The JobHandle has to be created with CibPdfJobCreate previously.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed.

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobJoin

COMOD_BOOL COMOD_API CibPdfJobJoin(CibPdfJobHandle a_hJob);

This method is used to execute a PDF join job. The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed.

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobShowPrintDialog

COMOD_BOOL COMOD_API CibPdfJobShowPrintDialog(CibPdfJobHandle a_hJob, int* a_pButtonID);

The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed.
Int*	a_pButtonID	Returns the ButtonId of the button clicked within the print selection. 1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards) 3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately) 2 (CIB_ID_CANCEL) Cancel button

Type

Variable

Description

CibPdfJobHandle*

a_hJob

Handle of the request to be executed.

Int*

a_pButtonID

Returns the ButtonId of the button clicked within the print selection.

1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards)

3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately)

2 (CIB_ID_CANCEL) Cancel button

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobShowPrintSetupDialog

COMOD_BOOL COMOD_API CibPdfJobShowPrintSetupDialog(CibPdfJobHandle a_hJob, int* a_pButtonID);

On Windows this function starts with the printer properties dialog of the respective driver manufacturer of the currently activated printer. With this dialog, you can configure the printer to be used for the subsequent printing process. This function is interesting for applications that always want to print with a user dialog.

The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
Int*	a_pButtonID	Returns the ButtonId of the button clicked within the print selection. 1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards) 3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately) 2 (CIB_ID_CANCEL) Cancel button

Type

Variable

Description

CibPdfJobHandle*

a_hJob

Handle of the request to be executed

Int*

a_pButtonID

Returns the ButtonId of the button clicked within the print selection.

1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards)

3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately)

2 (CIB_ID_CANCEL) Cancel button

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobShowPageSetupDialog

COMOD_BOOL COMOD_API CibPdfJobShowPageSetupDialog(CibPdfJobHandle a_hJob, int* a_pButtonID);

On Windows this function starts with the standard printer driver dialog of the operating system. With this dialog you can set up the printer driver (Page Setup), which will be taken into account when printing. This function is interesting for applications that always want to print with a user dialog.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
Int*	a_pButtonID	Returns the ButtonId of the button clicked within the print selection. 1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards) 3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately) 2 (CIB_ID_CANCEL) Cancel button

Type

Variable

Description

CibPdfJobHandle*

a_hJob

Handle of the request to be executed

Int*

a_pButtonID

Returns the ButtonId of the button clicked within the print selection.

1 (COMOD_ID_OK) OK button (à you should call CibPrPrint afterwards)

3 (COMOD_ID_CLOSE) Close button (à the user has changed the printer but does not want to print immediately)

2 (CIB_ID_CANCEL) Cancel button

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobGetProperty

COMOD_BOOL COMOD_API CibPdfJobGetProperty(CibPdfJobHandle a_hJob, const char* a_pName, void*a_pValue, size_t a_MaxLength);

With this function the currently set properties of the CIB pdf toolbox components can be queried.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
char*	a_pName	Name of the desired property
void*	a_pValue	Value of the desired property
size_t	a_MaxLength	Buffer length for the option content

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobSetProperty

COMOD_BOOL COMOD_API CibPdfJobSetProperty(CibPdfJobHandle a_hJob, const char* a_pName, void*a_pValue, size_t a_Length);

With this function the properties for the execution of the CIB pdf toolbox component can be set.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
char*	a_pName	Name of the desired property
void*	a_pValue	Value of the desired property
size_t	a_Length

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobGetPropertyW

COMOD_BOOL COMOD_API CibPdfJobGetPropertyW(CibPdfJobHandle a_hJob, const wchar_t* a_pName, const wchar_t*a_pValue, size_t a_MaxLength);

With this function the currently set properties of the CIB pdf toolbox component can be retrieved.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
wchar-t*	a_pName	Name of the property in wchar_t* (UNICODE)
wchar-t*	a_pValue	Value of the property in wchar_t* (UNICODE)
size_t	a_MaxLength	The number of bytes of the data

The function returns TRUE if no error has occurred. Otherwise FALSE is returned.

CibPdfJobSetPropertyW

COMOD_BOOL COMOD_API CibPdfJobSetPropertyW(CibPdfJobHandle a_hJob, const wchar_t* a_pName, const wchar_t*a_pValue/*, size_t a_Length*/);

With this function the properties for the execution of the CIB pdf toolbox components can be set.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
wchar-t*	a_pName	Name of the property in wchar_t* (UNICODE)
wchar-t*	a_pValue	Value of the property in wchar_t* (UNICODE)
size_t	a_MaxLength	The number of bytes of the data

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobGetError

COMOD_BOOL COMOD_API CibPdfJobGetError(CibPdfJobHandle a_hJob, int*a_pErrorCode);

With this function the current error status of the CIB pdf toolbox can be retrieved after the execution of various functions.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
int*	a_pErrorCode	Placeholder for the current error code

The function returns TRUE if no error has occurred. Otherwise FALSE will be returned.

CibPdfJobGetErrorText

COMOD_BOOL COMOD_API CibPdfJobGetErrorText(CibPdfJobHandle a_hJob, char* a_pText, size_t a_MaxLength);

This function can be used to retrieve the current error text for a job after a function has been executed.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed
char*	a_pText	Text buffer for the error text
size_t	a_MaxLength	Length of the available text buffer

The function returns TRUE if no error has occurred. Otherwise FALSE is returned.

CibPdfJobCancel

(from CIB pdf toolbox 1.24.0 onwards)

COMOD_BOOL COMOD_API CibPdfJobCancel(CibPdfJobHandle a_hJob);

With this function the current job of a CIB ocr text recognition (CibOcrJobGetProgress) can be aborted.
The JobHandle must have been created previously with CibPdfJobCreate.

Parameters:

Type	Variable	Description
CibPdfJobHandle*	a_hJob	Handle of the request to be executed

The function returns TRUE if no error has occurred. Otherwise FALSE is returned.