Error Codes
Functions return an HRESULT value in most cases. This provides a simple method to determine the success/failure of a function call.
If the most significant bit/result is set to 1 then the specified error occurred. Any other result means the function was successful. The following macros for C/C++ apply these checks:
#define IS_DS_SUCCESSFUL(x) (((x) & 0x80000000) == 0)
#define IS_DS_FAILED(x) (((x) & 0x80000000) != 0)
Note: it is strongly recommended to use the same macros consistently in order to establish the success of function calls. A simple comparison with zero often results in unreliable data, as detailed in the example below.
Please note that the macros detailed above are case-sensitive.
Functions may return warnings with a code that is neither equal to zero nor negative. Usually this means that the function was successful and is providing additional information about the call, for example that a default value was returned. See the table below for further information.
The following code is an example of how error-checking should not be performed:
HRESULT hr = PXCV_CheckPassword(doc, password, len);
if (hr == 0)
{
// treat as success
...
(this is not true as a positive return value was received!)
...
}
else
{
// treat as error
(Incorrect as the return value has not been adequately identified and this is unreliable!)
...
}
The IS_DS_WARNING macros can be used to determine if the return value generates a warning. The following code can be used to check for the error status of the PXCV_CheckPassword function:
HRESULT hr = PXCV_CheckPassword(doc, password, len);
if (IS_DS_FAILED(hr))
{
// An error occurred!
// Manage the error accordingly to provide an orderly exit from the function call
...
}
else
{
// 'hr' contains a value that indicates whether the password supplied was owner or user
...
}
The most common error codes are listed in the table below, but it should be noted that functions may return other error codes.
CONSTANT
|
VALUE
|
DESCRIPTION
|
OCR_ERR_NOTIMPL
|
0x820a04b0
|
Not implemented.
|
OCR_ERR_INVARG
|
0x820a0001
|
Invalid argument.
|
OCR_ERR_MEMALLOC
|
0xc20a03e8
|
Insufficient memory.
|
OCR_ERR_USER_BREAK
|
0xc20a01f4
|
Operation aborted by user.
|
OCR_WRN_USER_BREAK
|
0x820f0011
|
Operation completed but user requested break.
|
OCR_ERR_DOCNOTREAD
|
0x820a2711
|
Input document empty.
|
OCR_ERR_WRONGPAGENUMBER
|
0x820a2712
|
Invalid page requested.
|
OCR_ERR_DOCHASNOPAGES
|
0x820a2713
|
Document has no pages.
|
OCR_ERR_NOTLICENSED
|
0x820a2714
|
Operation requested not allowed by license.
|
OCR_WRN_NOTLICENSED
|
0x420a2715
|
Operation completed but some portions not allowed.
|
OCR_ERR_INTERNAL
|
0x820a2717
|
Unspecified internal error.
|
OCR_ERR_POINTER
|
0x820a2718
|
NULL pointer received.
|
OCR_WRN_NORESULTS
|
0x420a2716
|
Operation completed but no results were found.
|
OCR_WRN_NOTROTATED
|
0x420a2719
|
Operation completed but one or more pages were not auto-rotated due to failure determining rotation angle (possibly because the page is blank).
|
OCR_WRN_FIELDBOUNDS
|
0x420a271a
|
Operation completed but one or more PXO_InputField structures specified rectangles that were partially outside of the bounds of the page. Rectangles were truncated to fit the PDF page.
|
OCR_ERR_FIELDBOUNDS
|
0x820a271b
|
Operation did not complete because one or more PXO_InputField structures specified rectangles that were either empty or located fully outside of the PDF page boundaries.
|
Comments
The utility DSErrorLookUp.exe can provide additional error code data. This is a very useful application development tool and can be found in the installation folders. Please note that the errors contained in the DSErrorLookUp utility may not yet be comprehensive as the PDF-XChange PSO SDK is still in development, but they will be updated in future releases.