Exception codes and error messages for the Adobe PDF Library are listed in the AcroErr.h header file. You will find this in the product installation package, in the directory called /CPlusPlus/Include/Headers.
The Adobe PDF Library creates error messages using a macro defined in AcroErr.h (lines 291-316). The product provides each error code as a series of bit field values, concatenated together into a single larger number.
The Adobe PDF Library offers an API, ASGetErrorString, that translates error codes into error messages that are easy to read and prints them to a command line monitor.
const char *ASGetErrorString(ASErrorCode errorCode, char *buffer, ASTArraySize lenBuffer);
ASGetErrorString() has three parameters:
ASGetErrorString() returns a pointer to buffer, but this pointer does not by itself indicate that the function worked. If the buffer was memset to 0, call strlen on the returned buffer to determine if the error code was valid.
For example, the following code will convert an error code into an error message string, and print that string to stderr:
ASGetErrorString(ERRORCODE, buf, sizeof(buf));
fprintf(stderr, "Error code: %ld, Error Message: %sn", ERRORCODE, buf);
The use of the ASGetErrorString API is demonstrated in the sample program APDFLDoc.cpp. Find this sample program in your Adobe PDF Library software installation package:
The samples found in this directory are called by other Library sample programs.
The Adobe PDF Library provides each error code as a series of bit field values, concatenated together into a single larger number. You can interpret the message by converting the decimal value that results into hexadecimal. The hexadecimal number is always eight digits long.
Remember that each hexadecimal number is a single digit that represents one of 16 values, between 0 and 15. Hexadecimal digits are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F.
It is easier to read if you use a decimal to hexadecimal code converter utility to convert the error code to hex notation, and then parse the hex version of the error code.
You can also use the Windows 10 calculator app.
Open the calculator and click the icon in the upper left corner.
Type in a value for Dec to convert it to Hex. Try typing 1073938471:
Note that if you have an error code that is eight digits, it might be hexadecimal already.
Consider this example. The error code 1073938471 can be converted to hex code 40030027, as shown in the Windows Calculator screens above. You can then parse that hex code into four fields:
Severity Level. The ERR_SEVERITY_MASK values are found at lines 152 to 179 AcroErr.h header file.
The width of the field is four bits, and the format is designed to allow for up to 16 possible Severity Levels (2 to the 4th power). The Adobe PDF Library provides five levels, but you can add your own custom Severity Levels to the header file if you like.
The Severity Levels include:
|ErrNoError=0||No error occurred|
|ErrWarning||Display a warning|
|ErrSuppressable||Display a message if the user has not suppressed errors|
|ErrSilent||Never display a message|
|ErrAlways||Always display a message, even if others are suppressed|
System Number. The ERR_SYSTEM_MASK refers to internal systems within the Adobe PDF Library, or categories of the type of errors displayed. Adobe PDF Library provides 19 default System types, but provides room for up to 256, so you can add many more System types to your APDFL application.
The default error messages provided by the Library are found in lines 183-282 of the AcroErr.h header file, and are listed below.
|ErrSysNone=0||General errors and out of memory errors|
|ErrSysCos||CosStore filter errors|
|ErrSysCosSyntax||Cos syntax errors|
|ErrSysPDDoc||PDDoc and family, Page tree, outlines errors|
|ErrSysPDPage||PDPage and family, thumbs, annotations errors|
|ErrSysPDModel||Global PD errors|
|ErrSysPage||Page parsing and RIPping errors|
|ErrSysFontSvr||Font Server errors|
|ErrSysASFile||ASFile I/O errors|
|ErrSysXtnMgr||Extension Manager errors|
|ErrSysXtn||New error codes added by extensions|
|ErrSysMDSystem||Platform-specific system errors|
|ErrSysMDApp||Platform-specific application errors|
|ErrSysPDSEdit||PDSEdit (structure) errors|
|ErrSysPDMetadata||XAP Metadata errors|
Error Number. The ERR_ERROR_MASK code maps to the individual error message, such as "pdErrNeedPassword," which means that a required password is missing.
The error number refers to the position of the error message in the list of error messages for the System. In this example, error number 0027 would be the 27th message found under system number 3, Cos Syntax Errors. So each error number is unique.
The list of error masks begins in the AcroForms.h header file with /*General Errors*/ at line 318, and continues to the end of the file. These are the errors provided with the Adobe PDF Library. Note that Datalogics also created error messages that can be returned, related to the .NET or Java Interfaces, or .NET Core.
The AcroErr.h header file provides 22 different categories for error messages, with six of these categories specific to individual platforms, such as Windows errors and macOS errors. The rest of the error messages can apply to any platform.
The error messages can be generic, such as "bad parameter." Keep in mind that functions call other functions; it could be that a function that expected a dictionary was passed something else. Even though the initial parameters were valid, you could still see a bad parameter error appearing from a function deep in your system workflow.
Error code 1073741825
|1||Convert number to Hex||4000 0001|
|2||Count to the severity item||4||ErrAlways|
Count to the system item
Count to error item
Error code 537067605
|1||Convert number to Hex||2003 0555|
|2||Count to the severity item||2||ErrSuppressable|
Count to the system item
Count to error item
|85 (hex 55 is decimal 85)||cosSynErrBadCharInHexString|