Pdftools SDK
Loading...
Searching...
No Matches
Macros | Typedefs | Functions
PdfTools_PdfToolsPdfAConversion.h File Reference
#include "PdfTools_Types.h"
#include "PdfTools_PdfToolsSys.h"

Go to the source code of this file.

Macros

#define PDFTOOLS_CALL
 
#define TPdfToolsPdfAConversion_Converter_ConversionEvent   TPdfToolsPdfAConversion_Converter_ConversionEventA
 
#define PdfToolsPdfAConversion_Converter_AddConversionEventHandler    PdfToolsPdfAConversion_Converter_AddConversionEventHandlerA
 
#define PdfToolsPdfAConversion_Converter_RemoveConversionEventHandler    PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerA
 

Typedefs

typedef void(PDFTOOLS_CALLTPdfToolsPdfAConversion_Converter_ConversionEventA) (void *pContext, const char *szDataPart, const char *szMessage, TPdfToolsPdfAConversion_EventSeverity iSeverity, TPdfToolsPdfAConversion_EventCategory iCategory, TPdfToolsPdfAConversion_EventCode iCode, const char *szContext, int iPageNo)
 The event for errors, warnings, and informational messages that occur during conversion.
 
typedef void(PDFTOOLS_CALLTPdfToolsPdfAConversion_Converter_ConversionEventW) (void *pContext, const WCHAR *szDataPart, const WCHAR *szMessage, TPdfToolsPdfAConversion_EventSeverity iSeverity, TPdfToolsPdfAConversion_EventCategory iCategory, TPdfToolsPdfAConversion_EventCode iCode, const WCHAR *szContext, int iPageNo)
 The event for errors, warnings, and informational messages that occur during conversion.
 

Functions

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_AddConversionEventHandlerA (TPdfToolsPdfAConversion_Converter *pConverter, void *pContext, TPdfToolsPdfAConversion_Converter_ConversionEventA pFunction)
 Adds event handler.
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_AddConversionEventHandlerW (TPdfToolsPdfAConversion_Converter *pConverter, void *pContext, TPdfToolsPdfAConversion_Converter_ConversionEventW pFunction)
 Adds event handler.
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerA (TPdfToolsPdfAConversion_Converter *pConverter, void *pContext, TPdfToolsPdfAConversion_Converter_ConversionEventA pFunction)
 Removes event handler.
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerW (TPdfToolsPdfAConversion_Converter *pConverter, void *pContext, TPdfToolsPdfAConversion_Converter_ConversionEventW pFunction)
 Removes event handler.
 
PDFTOOLS_EXPORT TPdfToolsPdfAConversion_Converter *PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_New (void)
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_AddInvoiceXml (TPdfToolsPdfAConversion_Converter *pConverter, TPdfToolsPdfAConversion_InvoiceType iInvoiceType, const TPdfToolsSys_StreamDescriptor *pInvoice, const TPdfToolsPdfAConversion_AFRelationship *pAfRelationship)
 Prepares the invoice XML file (ZUGFeRD or Factur-X) for embedding. Note: This requires the compliance to be set to PDF/A-3.
 
PDFTOOLS_EXPORT TPdfToolsPdf_Document *PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_Convert (TPdfToolsPdfAConversion_Converter *pConverter, TPdfToolsPdfAValidation_AnalysisResult *pAnalysis, TPdfToolsPdf_Document *pDocument, const TPdfToolsSys_StreamDescriptor *pOutStreamDesc, TPdfToolsPdfAConversion_ConversionOptions *pOptions, TPdfToolsPdf_OutputOptions *pOutOptions)
 Convert a document to PDF/A. Note that it is highly recommended to use TPdfToolsPdfAConversion_Converter_ConversionEvent to detect critical conversion events.
 
PDFTOOLS_EXPORT TPdfToolsPdfAConversion_ConversionOptions *PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_New (void)
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_GetConformance (TPdfToolsPdfAConversion_ConversionOptions *pConversionOptions, TPdfToolsPdf_Conformance *pConformance)
 The minimal target conformance.
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_SetConformance (TPdfToolsPdfAConversion_ConversionOptions *pConversionOptions, const TPdfToolsPdf_Conformance *pConformance)
 The minimal target conformance.
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_GetCopyMetadata (TPdfToolsPdfAConversion_ConversionOptions *pConversionOptions)
 Whether to copy metadata Copy document information dictionary and XMP metadata. Default: TRUE.
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_SetCopyMetadata (TPdfToolsPdfAConversion_ConversionOptions *pConversionOptions, BOOL bCopyMetadata)
 Whether to copy metadata Copy document information dictionary and XMP metadata. Default: TRUE.
 
PDFTOOLS_EXPORT double PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_GetImageQuality (TPdfToolsPdfAConversion_ConversionOptions *pConversionOptions)
 Image quality of recompressed images.
 
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_SetImageQuality (TPdfToolsPdfAConversion_ConversionOptions *pConversionOptions, double dImageQuality)
 Image quality of recompressed images.
 

Macro Definition Documentation

◆ PDFTOOLS_CALL

#define PDFTOOLS_CALL

◆ PdfToolsPdfAConversion_Converter_AddConversionEventHandler

#define PdfToolsPdfAConversion_Converter_AddConversionEventHandler    PdfToolsPdfAConversion_Converter_AddConversionEventHandlerA

◆ PdfToolsPdfAConversion_Converter_RemoveConversionEventHandler

#define PdfToolsPdfAConversion_Converter_RemoveConversionEventHandler    PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerA

◆ TPdfToolsPdfAConversion_Converter_ConversionEvent

#define TPdfToolsPdfAConversion_Converter_ConversionEvent   TPdfToolsPdfAConversion_Converter_ConversionEventA

Typedef Documentation

◆ TPdfToolsPdfAConversion_Converter_ConversionEventA

typedef void(PDFTOOLS_CALL * TPdfToolsPdfAConversion_Converter_ConversionEventA) (void *pContext, const char *szDataPart, const char *szMessage, TPdfToolsPdfAConversion_EventSeverity iSeverity, TPdfToolsPdfAConversion_EventCategory iCategory, TPdfToolsPdfAConversion_EventCode iCode, const char *szContext, int iPageNo)

The event for errors, warnings, and informational messages that occur during conversion.

Report a conversion event that occurred in PdfToolsPdfAConversion_Converter_Convert. These events can be used to:

  • Generate a detailed conversion report.
  • Detect and handle critical conversion events.

Note that if a document cannot be converted to the requested conformance, the PdfToolsPdfAConversion_Converter_Convert throws an exception. However, even if the output document meets all required standards, the conversion might have resulted in differences that might be acceptable in some processes but not in others. Such potentially critical conversion issues are reported as conversion events.

We suggest checking which conversion events can be tolerated in your conversion process and which must be considered critical:

Parameters
[in,out]pContextContext of the event callback.
[in]szDataPartThe data part is NULL for the main file and a data part specification for embedded files. Examples:
  • embedded-file:file.pdf: For a file file.pdf that is embedded in the main file.
  • embedded-file:file1.pdf/embedded-file:file2.pdf: For a file file2.pdf that is embedded in an embedded file file1.pdf.
[in]szMessageThe event message
[in]iSeverityThe suggested severity of the event. We suggest checking, which conversion events are tolerable in your conversion process and which must be considered critical. See the documentation of TPdfToolsPdfAConversion_Converter_ConversionEvent for a more detailed description.
[in]iCategoryThe category of the event. This parameter can be used to:
[in]iCodeThe code identifying particular events which can be used for detection and specialized handling of specific events. For most applications, it suffices to handle events by category.
[in]szContextA description of the context where the event occurred
[in]iPageNoThe page this event is associated to or 0

◆ TPdfToolsPdfAConversion_Converter_ConversionEventW

typedef void(PDFTOOLS_CALL * TPdfToolsPdfAConversion_Converter_ConversionEventW) (void *pContext, const WCHAR *szDataPart, const WCHAR *szMessage, TPdfToolsPdfAConversion_EventSeverity iSeverity, TPdfToolsPdfAConversion_EventCategory iCategory, TPdfToolsPdfAConversion_EventCode iCode, const WCHAR *szContext, int iPageNo)

The event for errors, warnings, and informational messages that occur during conversion.

Report a conversion event that occurred in PdfToolsPdfAConversion_Converter_Convert. These events can be used to:

  • Generate a detailed conversion report.
  • Detect and handle critical conversion events.

Note that if a document cannot be converted to the requested conformance, the PdfToolsPdfAConversion_Converter_Convert throws an exception. However, even if the output document meets all required standards, the conversion might have resulted in differences that might be acceptable in some processes but not in others. Such potentially critical conversion issues are reported as conversion events.

We suggest checking which conversion events can be tolerated in your conversion process and which must be considered critical:

Parameters
[in,out]pContextContext of the event callback.
[in]szDataPartThe data part is NULL for the main file and a data part specification for embedded files. Examples:
  • embedded-file:file.pdf: For a file file.pdf that is embedded in the main file.
  • embedded-file:file1.pdf/embedded-file:file2.pdf: For a file file2.pdf that is embedded in an embedded file file1.pdf.
[in]szMessageThe event message
[in]iSeverityThe suggested severity of the event. We suggest checking, which conversion events are tolerable in your conversion process and which must be considered critical. See the documentation of TPdfToolsPdfAConversion_Converter_ConversionEvent for a more detailed description.
[in]iCategoryThe category of the event. This parameter can be used to:
[in]iCodeThe code identifying particular events which can be used for detection and specialized handling of specific events. For most applications, it suffices to handle events by category.
[in]szContextA description of the context where the event occurred
[in]iPageNoThe page this event is associated to or 0

Function Documentation

◆ PdfToolsPdfAConversion_ConversionOptions_GetConformance()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_GetConformance ( TPdfToolsPdfAConversion_ConversionOptions * pConversionOptions,
TPdfToolsPdf_Conformance * pConformance )

The minimal target conformance.

If a conformance is set, it is used as the minimal target conformance. The PDF/A version of the conformance must match the PDF/A version of the analysisOptions of PdfToolsPdfAValidation_Validator_Analyze. If the conformance level cannot be achieved, the conversion will abort with the error ePdfTools_Error_Conformance. If a higher conformance level can be achieved, it is used automatically.

If NULL is used, the optimal conformance determined in the analysis (i.e. PdfToolsPdfAValidation_AnalysisResult_GetRecommendedConformance) is used. It is highly recommended to use NULL.

Default value: NULL

Parameters
[in,out]pConversionOptionsActs as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
[out]pConformanceRetrieved value.
Returns
FALSE if either an error occurred or the [out] argument returns NULL. To determine if an error has occurred, check the error code as described in the note section below.
Note
An error occurred when FALSE was returned and the error code returned by PdfTools_GetLastError is different from ePdfTools_Error_Success. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_ConversionOptions_GetCopyMetadata()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_GetCopyMetadata ( TPdfToolsPdfAConversion_ConversionOptions * pConversionOptions)

Whether to copy metadata Copy document information dictionary and XMP metadata. Default: TRUE.

Parameters
[in,out]pConversionOptionsActs as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
Returns
Retrieved value.

May indicate an error in certain scenarios. For further information see the note section below.

Note
An error occurred when FALSE was returned and the error code returned by PdfTools_GetLastError is different from ePdfTools_Error_Success. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_ConversionOptions_GetImageQuality()

PDFTOOLS_EXPORT double PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_GetImageQuality ( TPdfToolsPdfAConversion_ConversionOptions * pConversionOptions)

Image quality of recompressed images.

The image quality for images that use a prohibited lossy compression type and must be recompressed. Supported values are 0.01 to 1.0. A higher value means better visual quality at the cost of a larger file size. Recommended values range from 0.7 to 0.9.

Example: JPX (JPEG2000) is not allowed in PDF/A-1. If a PDF contains a JPX compressed image, its compression type must be altered. Thus the image is converted to an image with JPEG compression using the image quality defined by this property. Copy document information dictionary and XMP metadata. Default value: 0.8

Parameters
[in,out]pConversionOptionsActs as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
Returns
Retrieved value.

May indicate an error in certain scenarios. For further information see the note section below.

Note
An error occurred when -1.0 was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage. Possible error codes:

◆ PdfToolsPdfAConversion_ConversionOptions_New()

PDFTOOLS_EXPORT TPdfToolsPdfAConversion_ConversionOptions *PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_New ( void )
Returns
Handle to the newly created native object.

NULL if there is an error.

Note
An error occurred when NULL was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_ConversionOptions_SetConformance()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_SetConformance ( TPdfToolsPdfAConversion_ConversionOptions * pConversionOptions,
const TPdfToolsPdf_Conformance * pConformance )

The minimal target conformance.

If a conformance is set, it is used as the minimal target conformance. The PDF/A version of the conformance must match the PDF/A version of the analysisOptions of PdfToolsPdfAValidation_Validator_Analyze. If the conformance level cannot be achieved, the conversion will abort with the error ePdfTools_Error_Conformance. If a higher conformance level can be achieved, it is used automatically.

If NULL is used, the optimal conformance determined in the analysis (i.e. PdfToolsPdfAValidation_AnalysisResult_GetRecommendedConformance) is used. It is highly recommended to use NULL.

Default value: NULL

Parameters
[in,out]pConversionOptionsActs as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
[in]pConformanceSet value.
Returns
TRUE if the operation is successful; FALSE if there is an error.
Note
An error occurred when FALSE was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_ConversionOptions_SetCopyMetadata()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_SetCopyMetadata ( TPdfToolsPdfAConversion_ConversionOptions * pConversionOptions,
BOOL bCopyMetadata )

Whether to copy metadata Copy document information dictionary and XMP metadata. Default: TRUE.

Parameters
[in,out]pConversionOptionsActs as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
[in]bCopyMetadataSet value.
Returns
TRUE if the operation is successful; FALSE if there is an error.
Note
An error occurred when FALSE was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_ConversionOptions_SetImageQuality()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_ConversionOptions_SetImageQuality ( TPdfToolsPdfAConversion_ConversionOptions * pConversionOptions,
double dImageQuality )

Image quality of recompressed images.

The image quality for images that use a prohibited lossy compression type and must be recompressed. Supported values are 0.01 to 1.0. A higher value means better visual quality at the cost of a larger file size. Recommended values range from 0.7 to 0.9.

Example: JPX (JPEG2000) is not allowed in PDF/A-1. If a PDF contains a JPX compressed image, its compression type must be altered. Thus the image is converted to an image with JPEG compression using the image quality defined by this property. Copy document information dictionary and XMP metadata. Default value: 0.8

Parameters
[in,out]pConversionOptionsActs as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
[in]dImageQualitySet value.
Returns
TRUE if the operation is successful; FALSE if there is an error.
Note
An error occurred when FALSE was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage. Possible error codes:

◆ PdfToolsPdfAConversion_Converter_AddConversionEventHandlerA()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_AddConversionEventHandlerA ( TPdfToolsPdfAConversion_Converter * pConverter,
void * pContext,
TPdfToolsPdfAConversion_Converter_ConversionEventA pFunction )

Adds event handler.

Parameters
[in,out]pConverterPointer to the object to which the event handler is added.
[in,out]pContextThe context of the event handler.
[in]pFunctionThe event callback that is added.
Returns
TRUE if adding event handler was successful; FALSE if error occured.
Note
In case of an error, Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_Converter_AddConversionEventHandlerW()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_AddConversionEventHandlerW ( TPdfToolsPdfAConversion_Converter * pConverter,
void * pContext,
TPdfToolsPdfAConversion_Converter_ConversionEventW pFunction )

Adds event handler.

Parameters
[in,out]pConverterPointer to the object to which the event handler is added.
[in,out]pContextThe context of the event handler.
[in]pFunctionThe event callback that is added.
Returns
TRUE if adding event handler was successful; FALSE if error occured.
Note
In case of an error, Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_Converter_AddInvoiceXml()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_AddInvoiceXml ( TPdfToolsPdfAConversion_Converter * pConverter,
TPdfToolsPdfAConversion_InvoiceType iInvoiceType,
const TPdfToolsSys_StreamDescriptor * pInvoice,
const TPdfToolsPdfAConversion_AFRelationship * pAfRelationship )

Prepares the invoice XML file (ZUGFeRD or Factur-X) for embedding. Note: This requires the compliance to be set to PDF/A-3.

Parameters
[in,out]pConverterActs as a handle to the native object of type TPdfToolsPdfAConversion_Converter.
[in]iInvoiceTypeThe type of invoice.
[in]pInvoiceThe XML invoice stream.
[in]pAfRelationshipIf no value is provided, a sensible default value is chosen based on the invoice type and version.
Returns
TRUE if the operation is successful; FALSE if there is an error.
Note
An error occurred when FALSE was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage. Possible error codes:

◆ PdfToolsPdfAConversion_Converter_Convert()

Convert a document to PDF/A. Note that it is highly recommended to use TPdfToolsPdfAConversion_Converter_ConversionEvent to detect critical conversion events.

Parameters
[in,out]pConverterActs as a handle to the native object of type TPdfToolsPdfAConversion_Converter.
[in,out]pAnalysisThe result of the document's analysis using PdfToolsPdfAValidation_Validator_Analyze.
[in,out]pDocumentThe document to convert
[in,out]pOutStreamDescThe stream where the converted document is written
[in,out]pOptionsThe conversion options
[in,out]pOutOptionsThe output options object
Returns
The result of the conversion

NULL if there is an error.

Note
An error occurred when NULL was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage. Possible error codes:

◆ PdfToolsPdfAConversion_Converter_New()

PDFTOOLS_EXPORT TPdfToolsPdfAConversion_Converter *PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_New ( void )
Returns
Handle to the newly created native object.

NULL if there is an error.

Note
An error occurred when NULL was returned. Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerA()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerA ( TPdfToolsPdfAConversion_Converter * pConverter,
void * pContext,
TPdfToolsPdfAConversion_Converter_ConversionEventA pFunction )

Removes event handler.

Parameters
[in,out]pConverterPointer to the object from which the event handler is removed.
[in,out]pContextThe context of the event handler.
[in]pFunctionThe event callback that is removed.
Returns
TRUE if removal was successful; FALSE if error occured.
Note
In case of an error, Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.

◆ PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerW()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsPdfAConversion_Converter_RemoveConversionEventHandlerW ( TPdfToolsPdfAConversion_Converter * pConverter,
void * pContext,
TPdfToolsPdfAConversion_Converter_ConversionEventW pFunction )

Removes event handler.

Parameters
[in,out]pConverterPointer to the object from which the event handler is removed.
[in,out]pContextThe context of the event handler.
[in]pFunctionThe event callback that is removed.
Returns
TRUE if removal was successful; FALSE if error occured.
Note
In case of an error, Retrieve specific error code by calling PdfTools_GetLastError. Get the error message with PdfTools_GetLastErrorMessage.