PdfTools_PdfToolsImage2PdfProfiles.h File Reference

#include "PdfTools_Types.h"
#include "PdfTools_PdfToolsSys.h"

Go to the source code of this file.

Macros
#define	PDFTOOLS_CALL
#define	PdfToolsImage2PdfProfiles_Archive_GetLanguage   PdfToolsImage2PdfProfiles_Archive_GetLanguageA
#define	PdfToolsImage2PdfProfiles_Archive_SetLanguage   PdfToolsImage2PdfProfiles_Archive_SetLanguageA

Functions
PDFTOOLS_EXPORT TPdfToolsImage2Pdf_ImageOptions *PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Profile_GetImageOptions (TPdfToolsImage2PdfProfiles_Profile *pProfile)
	The image conversion options.
PDFTOOLS_EXPORT TPdfToolsImage2PdfProfiles_ProfileType PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Profile_GetType (TPdfToolsImage2PdfProfiles_Profile *pProfile)
	Get actual derived type of base type TPdfToolsImage2PdfProfiles_Profile.
PDFTOOLS_EXPORT TPdfToolsImage2PdfProfiles_Default *PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Default_New (void)
PDFTOOLS_EXPORT TPdfToolsPdf_Conformance PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Default_GetConformance (TPdfToolsImage2PdfProfiles_Default *pDefault)
	The PDF conformance of the output document.
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Default_SetConformance (TPdfToolsImage2PdfProfiles_Default *pDefault, TPdfToolsPdf_Conformance iConformance)
	The PDF conformance of the output document.
PDFTOOLS_EXPORT TPdfToolsImage2PdfProfiles_Archive *PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_New (void)
PDFTOOLS_EXPORT TPdfToolsPdf_Conformance PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_GetConformance (TPdfToolsImage2PdfProfiles_Archive *pArchive)
	The PDF/A conformance of the output document.
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_SetConformance (TPdfToolsImage2PdfProfiles_Archive *pArchive, TPdfToolsPdf_Conformance iConformance)
	The PDF/A conformance of the output document.
PDFTOOLS_EXPORT TPdfTools_StringList *PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_GetAlternateText (TPdfToolsImage2PdfProfiles_Archive *pArchive)
	The alternate text describing the image.
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_SetAlternateText (TPdfToolsImage2PdfProfiles_Archive *pArchive, TPdfTools_StringList *pAlternateText)
	The alternate text describing the image.
PDFTOOLS_EXPORT size_t PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_GetLanguageA (TPdfToolsImage2PdfProfiles_Archive *pArchive, char *pBuffer, size_t nBufferSize)
	The language of the output PDF.
PDFTOOLS_EXPORT size_t PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_GetLanguageW (TPdfToolsImage2PdfProfiles_Archive *pArchive, WCHAR *pBuffer, size_t nBufferSize)
	The language of the output PDF.
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_SetLanguageA (TPdfToolsImage2PdfProfiles_Archive *pArchive, const char *szLanguage)
	The language of the output PDF.
PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL	PdfToolsImage2PdfProfiles_Archive_SetLanguageW (TPdfToolsImage2PdfProfiles_Archive *pArchive, const WCHAR *szLanguage)
	The language of the output PDF.

Macro Definition Documentation

PDFTOOLS_CALL

#define PDFTOOLS_CALL

PdfToolsImage2PdfProfiles_Archive_GetLanguage

#define PdfToolsImage2PdfProfiles_Archive_GetLanguage   PdfToolsImage2PdfProfiles_Archive_GetLanguageA

PdfToolsImage2PdfProfiles_Archive_SetLanguage

#define PdfToolsImage2PdfProfiles_Archive_SetLanguage   PdfToolsImage2PdfProfiles_Archive_SetLanguageA

Function Documentation

PdfToolsImage2PdfProfiles_Archive_GetAlternateText()

PDFTOOLS_EXPORT TPdfTools_StringList *PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_GetAlternateText

(

TPdfToolsImage2PdfProfiles_Archive *

pArchive

)

The alternate text describing the image.

The alternate text provides a meaningful description of the images. For example, "This color image shows a small sailing boat at sunset". This information can be used to read the document to the visually impaired.

The list must contain a description for each page of the input image document. For the conversion of TPdfToolsImage_SinglePageDocument, a single description is sufficient. For TPdfToolsImage_MultiPageDocument, multiple descriptions may be required.

Alternate text is required for PDF/A level A conformance. It is not advisable to add "dummy" tagging solely for the purpose of achieving level A conformance. Instead, for scanned text documents, the Conversion Service can be used to recognize the characters in the documents (OCR) and tag the image with the recognized structure and text. For other types of images, such as photos, logos or graphics, alternate text descriptions should be written manually by a user.

Default: empty list

Parameters

[in,out]

pArchive

Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.

Returns

Retrieved value.

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.

PdfToolsImage2PdfProfiles_Archive_GetConformance()

PDFTOOLS_EXPORT TPdfToolsPdf_Conformance PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_GetConformance

(

TPdfToolsImage2PdfProfiles_Archive *

pArchive

)

The PDF/A conformance of the output document.

The supported PDF/A conformance are:

• "PDF/A-1b"
• "PDF/A-1a"
• "PDF/A-2b"
• "PDF/A-2u"
• "PDF/A-2a"
• "PDF/A-3b"
• "PDF/A-3u"
• "PDF/A-3a" With level A conformances (PDF/A-1a, PDF/A-2a, PDF/A-3a), the properties PdfToolsImage2PdfProfiles_Archive_GetAlternateText and PdfToolsImage2PdfProfiles_Archive_GetLanguage must be set.

Default value: "PDF/A-2b"

Parameters

[in,out]

pArchive

Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.

Returns

Retrieved value.

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

Note

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

• ePdfTools_Error_IllegalArgument The conformance is PDF but must be PDF/A for this profile. Use the profile TPdfToolsImage2PdfProfiles_Default to create PDF documents.

PdfToolsImage2PdfProfiles_Archive_GetLanguageA()

PDFTOOLS_EXPORT size_t PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_GetLanguageA	(	TPdfToolsImage2PdfProfiles_Archive *	pArchive,
		char *	pBuffer,
		size_t	nBufferSize )

The language of the output PDF.

The language code that specifies the language of the PDF and specifically its PdfToolsImage2PdfProfiles_Archive_GetAlternateText descriptions. Specifying the language is highly recommended for PDF/A level A conformance.

The codes are defined in BCP 47 and ISO 3166:2013 and can be obtained from the Internet Engineering Task Force and the International Organization for Standardization.

If no code is set, the language will be specified as unknown.

Examples:

• "en"
• "en-US"
• "de"
• "de-CH"
• "fr-FR"
• "zxx" (for non linguistic content)

Default: NULL (unknown)

Parameters

[in,out]	pArchive	Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.
[out]	pBuffer	Retrieved value. To determine the required buffer size, the function has to be called with NULL. The return value of this function specifies the buffer size.
[in]	nBufferSize	The buffer size of the retrieved string pBuffer.

Returns

The amount of data written to the buffer pBuffer. 0 if either an error occurred or the returned buffer is actually NULL. To determine if an error has occurred, check the error code as described in the note section below.

Note

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

PdfToolsImage2PdfProfiles_Archive_GetLanguageW()

PDFTOOLS_EXPORT size_t PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_GetLanguageW	(	TPdfToolsImage2PdfProfiles_Archive *	pArchive,
		WCHAR *	pBuffer,
		size_t	nBufferSize )

The language of the output PDF.

The language code that specifies the language of the PDF and specifically its PdfToolsImage2PdfProfiles_Archive_GetAlternateText descriptions. Specifying the language is highly recommended for PDF/A level A conformance.

The codes are defined in BCP 47 and ISO 3166:2013 and can be obtained from the Internet Engineering Task Force and the International Organization for Standardization.

If no code is set, the language will be specified as unknown.

Examples:

• "en"
• "en-US"
• "de"
• "de-CH"
• "fr-FR"
• "zxx" (for non linguistic content)

Default: NULL (unknown)

Parameters

[in,out]	pArchive	Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.
[out]	pBuffer	Retrieved value. To determine the required buffer size, the function has to be called with NULL. The return value of this function specifies the buffer size.
[in]	nBufferSize	The buffer size of the retrieved string pBuffer.

Returns

The amount of data written to the buffer pBuffer. 0 if either an error occurred or the returned buffer is actually NULL. To determine if an error has occurred, check the error code as described in the note section below.

Note

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

PdfToolsImage2PdfProfiles_Archive_New()

PDFTOOLS_EXPORT TPdfToolsImage2PdfProfiles_Archive *PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_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.

PdfToolsImage2PdfProfiles_Archive_SetAlternateText()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_SetAlternateText	(	TPdfToolsImage2PdfProfiles_Archive *	pArchive,
		TPdfTools_StringList *	pAlternateText )

The alternate text describing the image.

The alternate text provides a meaningful description of the images. For example, "This color image shows a small sailing boat at sunset". This information can be used to read the document to the visually impaired.

The list must contain a description for each page of the input image document. For the conversion of TPdfToolsImage_SinglePageDocument, a single description is sufficient. For TPdfToolsImage_MultiPageDocument, multiple descriptions may be required.

Alternate text is required for PDF/A level A conformance. It is not advisable to add "dummy" tagging solely for the purpose of achieving level A conformance. Instead, for scanned text documents, the Conversion Service can be used to recognize the characters in the documents (OCR) and tag the image with the recognized structure and text. For other types of images, such as photos, logos or graphics, alternate text descriptions should be written manually by a user.

Default: empty list

Parameters

[in,out]	pArchive	Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.
[in,out]	pAlternateText	Set 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.

PdfToolsImage2PdfProfiles_Archive_SetConformance()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_SetConformance	(	TPdfToolsImage2PdfProfiles_Archive *	pArchive,
		TPdfToolsPdf_Conformance	iConformance )

The PDF/A conformance of the output document.

The supported PDF/A conformance are:

• "PDF/A-1b"
• "PDF/A-1a"
• "PDF/A-2b"
• "PDF/A-2u"
• "PDF/A-2a"
• "PDF/A-3b"
• "PDF/A-3u"
• "PDF/A-3a" With level A conformances (PDF/A-1a, PDF/A-2a, PDF/A-3a), the properties PdfToolsImage2PdfProfiles_Archive_GetAlternateText and PdfToolsImage2PdfProfiles_Archive_GetLanguage must be set.

Default value: "PDF/A-2b"

Parameters

[in,out]	pArchive	Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.
[in]	iConformance	Set 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:

• ePdfTools_Error_IllegalArgument The conformance is PDF but must be PDF/A for this profile. Use the profile TPdfToolsImage2PdfProfiles_Default to create PDF documents.

PdfToolsImage2PdfProfiles_Archive_SetLanguageA()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_SetLanguageA	(	TPdfToolsImage2PdfProfiles_Archive *	pArchive,
		const char *	szLanguage )

The language of the output PDF.

The language code that specifies the language of the PDF and specifically its PdfToolsImage2PdfProfiles_Archive_GetAlternateText descriptions. Specifying the language is highly recommended for PDF/A level A conformance.

The codes are defined in BCP 47 and ISO 3166:2013 and can be obtained from the Internet Engineering Task Force and the International Organization for Standardization.

If no code is set, the language will be specified as unknown.

Examples:

• "en"
• "en-US"
• "de"
• "de-CH"
• "fr-FR"
• "zxx" (for non linguistic content)

Default: NULL (unknown)

Parameters

[in,out]	pArchive	Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.
[in]	szLanguage	Set 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.

PdfToolsImage2PdfProfiles_Archive_SetLanguageW()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Archive_SetLanguageW	(	TPdfToolsImage2PdfProfiles_Archive *	pArchive,
		const WCHAR *	szLanguage )

The language of the output PDF.

The language code that specifies the language of the PDF and specifically its PdfToolsImage2PdfProfiles_Archive_GetAlternateText descriptions. Specifying the language is highly recommended for PDF/A level A conformance.

The codes are defined in BCP 47 and ISO 3166:2013 and can be obtained from the Internet Engineering Task Force and the International Organization for Standardization.

If no code is set, the language will be specified as unknown.

Examples:

• "en"
• "en-US"
• "de"
• "de-CH"
• "fr-FR"
• "zxx" (for non linguistic content)

Default: NULL (unknown)

Parameters

[in,out]	pArchive	Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Archive.
[in]	szLanguage	Set 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.

PdfToolsImage2PdfProfiles_Default_GetConformance()

PDFTOOLS_EXPORT TPdfToolsPdf_Conformance PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Default_GetConformance

(

TPdfToolsImage2PdfProfiles_Default *

pDefault

)

The PDF conformance of the output document.

All PDF conformances are supported. For PDF/A the TPdfToolsImage2PdfProfiles_Archive profile must be used.

Default value: "PDF 1.7"

Parameters

[in,out]

pDefault

Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Default.

Returns

Retrieved value.

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

Note

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

• ePdfTools_Error_IllegalArgument The conformance is PDF/A but must be PDF for this profile. Use the profile TPdfToolsImage2PdfProfiles_Archive to create PDF/A documents.

PdfToolsImage2PdfProfiles_Default_New()

PDFTOOLS_EXPORT TPdfToolsImage2PdfProfiles_Default *PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Default_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.

PdfToolsImage2PdfProfiles_Default_SetConformance()

PDFTOOLS_EXPORT BOOL PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Default_SetConformance	(	TPdfToolsImage2PdfProfiles_Default *	pDefault,
		TPdfToolsPdf_Conformance	iConformance )

The PDF conformance of the output document.

All PDF conformances are supported. For PDF/A the TPdfToolsImage2PdfProfiles_Archive profile must be used.

Default value: "PDF 1.7"

Parameters

[in,out]	pDefault	Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Default.
[in]	iConformance	Set 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:

• ePdfTools_Error_IllegalArgument The conformance is PDF/A but must be PDF for this profile. Use the profile TPdfToolsImage2PdfProfiles_Archive to create PDF/A documents.

PdfToolsImage2PdfProfiles_Profile_GetImageOptions()

PDFTOOLS_EXPORT TPdfToolsImage2Pdf_ImageOptions *PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Profile_GetImageOptions

(

TPdfToolsImage2PdfProfiles_Profile *

pProfile

)

The image conversion options.

Parameters

[in,out]

pProfile

Acts as a handle to the native object of type TPdfToolsImage2PdfProfiles_Profile.

Returns

Retrieved value.

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.

PdfToolsImage2PdfProfiles_Profile_GetType()

PDFTOOLS_EXPORT TPdfToolsImage2PdfProfiles_ProfileType PDFTOOLS_CALL PdfToolsImage2PdfProfiles_Profile_GetType

(

TPdfToolsImage2PdfProfiles_Profile *

pProfile

)

Get actual derived type of base type TPdfToolsImage2PdfProfiles_Profile.

This function is invoked prior to downcasting to ascertain the derived object type.

Parameters

[in,out]

pProfile

Acts as a handle to a native object.

Returns

The item of the enumeration TPdfToolsImage2PdfProfiles_ProfileType that refers to the actual derived type. 0 in case of an error.

Note

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