Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 3 - Errors, Warnings, and Notices / Errors, Warnings, and Notices Reference

Functions / Error Posting and Handling

GXSetUserGraphicsError

You can use the GXSetUserGraphicsError function to install an error handling function.

void GXSetUserGraphicsError(gxUserErrorFunction userFunction, 
                           long reference);

userFunction

The application's error handling function that is to be passed the error code.

reference

A long value that is passed each time an error occurs. This value can be used by the application for any purpose.

DESCRIPTION

The GXSetUserGraphicsError function installs an application-defined error handling function. This function installs a function pointer that is called whenever an error is posted. Setting the userFunction parameter to nil removes the error handling function.

The userFunction parameter points to an application-defined error handler defined by the following type:

typedef void (*gxUserErrorProcPtr)(gxGraphicsError status, 
               long reference);
typedef gxUserErrorProcPtr gxUserErrorFunction;

The second parameter is the long reference number. Whenever the application posts an error, the installed error handling function is called with the error number. The reference number is passed to the GXSetUserGraphicsError function.

You can install an error handler before calling the GXEnterGraphics function, but you should call the GXNewGraphicsClient function first. If you don't, GXNewGraphicsClient will be called for you.

SPECIAL CONSIDERATIONS

If the error number posted by the application is within the QuickDraw GX range of fatal errors, execution continues with undefined results. The fatal error range is bounded by error numbers -27999 and -27951.

If the error number posted by the application is within the QuickDraw GX range of nonfatal errors, execution continues, but results may be other than that expected. The nonfatal error range is bounded by error numbers -27950 and -27000.

SEE ALSO

The use of this function is described in the section "Installing an Error, Warning, or Notice Handler" beginning on page 3-38.

The GXGetUserGraphicsError function used to return a pointer to the application-defined error-handling function is described in the next section.

An alternative method of posting errors is to use the QuickDraw GX error messages. This topic is discussed in the section "Obtaining Errors, Warnings, and Notices" beginning on page 3-30.

The GXGetGraphicsError function described on page 3-54 is used to obtain the first and last QuickDraw GX errors posted.

The application-defined error handler is described on page 3-70.