PDF SDK Documentation

Comprehensive Guide for Developers: Features, Integration, and API Reference

Loading...
Searching...
No Matches
pdf2pdfa.h File Reference

PDF to PDF/A conversion API. More...

#include <pdfsdk/core.h>
#include <pdfsdk/core/pdfa_flavor.h>

Go to the source code of this file.

Classes

struct  PDFConvertToPDFAParams
 Conversion input parameters. More...
struct  PDFAIssueMonitor
 PDF/A compliance issue monitor. More...

Macros

#define PDF_PDF2PDFA_API   PDFSDK_IMPORT_

Typedefs

typedef uint32_t PDFAConvertFlags

Enumerations

enum  PDFAConvertMode { kPDFAConvertMode_Auto = 0 , kPDFAConvertMode_Exact = 1 , kPDFAConvertMode_Downgrade = 2 }
 Defines the conversion mode for PDF to PDF/A conversion. More...
enum  PDFAConvertFlagsBits { kPDFAConvertFlags_ClearSignatures = 1 << 0 , kPDFAConvertFlags_RemoveEncryption = 1 << 1 , kPDFAConvertFlags_Default = kPDFAConvertFlags_ClearSignatures | kPDFAConvertFlags_RemoveEncryption }
 Bit flags for PDFConvertToPdfaParams::flags. Combine with bitwise OR and store in a PDFAConvertFlags value. More...
enum  PDFAIssueType {
  kPDFAIssueType_VisualDifferences = 0x0001 , kPDFAIssueType_TargetFlavorAdjusted = 0x0002 , kPDFAIssueType_TargetFlavorUnachievable = 0x0003 , kPDFAIssueType_LimitsExceeded = 0x0010 ,
  kPDFAIssueType_NameIsNotValidUtf8 = 0x0011 , kPDFAIssueType_ProhibitedFilter = 0x0020 , kPDFAIssueType_InvalidStreamLength = 0x0021 , kPDFAIssueType_MissingLogicalStructure = 0x0030 ,
  kPDFAIssueType_IncorrectLogicalStructure = 0x0031 , kPDFAIssueType_OptionalContent = 0x0040 , kPDFAIssueType_IncorrectOptionalContent = 0x0041 , kPDFAIssueType_MetadataNonConformant = 0x0050 ,
  kPDFAIssueType_MetadataMissingRequired = 0x0051 , kPDFAIssueType_MetadataInvalidProperty = 0x0052 , kPDFAIssueType_MetadataInvalidNamespace = 0x0053 , kPDFAIssueType_MetadataInvalidStructure = 0x0054 ,
  kPDFAIssueType_MetadataInvalidPattern = 0x0055 , kPDFAIssueType_DeviceColors = 0x0060 , kPDFAIssueType_IncorrectColorSpaceStructure = 0x0061 , kPDFAIssueType_InvalidICCProfile = 0x0062 ,
  kPDFAIssueType_TransparencyUsage = 0x0063 , kPDFAIssueType_IncorrectOutputIntent = 0x0064 , kPDFAIssueType_Jpeg2000NonConformant = 0x0070 , kPDFAIssueType_InvalidImageProperties = 0x0071 ,
  kPDFAIssueType_PostScriptXObjectFound = 0x0080 , kPDFAIssueType_ProhibitedXObjectProps = 0x0081 , kPDFAIssueType_ProhibitedActions = 0x0090 , kPDFAIssueType_ProhibitedInteractiveFormProps = 0x0091 ,
  kPDFAIssueType_ProhibitedAnnotationType = 0x00A0 , kPDFAIssueType_InvisibleAnnotation = 0x00A1 , kPDFAIssueType_IncorrectAnnotationProps = 0x00A2 , kPDFAIssueType_DocumentIsEncrypted = 0x00D0 ,
  kPDFAIssueType_DocumentIsSigned = 0x00D1 , kPDFAIssueType_EmbeddedFilesInvalid = 0x00E0 , kPDFAIssueType_EmbeddedFilesNotAssociated = 0x00E1 , kPDFAIssueType_EmbeddedFilesMissing = 0x00E2 ,
  kPDFAIssueType_FontNotEmbedded = 0x00F0 , kPDFAIssueType_FontProgramCorrupted = 0x00F1 , kPDFAIssueType_FontMissingCIDSet = 0x00F2 , kPDFAIssueType_FontUnnecessaryCIDSet = 0x00F3 ,
  kPDFAIssueType_FontFailedToLoadAGL = 0x00F4 , kPDFAIssueType_FontMissingToUnicode = 0x00F5 , kPDFAIssueType_FontGlyphFailMapToUnicode = 0x00F6 , kPDFAIssueType_FontVectorizeTextRun = 0x00F7 ,
  kPDFAIssueType_FontNotdefGlyphReference = 0x00F8 , kPDFAIssueType_FontMissingCharSet = 0x00F9 , kPDFAIssueType_FontMissingWidths = 0x00FA , kPDFAIssueType_FontSymbolicTrueTypeNonCompliant = 0x00FB ,
  kPDFAIssueType_FontNonSymbolicTrueTypeNonCompliant = 0x00FC
}
 Compliance issue category reported via PDFAIssueMonitor. More...
enum  PDFAIssueLevel { kPDFAIssueLevel_Info = 1 , kPDFAIssueLevel_Warning = 2 , kPDFAIssueLevel_Error = 3 , kPDFAIssueLevel_FatalError = 4 }
 The level of severity of the compliance issue, reported via PDFAIssueMonitor. More...

Functions

PDFSDK_IMPORT_ PDErrCode PDFSDK_CALLCONV PDFConvertToPDFA (PDDoc source, const PDProgressMonitor *progress, void *progressData, const PDFAIssueMonitor *issueMon, void *issueMonData, const PDFConvertToPDFAParams *params, PDFAFlavor *producedFlavor)
 Converts a PDF document into a PDF/A‑compliant file.

Detailed Description

PDF to PDF/A conversion API.

Typedef Documentation

◆ PDFAConvertFlags

typedef uint32_t PDFAConvertFlags

Storage type for combinations of PDFAConvertFlagsBits.

Enumeration Type Documentation

◆ PDFAConvertFlagsBits

Bit flags for PDFConvertToPdfaParams::flags. Combine with bitwise OR and store in a PDFAConvertFlags value.

Enumerator
kPDFAConvertFlags_ClearSignatures 

If set, all signatures in the source document will be cleared from the output PDF/A document.

kPDFAConvertFlags_RemoveEncryption 

If set, any encryption in the source document will be removed from the output PDF/A document.

kPDFAConvertFlags_Default 

Default: clear all signatures and encryption.

◆ PDFAConvertMode

Defines the conversion mode for PDF to PDF/A conversion.

Enumerator
kPDFAConvertMode_Auto 

Use the PDF/A part from the requested flavor and achieve the highest conformance level possible (A > U > B); downgrade if necessary. Fails only if level B cannot be achieved.

kPDFAConvertMode_Exact 

Succeed only if the exact requested conformance can be achieved. Fail otherwise.

kPDFAConvertMode_Downgrade 

Allow downgrading of the requested conformance if it cannot be achieved (e.g., A -> U -> B). Unlike Auto, this mode never upgrades beyond the requested level. Fails if level B cannot be achieved.

◆ PDFAIssueLevel

The level of severity of the compliance issue, reported via PDFAIssueMonitor.

Enumerator
kPDFAIssueLevel_Info 

Informational note, including issues fixed during processing.

kPDFAIssueLevel_Warning 

Non‑critical finding that may need attention (e.g., metadata inconsistency).

kPDFAIssueLevel_Error 

Conformance violation expected to be fixable automatically (e.g., prohibited actions present).

kPDFAIssueLevel_FatalError 

Unrecoverable condition - conversion cannot proceed (e.g., dictionary too large).

◆ PDFAIssueType

Compliance issue category reported via PDFAIssueMonitor.

Various categories of conversion issues found during analysis that may require fixes in order to achieve a target PDF/A flavor.

Enumerator
kPDFAIssueType_VisualDifferences 

File was converted to PDF/A, but with visual differences compared to the source.

kPDFAIssueType_TargetFlavorAdjusted 

Requested PDF/A flavor was adjusted to an achievable one.

kPDFAIssueType_TargetFlavorUnachievable 

Requested PDF/A flavor cannot be achieved.

kPDFAIssueType_LimitsExceeded 

Implementation limits exceeded.

kPDFAIssueType_NameIsNotValidUtf8 

A Name object (e.g., structure type, colorant) contains bytes that are malformed or do not form a valid UTF‑8 sequence. The validator cannot derive a Unicode representation required by PDF/A.

kPDFAIssueType_ProhibitedFilter 

Cannot decode stream data. Prohibited stream filter present.

kPDFAIssueType_InvalidStreamLength 

A stream object has a missing, non‑numeric, or incorrect /Length entry. The declared length does not match the actual byte count, or the referenced Length object is invalid, preventing reliable parsing of the stream.

kPDFAIssueType_MissingLogicalStructure 

The document lacks a logical structure tree (tagging). No /StructTreeRoot, structure elements, or valid semantic tagging is present, preventing A‑level PDF/A conformance.

kPDFAIssueType_IncorrectLogicalStructure 

The PDF contains a logical structure tree, but it is malformed, inconsistent, or non‑compliant with PDF/PDF‑A tagging rules.

kPDFAIssueType_OptionalContent 

Optional Content Groups (layers) or visibility-controlled content detected. Such content can change appearance and is not permitted in PDF/A.

kPDFAIssueType_IncorrectOptionalContent 

Optional Content Groups or visibility controls are present but invalid, inconsistent, or used in ways that violate PDF/PDF‑A requirements.

kPDFAIssueType_MetadataNonConformant 

The PDF's metadata (Info dictionary or XMP packet) is incomplete, inconsistent, malformed, or otherwise non‑compliant with PDF/A metadata requirements.

kPDFAIssueType_MetadataMissingRequired 

Required PDF/A XMP metadata properties (e.g., pdfaid:part, pdfaid:conformance, or other mandatory fields) are missing from the document’s metadata.

kPDFAIssueType_MetadataInvalidProperty 

An XMP property exists but its value or data type is invalid according to the XMP or PDF/A specification.

kPDFAIssueType_MetadataInvalidNamespace 

The XMP property uses an unknown, undeclared, or disallowed namespace.

kPDFAIssueType_MetadataInvalidStructure 

The XMP structured property is malformed or violates the required structure for its schema (e.g., missing fields, wrong nesting).

kPDFAIssueType_MetadataInvalidPattern 

The XMP property value does not match the required lexical pattern (e.g., date/time format, language tag, URI format).

kPDFAIssueType_DeviceColors 

Device color spaces used where ICC-based color spaces are required.

kPDFAIssueType_IncorrectColorSpaceStructure 

Color space dictionary or components are malformed or violate PDF/PDF‑A rules.

kPDFAIssueType_InvalidICCProfile 

Embedded ICC profile is invalid or does not satisfy PDF/A requirements.

kPDFAIssueType_TransparencyUsage 

Transparency features used where PDF/A requires opaque rendering.

kPDFAIssueType_IncorrectOutputIntent 

Output Intent dictionary exists, but is missing required fields, is invalid, or is inconsistent with document color usage.

kPDFAIssueType_Jpeg2000NonConformant 

JPEG 2000 (JPX/JP2) image violates PDF/A JPEG2000 requirements (see ISO 19005‑4:2020, 6.2.7).

kPDFAIssueType_InvalidImageProperties 

Image properties (Alternates, OPI, Interpolate, Intent) violate PDF/A requirements.

kPDFAIssueType_PostScriptXObjectFound 

PostScript XObject detected (PostScript content is not permitted in PDF/A).

kPDFAIssueType_ProhibitedXObjectProps 

XObject contains properties that are prohibited by PDF/A (e.g., Alternates, OPI, transparency).

kPDFAIssueType_ProhibitedActions 

Document contains prohibited actions (e.g., OpenAction, JavaScript, launch or other interactive actions).

kPDFAIssueType_ProhibitedInteractiveFormProps 

Interactive form (AcroForm) contains prohibited fields or field properties (e.g., submit actions, JavaScript, dynamic behavior).

kPDFAIssueType_ProhibitedAnnotationType 

Annotation uses a subtype that is not permitted in PDF/A.

kPDFAIssueType_InvisibleAnnotation 

Annotation is hidden, non‑printable, or otherwise not visible as required by PDF/A.

kPDFAIssueType_IncorrectAnnotationProps 

Annotation dictionary contains properties that violate PDF/A (e.g., actions, appearance issues, prohibited flags).

kPDFAIssueType_DocumentIsEncrypted 

Document is encrypted or password‑protected, which is not permitted in PDF/A.

kPDFAIssueType_DocumentIsSigned 

Document contains a digital signature, which may violate PDF/A depending on the target conformance level.

kPDFAIssueType_EmbeddedFilesInvalid 

Embedded files or attachments are invalid or not permitted by the PDF/A conformance level.

kPDFAIssueType_EmbeddedFilesNotAssociated 

Embedded files are present, but not correctly associated with document content via the /AF entry (PDF/A‑3/4F requirement).

kPDFAIssueType_EmbeddedFilesMissing 

Required embedded files are missing (PDF/A‑4F requires at least one associated embedded file).

kPDFAIssueType_FontNotEmbedded 

Font is not embedded, but PDF/A requires all fonts to be embedded.

kPDFAIssueType_FontProgramCorrupted 

Embedded font program is corrupted or has an invalid format and needs to be repaired.

kPDFAIssueType_FontMissingCIDSet 

CIDFont descriptor dictionary requires a CIDSet stream (PDF/A‑1).

kPDFAIssueType_FontUnnecessaryCIDSet 

CIDSet stream is present but not required for this PDF/A conformance level (PDF/A‑2+).

kPDFAIssueType_FontFailedToLoadAGL 

Failed to load Adobe Glyph List; some exceptions to the /ToUnicode map requirement cannot be checked.

kPDFAIssueType_FontMissingToUnicode 

Font requires a valid /ToUnicode map, but it is missing, unreadable, unparsable, or invalid due to Private Use Area (PUA) mappings.

kPDFAIssueType_FontGlyphFailMapToUnicode 

Font has glyphs used in content that are unmapped, mapped to invalid Unicode code points, or mapped to the Private Use Area (PUA).

kPDFAIssueType_FontVectorizeTextRun 

Text runs were vectorized (or are expected to be vectorized) due to unmappable glyphs.

kPDFAIssueType_FontNotdefGlyphReference 

A text-showing operator in the content stream references a character code that resolves to the .notdef glyph.

kPDFAIssueType_FontMissingCharSet 

Type 1 font is missing the required CharSet string listing glyph names defined in the font program.

kPDFAIssueType_FontMissingWidths 

Glyph widths are missing or inconsistent with the embedded font program.

kPDFAIssueType_FontSymbolicTrueTypeNonCompliant 

Symbolic TrueType font does not satisfy PDF/A symbolic requirements (e.g., has /Encoding entry, or font program lacks (3,0)/(1,0) cmap subtable).

kPDFAIssueType_FontNonSymbolicTrueTypeNonCompliant 

Non-symbolic TrueType font does not satisfy PDF/A non‑symbolic requirements (e.g., base encoding is not MacRoman/WinAnsi, /Differences names not in AGL, or font program lacks (3,1) cmap subtable).

Function Documentation

◆ PDFConvertToPDFA()

PDFSDK_IMPORT_ PDErrCode PDFSDK_CALLCONV PDFConvertToPDFA ( PDDoc source,
const PDProgressMonitor * progress,
void * progressData,
const PDFAIssueMonitor * issueMon,
void * issueMonData,
const PDFConvertToPDFAParams * params,
PDFAFlavor * producedFlavor )

Converts a PDF document into a PDF/A‑compliant file.

Ownership: source is not modified and not retained; the caller remains responsible for closing it and it stays valid after this call returns.

Thread safety: this function may be called concurrently on distinct PDDoc instances. Concurrent calls that share the same PDDoc are not supported. Monitor callbacks must not reenter the API with the same PDDoc.

Parameters
[in]sourceThe already-opened PDF document to convert. Must not be null.
[in]progressOptional progress monitor. May be null.
See also
PDProgressMonitor.
Parameters
[in]progressDataOpaque pointer forwarded to each progress callback as its clientData argument. May be null.
[in]issueMonOptional compliance-issue monitor. May be null.
See also
PDFAIssueMonitor.
Parameters
[in]issueMonDataOpaque pointer forwarded to each issueMon callback as its clientData argument. May be null.
[in]paramsConversion parameters. Must not be null.
See also
PDFConvertToPDFAParams.
Parameters
[out]producedFlavorOptional. If non-null, receives the flavor actually written to outputFile on success. Relevant when params->mode is kPDFAConvertMode_Auto or kPDFAConvertMode_Downgrade, where the produced flavor may differ from the requested params->flavor. Not written on failure.
Returns
kPDErrSuccess on success. On failure, an error code indicating the cause, including but not limited to: invalid arguments, unwritable outputFile, a source document that cannot be made compliant with the requested flavor under the selected mode, or an abort value returned from a monitor callback.