Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records / Writing Object Callback Functions

Writing Marking Callback Functions

Marking callback functions allow applications such as databases that can mark their own objects to take advantage of that capability when resolving object specifier records. Instead of returning a list of tokens for a group of Apple event objects that pass a test, your application can simply mark the Apple event objects and return a token that identifies how they have been marked. In this way, you can speed the resolution of complex object specifier records and reduce the amount of memory you need to allocate for tokens.

The use of marking callback functions is optional and usually makes sense if (a) you can reasonably expect that the tokens created in the process of resolving some object specifier records might not all fit in memory at once or (b) your application already uses a marking mechanism. If you want the Apple Event Manager to use marking callback functions provided by your application, you must add the kAEIDoMarking constant to the value of the callbackFlags parameter for the AEResolve function. If for any reason your application cannot mark a requested set of Apple event objects, it should return errAEEventNotHandled as the result code, and the Apple Event Manager will attempt to continue resolving the object specifier record by some other method, such as using a system marking function, if one exists.

If your application supports marking callback functions, it must provide three functions with declarations that match these examples:

FUNCTION MyGetMarkToken (containerToken: AEDesc; 
                         containerClass: DescType; 
                         VAR Result: AEDesc): OSErr;
FUNCTION MyMark (theToken: AEDesc; markToken: AEDesc; 
                 markCount: LongInt): OSErr;
FUNCTION MyAdjustMarks (newStart, newStop: LongInt; 
                        markToken: AEDesc): OSErr;

For more detailed information about these sample declarations, see "Object Callback Functions," which begins on page 6-109.

To resolve a given object specifier record with the aid of the marking callback functions provided by your application, the Apple Event Manager first calls your application's mark token function (MyGetMarkToken), passing a token that identifies the container of the elements to be marked in the containerToken parameter and the container's object class in the containerClass parameter. The mark token function returns a mark token. A mark token, like other tokens, can be a descriptor record of any type; however, unlike other tokens, it identifies the way your application marks Apple event objects during the current session while resolving a single test. A mark token does not identify a specific Apple event object; rather, it allows your application to associate a group of objects with a marked set.

After it receives the mark token, the Apple Event Manager can call your application's object-marking function (MyMark) repeatedly to mark specific Apple event objects. The Apple Event Manager passes the following information to your marking function: in the theToken parameter, a token for the object to be marked (obtained from the appropriate object accessor function); in the markToken parameter, the current mark token; and in the markCount parameter, the mark count. The mark count indicates the number of times the Apple Event Manager has called the marking function for the current mark token. Your application should associate the mark count with each Apple event object it marks.

When the Apple Event Manager needs to identify either a range of elements or the absolute position of an element in a group of Apple event objects that pass a test, it can use your application's mark-adjusting function (MyAdjustMarks) to unmark objects that it has previously marked. For example, suppose an object specifier record specifies "any row in the table 'MyCustomers' for which the City column is 'San Francisco.'" The Apple Event Manager first uses the appropriate object accessor routine to locate all the rows in the table for which the City column is "San Francisco" and calls the application's marking function repeatedly to mark them. It then generates a random number between 1 and the number of rows it found that passed the test and calls the application's mark-adjusting function to unmark all the rows whose mark count does not match the randomly generated number. If the randomly chosen row has a mark count value of 5, the Apple Event Manager passes the mark-adjusting function 5 in both the newStart parameter and the newStop parameter, and the current mark token in the markToken parameter. The newStart and newStop parameters identify the beginning and end of the new set of marked objects that the mark-adjusting function will create by unmarking those previously marked objects not included in the new set.

When the Apple Event Manager calls your mark-adjusting function, your application must dispose of any data structures that it may have created to mark the previously marked objects. The Apple Event Manager calls your mark-adjusting function only once for a given mark token.

A mark token is valid until the Apple Event Manager either disposes of it (by calling AEDisposeToken) or returns it as the result of the AEResolve function. If the final result of a call to the AEResolve function is a mark token, the Apple event objects currently marked for that mark token are those specified by the object specifier record passed to AEResolve, and your application can proceed to do whatever the Apple event has requested. Note that your application is responsible for disposing of a final mark token with a call to AEDisposeToken, just as for any other final token.

If your application supports marking, it should also provide a token disposal function. When the Apple Event Manager calls AEDisposeToken to dispose of a mark token that is not the final result of a call to AEResolve, the subsequent call to your token disposal function lets you know that you can unmark the Apple event objects marked with that mark token. A call to AEDisposeDesc to dispose of a mark token (which would occur if you did not provide a token disposal function) would leave the objects marked.