Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 4 - QuickDraw GX Debugging / Using QuickDraw GX Debugging

Using Validation Functions

QuickDraw GX provides validation functions that check the function parameters of all allocated objects. You can validate the public functions that you use in your application or choose to validate the internal QuickDraw GX functions.

Type validation is the simplest level of validation. QuickDraw GX provides successively more complicated levels of validation when you also check structures and internal caches. The various validation modes and validation levels are described in the section "Validation Functions" beginning on page 4-6.

Controlling Validation

You can use the GXSetValidation function to control the validation of public and private functions used by your application. You control validation by using the GXSetValidation function to set validation level flags for the gxValidationLevel parameter.

void GXSetValidation(gxValidationLevel, level);

You set one flag from the modes in Table 4-8, one flag from the options in Table 4-9, and one or more flags from Table 4-10. The validation modes and levels are defined in the gxValidationLevel enumeration that appears in the section "Drawing Errors" beginning on page 4-29. The GXSetValidation function is described on page 4-34

Once you set the gxValidationLevel parameter, you can use the GXGetValidation function to return the current gxValidationLevel parameter.

The three validation mode options are validation off, public validation, and internal validation. You may choose only one of these validation options. Table 4-8 summarizes the public and internal validation mode options.

Table 4-8 Validation modes

Constant	Value	Explanation
gxNoValidation	0x00	Turns off QuickDraw GX validation.
gxPublicValidation	0x01	Performs validation whenever your application uses a public function.
gxInternalValidation	0x02	Performs validation whenever your application uses a public function or an internal function.

The validation mode flags allow you to selectively turn validation options on and off. You should experience reduction in performance only when validation is on. In the non-debugging version, validation is not operational. However, it is best just to turn validation off by setting the parameter of the GXSetValidation function to gxNoValidation.

If you activate either public validation or internal validation mode, then you must also specify either type validation, structure validation, or all object validation. You may choose only one option. Table 4-9 summarizes the type, structure, and object validation level options.

Table 4-9 Validation levels

Constant	Value	Explanation
gxTypeValidation	0x00	Validates object types of function parameters.
gxStructureValidation	0x10	Validates object structures, caches and function parameters.
gxAllObjectValidation	0x20	Validates object types, structures, and all internal caches built for all objects.

Type Validation

You can select the gxTypeValidation level to check the type passed to all objects. The type validation errors are listed in the section "Debugging Version" in the chapter "Errors, Warnings, and Notices."

The simplest and most commonly used gxValidationLevel parameter value combination is of the gxPublicValidation and gxTypeValidation options:

GXSetValidation(gxPublicValidation | gxTypeValidation);

This combination of options causes QuickDraw GX to verify that the objects used by all public functions your application calls are the correct type. For example, if you call the GXDrawShape function and pass it a style, the GXSetValidation function posts a shape_wrong_type error.

If you want to check the type of all objects that your application passes to both public and internal functions, you can use the gxInternalValidation option plus the gxTypeValidation option for the gxValidationLevel parameter:

GXSetValidation(gxInternalValidation | gxTypeValidation);

This is useful only for detecting GX internal errors.

Structure Validation

You can set the gxStructureValidation validation parameter to check the type and structure for all objects. The structure validation errors are listed in the section "Debugging Version" in the chapter "Errors, Warnings, and Notices."

If you want to check the type of all objects and structure your application passes to public functions, you can use the gxPublicValidation and gxStructureValidation options for the gxValidationLevel parameter:

GXSetValidation(gxPublicValidation | gxStructureValidation);

If you want to check the type of all objects and the structure your application passes to public and internal functions, you can use the gxInternalValidation and gxStructureValidation options for the gxValidationLevel parameter:

GXSetValidation(gxInternalValidation | gxStructureValidation);

This is useful only for detecting internal GX errors.

The gxStructureValidation option might generate validation errors that are not part of the public interface. For example, these options may post a shape_cache_wrong_type error. This suggests only that the application erroneously changed the internal information that identifies a specific shape cache or an internal GX error occured. The correct shape and the correct value for a shape cache are private. The bad_private_flags error means that the application corrupted the flags internal to some structure. This is a private structure and QuickDraw GX provides no additional information for these posted errors. However it is useful for a developer to report the circumstances that produced these errors so that Apple Computer, Inc. can investigate them.

All Object Validation

You can use the gxAllObjectValidation validation level to check the type, structure, and internal caches built for all objects. In addition, it checks objects written to disk and the file structure itself to see if they are corrupt. The all object validation errors are listed in the section "Debugging Version" in the chapter "Errors, Warnings, and Notices."

If an application has an error that randomly writes to some portion of memory, the error can corrupt one object as easily as another. As a result, it is necessary to check all objects to detect this type of error. If a random write occurs in a free memory block or the value is already in the shape type, QuickDraw GX doesn't detect it. Again, this validation allows the developer to discriminate between QuickDraw GX and application problems.

If you want to check the type of all objects, the structure, and the internal caches for all objects each time public functions are called by your application, you can use the gxPublicValidation and gxAllObjectValidation options for the gxValidationLevel parameter:

GXSetValidation(gxPublicValidation | gxAllObjectValidation);

As an alternative to using the gxAllObjectValidation options for the gxValidationLevel parameter of the GXSetValidation function, you can use the GXValidateAll function, described in the section "Validating Objects" beginning on page 4-20. The GXValidateAll function is described on page 4-43.

Memory Validation

Once you pick a validation mode and a validation level, you can then also choose to include or not include memory validation options. Memory validation does not post validation errors. If QuickDraw GX detects a memory validation problem, it drops you into Macsbug or the debugging utility that is installed on your system.

Table 4-10 summarizes the memory validation options, all of which are associated with QuickDraw GX private data structures.

Table 4-10 Memory validation options

Constant	Value	Explanation
gxNoMemoryManagerValidation	0x0000	Turns off memory validation.
gxApBlockValidation	0x0100	Enables additional error checking on application blocks passed as parameters to internal memory routines.
gxFontBlockValidation	0x0200	Enables additional error checking on system blocks, often font caches, passed as parameters to internal memory routines.
gxApHeapValidation	0x0400	Checks all objects in a heap for validity each time an internal memory routine is called.
gxFontHeapValidation	0x0800	Checks all font objects in a heap for validity each time an internal memory routine is called.
gxCheckApHeapValidation	0x1000	When used with gxInternalValidation, checks the application heap on every internal function call. When used with gxPublicValidation, checks the application heap on every public function call.
gxCheckFontHeapValidation	0x2000	When used with gxInternalValidation, checks the font heap on every internal function call. When used with gxPublicValidation, checks the font heap on every public function call.

If you want to check the type of all objects that your application passes to public functions and also check the application heap on every public call, you can use the gxPublicValidation option plus the gxTypeValidation option plus the gxCheckApHeapValidation option for the gxValidationLevel parameter:

GXSetValidation(gxPublicValidation | gxTypeValidation |
                gxCheckApHeapValidation);

WARNING

If the gxApHeapValidation or gxFontHeapValidation flag is enabled and the platform that it is running on locates the graphics memory below the bottom 14 megabytes of memory, then the addresses on the stack and master pointers that refer to QuickDraw GX objects will be scrambled. This is a method of finding internal errors that may lead to unexpected erroneous behavior. For example, if the application has a path type shape and one long parameter of the path data happens to exactly equal the address of a graphics object, then QuickDraw GX might scramble the one long of path data and the path may draw one point off of the screen. This is expected behavior. These functions can scramble addresses without knowing that the addresses are really points on a path. Since these two validation types produce these apparent bugs, an application cannot use the gxApHeapValidation and gxFontHeapValidation options to ensure that QuickDraw GX has no internal bugs. These validation types are useful in tracking down bugs related to QuickDraw GX memory management.

For additional information about using QuickDraw GX memory, see the chapter "QuickDraw GX Memory Management."

The GXSetValidation function is described on page 4-34. The GXGetValidation function is described on page 4-35.

Validating Objects

QuickDraw GX also provides separate functions that validate the parameters passed to specific objects, their structures, and any internal caches built for specific objects.

You can use the GXValidateAll function to check the type, structure, and internal caches built for all objects. This is an alternative to using the GXSetValidation function with the gxInternalValidation and gxAllObjectValidation options selected, as described in the section "Using Validation Functions" beginning on page 4-15.

The following functions validate specific objects:

• The GXValidateColorSet function checks parameters for the color space, color-value array, owner count, and tag list properties for the specified color set object. The GXValidateColorSet function is described on page 4-38.
• The GXValidateColorProfile function checks the specified color profile object. The GXValidateColorProfile function is described on page 4-39.
• The GXValidateGraphicsClient function checks all properties of a specified graphics client object. The GXValidateGraphicsClient function is described on page 4-42.
• The GXValidateInk function checks parameters for the color, transfer mode, attributes, owner count, and tag list properties for a specified ink object. The GXValidateInk function is described on page 4-37.
• The GXValidateShape function checks parameters for the type, geometry, fill, style, ink, transform, attributes, owner count, and tag list properties for a specified shape object. The GXValidateShape function is described on page 4-36.
• The GXValidateStyle function checks parameters for the pen size, cap, join, dash, pattern, curve error, attributes, text face, text size, justification, font variations, platform, text attributes properties, run controls, run features array, glyph substitutions array, kerning adjustments, priority justification override, and glyph justification overrides array properties for the specified style object. The GXValidateStyle function is described on page 4-36.
• The GXValidateTag function checks the parameters for the tag type, size, contents, and owner count properties for a specified tag object. The GXValidateTag function is described on page 4-39.
• The GXValidateTransform function checks the parameters for the clip, mapping, view port list, hit-test parameters, attributes, owner count, and tag list properties for a specified transform object. The GXValidateTransform function is described on page 4-38.
• The GXValidateViewDevice function checks parameters for the clip, mapping, bitmap, attributes, and tag list properties for a specified view device object. The GXValidateViewDevice function is described on page 4-40.
• The GXValidateViewPort function checks parameters for the clip, mapping, dither, halftone, parent view port, child view port list, view device, attributes, owner count, and tag list properties for all view port objects. The GXValidateViewPort function is described on page 4-40.
• The GXValidateViewGroup function checks parameters for the clip, mapping, dither, halftone, parent view port, child view port list, view device, attributes, owner count, and tag list properties of the view port object and the clip, mapping, bitmap, attributes, and tag list properties of the view device object. The GXValidateViewGroup function is described on page 4-41.

Analyzing the Cause of Validation Errors

You can use the GXGetValidationError function to determine the function and parameter that caused the last validation error. This function works like other QuickDraw GX functions that return variable-length data. There are three steps:

1. Call the function to determine the length of data that will be returned. If no validation error is posted, a 0 is returned.
2. Allocate memory to store the data that will be returned.
3. Call the function a second time to obtain pointers to the function, parameter name, and parameter number that caused the validation error.

Listing 4-1 gives an example of using the GXGetValidationError function to obtain the function and parameter that caused the last validation error. The GXGetValidationError function is described on page 4-35.

Listing 4-1 Determining the function and parameter that caused the last validation error

static void DisplayErrorMessage(gxGraphicsError errorID, 
long context)
{
   char buffer[255];
   void * graphicsObject;
   long argNum;

   if (GXGetValidationError(buffer, &thing, &argNum)) {
      GXValidationError(buffer, nil, nil);
      printf("gxValidationError: %ld (routine: %s) ",
         errorID, buffer);
      printf("(argument[%ld]: 0x081x)\n",argNum, graphicsObject);
   } else
      printf("gxGraphicsError: 0x%081x\n", errorID);
}

Distinguishing Between Application Bugs and QuickDraw GX Bugs

All QuickDraw GX functions have been extensively tested prior to shipment. However, during your application debugging process, you may find anomalous behavior that you attribute to QuickDraw GX private functions.

Validation checking allows you to distinguish between your application bugs and QuickDraw GX bugs. If QuickDraw GX posts validation errors when internal validation is set, but not when public validation is set, it is possible that you have found an error in the QuickDraw GX internal private code. Please contact Apple Developer Technical Support and provide a detailed report of the bug encountered. For more information concerning public and internal validation modes, see the section "Controlling Validation" beginning on page 4-15.

Detecting Corrupted Objects

Normally, there is no way for an application using the public interface to corrupt the content of an object. If an error occurs with structure validation and not with type validation, either the error is a QuickDraw GX error or the application has corrupted memory. The most probable method of corrupting memory is by calling the GXGetShapeStructure function and altering the content directly or by writing randomly into memory. For more information concerning type and structure validation levels, see the section "Controlling Validation" beginning on page 4-15.