ImageGear for C and C++ on Windows v19.10 - Updated
Handling Warnings and Errors
User Guide > How to Work with... > Handling Warnings and Errors

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).

For information about ImageGear error codes, see Function Error Return Codes.

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

IG_err_stack_clear

Deletes all records (errors and warnings) from the error stack.

IG_err_count_get

Returns the total number of records (errors plus warnings) on the error stack.

IG_err_error_check

Returns the number of records of the specified level (either errors or warnings) on the error stack.

IG_err_error_get

Retrieves information about a record on the specified level of the error stack. Use this function if you are only interested in errors but not in warnings, or only warnings and not errors.

IG_err_record_get

Obtains information about a record on the error stack. Use this function if you are interested in both errors and warnings.

IG_err_error_set

Places a record onto the error stack.

The following additional functions are available:

IG_error_check

Returns the number of errors currently on the error stack.

IG_error_clear

Despite its name, clears both errors and warnings from the stack. Same as IG_err_stack_clear.

IG_error_get

Retrieves information about an error from the error stack.

IG_error_set

Places an error record onto the error stack.

IG_warning_check

Returns the number of warnings currently on the ImageGear error stack.

IG_warning_clear

Clears all warnings from the error stack.

IG_warning_get

Retrieves an ImageGear warning Code and associated information from the error stack.

IG_warning_set

Places an ImageGear warning onto the error stack.

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

IG_err_callback_get

Obtains error stack callback data and functions that are called to signal error stack changes for the current thread.

IG_err_callback_set

Sets error stack callback data and functions that are called to signal error stack changes for the current thread.

IG_errmngr_callback_get

Obtains error stack callback data and functions that are called to signal error stack changes for all threads.

IG_errmngr_callback_set

Sets error stack callback data and functions that are called to signal error stack changes for all threads.

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.

 C and C++
Copy Code
 
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);
        }
}
 

Each ImageGear function, excluding all IG_dspl_...() functions, clears the error stack upon entry. Therefore, after an ImageGear function call, you should check the stack prior to your next ImageGear function call.