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

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 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]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 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]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 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]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 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]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, 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]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, the specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling PdfTools_GetLastErrorMessage.

◆ 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 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:

◆ 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]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, 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]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, the specific error code can be retrieved by calling PdfTools_GetLastError. The error message can be obtained by calling PdfTools_GetLastErrorMessage.