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_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.
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.

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 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.

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:

• Review the suggested severity of events. Each event has a default severity indicated by severity which is based on the event's category. Review the suggested severity of each TPdfToolsPdfAConversion_EventCategory and determine the TPdfToolsPdfAConversion_EventSeverity to be used in your process.
• Handle events according to their severity.
  • Events of severity ePdfToolsPdfAConversion_EventSeverity_Error: The conversion must be considered as failed.
  • Events of severity ePdfToolsPdfAConversion_EventSeverity_Warning: In case of a warning, the output file is best presented to a user to decide if the result is acceptable. The properties message, context, and page in combination with the output file are helpful to make this decision. If a manual review is not feasible, critical warnings should be classified as an ePdfToolsPdfAConversion_EventSeverity_Error. An exception to this is, if all processed input documents are similar in their content, e.g. because they have been created by a single source (application). In this case, the conversion result can be verified using representative test files and the event severity chosen accordingly.
  • Events of severity ePdfToolsPdfAConversion_EventSeverity_Information: No further action is required.

Parameters

[in,out]	pContext	Context of the event callback.
[in]	szDataPart	The 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]	szMessage	The event message
[in]	iSeverity	The 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]	iCategory	The category of the event. This parameter can be used to: Classify the severity of an event Specialized handling of events See the documentation of TPdfToolsPdfAConversion_Converter_ConversionEvent for a more detailed description.
[in]	iCode	The 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]	szContext	A description of the context where the event occurred
[in]	iPageNo	The 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:

• Review the suggested severity of events. Each event has a default severity indicated by severity which is based on the event's category. Review the suggested severity of each TPdfToolsPdfAConversion_EventCategory and determine the TPdfToolsPdfAConversion_EventSeverity to be used in your process.
• Handle events according to their severity.
  • Events of severity ePdfToolsPdfAConversion_EventSeverity_Error: The conversion must be considered as failed.
  • Events of severity ePdfToolsPdfAConversion_EventSeverity_Warning: In case of a warning, the output file is best presented to a user to decide if the result is acceptable. The properties message, context, and page in combination with the output file are helpful to make this decision. If a manual review is not feasible, critical warnings should be classified as an ePdfToolsPdfAConversion_EventSeverity_Error. An exception to this is, if all processed input documents are similar in their content, e.g. because they have been created by a single source (application). In this case, the conversion result can be verified using representative test files and the event severity chosen accordingly.
  • Events of severity ePdfToolsPdfAConversion_EventSeverity_Information: No further action is required.

Parameters

[in,out]	pContext	Context of the event callback.
[in]	szDataPart	The 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]	szMessage	The event message
[in]	iSeverity	The 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]	iCategory	The category of the event. This parameter can be used to: Classify the severity of an event Specialized handling of events See the documentation of TPdfToolsPdfAConversion_Converter_ConversionEvent for a more detailed description.
[in]	iCode	The 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]	szContext	A description of the context where the event occurred
[in]	iPageNo	The 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]	pConversionOptions	Acts as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
[out]	pConformance	Retrieved 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 is returned and the error code returned by PdfTools_GetLastError is different from ePdfTools_Error_Success. The error message can be obtained by calling 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]

pConversionOptions

Acts 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 is returned and the error code returned by PdfTools_GetLastError is different from ePdfTools_Error_Success. The error message can be obtained by calling PdfTools_GetLastErrorMessage.

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 is returned. The specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling 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]	pConversionOptions	Acts as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
[in]	pConformance	Set value.

Returns

TRUE if the operation is successful; FALSE if there is an error.

Note

An error occurred when FALSE is returned. The specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling 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]	pConversionOptions	Acts as a handle to the native object of type TPdfToolsPdfAConversion_ConversionOptions.
[in]	bCopyMetadata	Set value.

Returns

TRUE if the operation is successful; FALSE if there is an error.

Note

An error occurred when FALSE is returned. The specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling PdfTools_GetLastErrorMessage.

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]	pConverter	Pointer to the object to which the event handler is added.
[in,out]	pContext	The context of the event handler.
[in]	pFunction	The event callback that is added.

Returns

TRUE if adding event handler was successful; FALSE if error occured.

Note

In case of an error, the specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling 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]	pConverter	Pointer to the object to which the event handler is added.
[in,out]	pContext	The context of the event handler.
[in]	pFunction	The event callback that is added.

Returns

TRUE if adding event handler was successful; FALSE if error occured.

Note

In case of an error, the specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling PdfTools_GetLastErrorMessage.

PdfToolsPdfAConversion_Converter_Convert()

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.

Parameters

[in,out]	pConverter	Acts as a handle to the native object of type TPdfToolsPdfAConversion_Converter.
[in,out]	pAnalysis	The result of the document's analysis using PdfToolsPdfAValidation_Validator_Analyze.
[in,out]	pDocument	The document to convert
[in,out]	pOutStreamDesc	The stream where the converted document is written
[in,out]	pOptions	The conversion options
[in,out]	pOutOptions	The output options object

Returns

The result of the conversion

NULL if there is an error.

Note

An error occurred when NULL is returned. The specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling PdfTools_GetLastErrorMessage. Possible error codes:

• ePdfTools_Error_License The license check has failed.
• ePdfTools_Error_IllegalArgument The pOutOptions argument is invalid.
• ePdfTools_Error_IllegalArgument The output stream could not be opened for writing.
• ePdfTools_Error_IllegalState The pDocument has already been closed.
• ePdfTools_Error_IllegalArgument The pAnalysis has already been closed, e.g. due to a previous conversion.
• ePdfTools_Error_IllegalArgument The PDF/A version of the analysis and the conversion options do not match.
• ePdfTools_Error_IllegalArgument The pAnalysis is not the analysis result of pDocument.
• ePdfTools_Error_IO Error reading from or writing to the pOutStreamDesc.
• ePdfTools_Error_Conformance The conformance required by pOptions cannot be achieved.
  • PDF/A level U: All text of the input document must be extractable.
  • PDF/A level A: In addition to the requirements of level U, the input document must be tagged.
• ePdfTools_Error_Conformance The PDF/A version of the conformances of pAnalysis and pOptions differ. The same PDF/A version must be used for the analysis and conversion.
• ePdfTools_Error_IllegalArgument The pOutOptions specifies document encryption, which is not allowed in PDF/A documents.
• ePdfTools_Error_Generic The document cannot be converted to PDF/A.
• ePdfTools_Error_Corrupt The analysis has been stopped.
• ePdfTools_Error_UnsupportedFeature The document is not a PDF, but an XFA document. See PdfToolsPdf_Document_GetXfa for more information on how to detect and handle XFA documents.
• ePdfTools_Error_NotFound A required font is missing from the installed font directories.

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 is returned. The specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling 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]	pConverter	Pointer to the object from which the event handler is removed.
[in,out]	pContext	The context of the event handler.
[in]	pFunction	The event callback that is removed.

Returns

TRUE if removal was successful; FALSE if error occured.

Note

In case of an error, the specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling 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]	pConverter	Pointer to the object from which the event handler is removed.
[in,out]	pContext	The context of the event handler.
[in]	pFunction	The event callback that is removed.

Returns

TRUE if removal was successful; FALSE if error occured.

Note

In case of an error, the specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling PdfTools_GetLastErrorMessage.