<< Click to Display Table of Contents >> Navigation:  Error Handling > Error Codes

---

 

Error Codes

 

---

 

Functions return an HRESULT value in most cases. This provides a simple means to determine the success/failure of a function call.

 

If the most significant bit or 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 will often result in unreliable data, as detailed in the example below.

 

Please note that these macros are case-sensitive.

 

Functions may return warning codes that are 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 Functions for further information.

 

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 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 most common error codes are listed in the table below, but it should be noted that functions may return other error codes. There are three further functions available for dealing with errors that may provide additional information: PXCV_Err_FormatSeverity, PXCV_Err_FormatFacility and PXCV_Err_FormatErrorCode. A code example is provided below the table. Please note that this function will provide information about all possible error codes.

 

Possible error values of PDF parser/structure:

 

 

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. It is strongly recommended that developers utilize DSErrorLookUp.exe to debug their applications during the development process.

 

Example (C++)

 

// Using of PXCV_Err_FormatSeverity, PXCV_Err_FormatFacility, PXCV_Err_FormatErrorCode functions

char* err_message = NULL;

char* buf = NULL;

_PXCPage* p = NULL;

    // Code below should always return an error and never work

HRESULT dummyError = PXCV_ReadDocumentW(NULL, NULL, 0);

LONG sevLen = PXCV_Err_FormatSeverity(dummyError, NULL, 0);

LONG facLen = PXCV_Err_FormatFacility(dummyError, NULL, 0);

LONG descLen = PXCV_Err_FormatErrorCode(dummyError, NULL, 0);

if ((sevLen > 0) && (facLen > 0) && (descLen > 0))

{

    // Total length of the formated text is the sum of the length for each description

    // plus some additional characters for formating

    LONG total = sevLen + facLen + descLen + 128;

    // allocate buffer for message

    err_message = new char[total];

    err_message[0] = '\0';

    // allocate temporary buffer

    buf = new char[total];

    // get error severity and append to message

    if (PXCV_Err_FormatSeverity(dummyError, buf, total) > 0)

        lstrcat(err_message, buf);

    lstrcat(err_message, " [");

    // get error facility and append to message

    if (PXCV_Err_FormatFacility(dummyError, buf, total) > 0)

        lstrcat(err_message, buf);

    lstrcat(err_message, "]: ");

    // and error code description and append to message

    if (PXCV_Err_FormatErrorCode(dummyError, buf, total) > 0)

        lstrcat(err_message, buf);

    ::MessageBox(NULL, err_message, "Test error", MB_OK);

    delete[] buf;

    delete[] err_message;

}

 

---