xil_error_get_string(3)

NAME

xil_error_get_string, xil_error_get_id, xil_error_get_category, xil_error_get_category_string, xil_error_get_location, xil_error_get_primary, xil_error_get_object, xil_object_get_error_string, xil_object_get_type − get information about errors and the objects affected by errors

SYNOPSIS

#include <xil/xil.h>

char ∗xil_error_get_string ( XilError error);

char ∗xil_error_get_id ( XilError error);

XilErrorCategory xil_error_get_category ( XilError error);

char ∗xil_error_get_category_string ( XilError error);

char ∗xil_error_get_location ( XilError error);

Xil_boolean xil_error_get_primary ( XilError error);

XilObject xil_error_get_object ( XilError error);

void xil_object_get_error_string ( XilObject object,

char ∗string,
int string_size);

XilObjectType xil_object_get_type ( XilObject object);

DESCRIPTION

These functions can be used by an error handler (installed with xil_install_error_handler(3) to retrieve information about an error when it occurs.

xil_error_get_string () returns an error string in the currently configured language.

xil_error_get_id () returns a character string that uniquely identifies the error.

xil_error_get_category () returns the general category of the error. See XilErrorDefines.h for the list of categories.

xil_error_get_category_string () returns a character string that identifies the category of the error.

xil_error_get_location () returns information that indicates where the error occurred in the XIL library. By reporting this information to support personnel, you can help pinpoint the source of the problem.

xil_error_get_primary () returns TRUE if the currently reported error is the primary cause of the error. For instance, if memory runs out and an image cannot be created, then the primary error would be an XIL_ERROR_RESOURCE error at image creation. Secondary errors might also be generated as the NULL image is used internally in the XIL library.

xil_error_get_object () returns the XIL object that an error occurred on. This object can then be used in the error handler to query for additional information about the object, either through xil_object_get_error_string () or through direct calls to the object.

xil_object_get_error_string () creates a string with additional information about the object involved in the error. This string may then be used in the error handler to provide additional information about the error.

xil_object_get_type () returns an enumeration constant that indicates the type of an object. This enumeration constant can be used in an error handler to take an XilObject and cast it to the appropriate type of XilObject. For example, after the object has been cast to XilImage, then additional information about the object is available. The following excerpt from XilDefines.h lists the possible XilObjects:

typedef enum {
XIL_IMAGE,
XIL_IMAGE_TYPE,
XIL_LOOKUP,
XIL_CIS,
XIL_DITHER_MASK,
XIL_KERNEL,
XIL_SEL,
XIL_ROI,
XIL_ROI_LIST,
XIL_HISTOGRAM,
XIL_COLORSPACE
} XilObjectType;

ERRORS

For a complete list of XIL error messages by number, consult Appendix B of the XIL Programmer’s Guide.

EXAMPLES

Create an error handler that puts out information about the category,
the error, the id, and any additional object information. Also output
the width of the image if the error object is an image.

Xil_boolean my_error_func(XilError error)
{
#define MAX 1024
XilObject obj;
char buffer[MAX];
printf("XIL Error category: %s\n", xil_error_get_category_string(error));
printf("XIL Error string: %s\n", xil_error_get_string(error));
printf("XIL Error id: %s\n", xil_error_get_id(error));
obj = xil_error_get_object(error);
if (obj) {
    xil_object_get_error_string(obj,buffer,MAX);
    if (buffer[0] != 0)
        printf("XIL Object info: %s\n", buffer);
    if ( xil_object_get_type(obj) == XIL_IMAGE)
        printf("Image Width: %d\n", xil_get_width( (XilImage)obj ));
}
return TRUE;

}

NOTES

The character pointer returned from xil_error_get_string () points to data internal to the error object and should not be freed or modified.

Museum

Related Articles