Error Detection and Handling

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 (in your program code) needed. After placing the error or errors 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:

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 you may 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 thorough explanations of its arguments.

	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), &lineNumber, &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); } }

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),
                        &lineNumber, &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.

ImageGear Professional DLL v18.1 for Windows
Error Detection and Handling
Send Feedback