ImageGear functions handle all errors in a single, uniform way. Even low-level ImageGear functions that you cannot call directly handle errors in this same way.

When an error condition is detected by an ImageGear function, the function places an error code indicating specifically what happened, along with information about where the error occurred, in an internal memory area called the ImageGear error stack. This error stack remains available to your application as it executes, so you can inspect and treat the errors where needed (in your program code). After placing the error(s) on the error stack, the ImageGear function returns to its caller (returning the count of errors now on the stack, if the function's return type is AT_ERRCOUNT).

More than one error may be placed on the error stack as a result of a single ImageGear function call. This is because an ImageGear function that you call will often call lower-level ImageGear functions (not directly callable by your application). Each such lower level function may itself place an error onto the error stack before returning to its caller. Upon return to your application, there may be several errors on the stack. Note that in such a case, the lowest level function's error was placed on the stack first, and the highest level function (the one that your application called directly) placed its error on the stack last, just before returning to your application, because it could not proceed (due to the error).

ImageGear provides the following general functions for accessing the error stack:

The following additional functions are available:

The following functions provide access to error callback functions and data:

The example below shows how to get information about all errors on the error stack using IG_err_error_get function. Refer to a description of this function in the Core Component API Function Reference for a thorough explanations of its arguments. The Error Handling Sample provides a more in-depth examination of using ImageGear error handling.

 
HIGEAR hIGear = 0;              // Will hold the handle returned by IG_load_file
AT_ERRCOUNT nErrCount;          // Count of errors on the stack upon function return

// Load image file "picture_bad.bmp" from working directory 
// and obtain the image's HIGEAR handle:
nErrCount = IG_load_file ( "picture_bad.bmp" , &hIGear );
if(nErrCount != 0)
{
        // Get all errors and report them
        AT_INT i;
        CHAR szFileName[MAX_PATH]; // ImageGear source file name where the error occurred
        INT nLineNumber; // Line number where the error occurred
        AT_ERRCODE nErrCode; // Error code
        AT_INT nValue1; // First value associated with the error
        AT_INT nValue2; // Second value associated with the error
        CHAR szExtraText[1024]; // Text description of the error
        for(i = 0; i < nErrCount; i ++)
        {
                IG_err_error_get(0, (UINT)i, szFileName, (UINT)sizeof(szFileName),
                        &nLineNumber, &nErrCode, &nValue1, &nValue2, szExtraText,
(UINT)sizeof(szExtraText));
                        // Process the error information
                        //...
        }
}
else    
{
        //...
        // Destroy the image
        if(IG_image_is_valid(hIGear))
        {
                IG_image_delete(hIGear);
        }
}