Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records

Writing Object Callback Functions

If an Apple event parameter consists of an object specifier record, your handler for the Apple event typically calls AEResolve to begin the process of locating the requested Apple event object or objects. In turn, AEResolve calls object accessor functions and, if necessary, object callback functions provided by your application.

Every application that supports Apple event objects should provide object accessor functions that can locate Apple event objects belonging to any of the supported object classes. For an overview of the way AEResolve calls object accessor functions to locate Apple event objects described by object specifier records, see "Resolving Object Specifier Records," which begins on page 6-4.

In addition to object accessor functions, your application can provide up to seven object callback functions:

• An object-counting function counts the number of elements of a specified class in a specified container, so that the Apple Event Manager can determine how many elements it must examine to find the element or elements that pass a test. Your application must provide one object-counting function to handle object specifier records that specify tests. (See "Writing an Object-Counting Function," which begins on page 6-56.)
• An object-comparison function compares one element either to another element or to a descriptor record and returns either TRUE or FALSE. Your application must provide one object-comparison function to handle object specifier records that specify tests. (See "Writing an Object-Comparison Function" on page 6-58.)
• A token disposal function disposes of a token after your application calls the AEDisposeToken function. If your application doesn't provide a token disposal function, the Apple Event Manager uses the AEDisposeDesc function instead. Your application must provide a token disposal function if it requires more than a call to AEDisposeDesc to dispose of one of its tokens. This is true, for example, if your application supports marking by modifying its own data structures. (See page 6-111 for the declaration of a token disposal function.)
• An error callback function gives the Apple Event Manager an address to which to write the descriptor record it is currently working with if an error occurs while AEResolve is attempting to resolve an object specifier record. Your application is not required to provide an error callback function. (See page 6-112 for the declaration of an error callback function.)
• Three marking callback functions are used by the Apple Event Manager to get a mark token from your application, to mark specific Apple event objects, and to pare down a group of marked Apple event objects. Your application must provide all three marking functions if it supports marking. (See "Writing Marking Callback Functions" on page 6-62.)

To make your object callback functions available to the Apple Event Manager, use the AESetObjectCallbacks function:

myErr := AESetObjectCallbacks (@MyCompareObjects,
                               @MyCountObjects, @MyDisposeToken,
                               @MyGetMarkToken, @MyMark, 
                               @MyAdjustMarks, @MyGetErrDesc);

Each parameter to the AESetObjectCallbacks function consists of either a pointer to the corresponding application-defined function or NIL if no function is provided. The AESetObjectCallbacks function sets object callback functions that are available only to your application. To set system object callback functions, which are available to all applications and processes running on the same computer, use the AEInstallSpecialHandler function as described on page 4-96.

To handle object specifier records that specify tests, your application must provide an object-counting function and an object-comparison function. The Apple Event Manager calls your application's object-counting function to determine the number of Apple event objects in a specified container that need to be tested. The Apple Event Manager calls your application's object-comparison function when it needs to compare one Apple event object to either another Apple event object or to a value in a descriptor record.

If your application does not provide a token disposal function, the Apple Event Manager uses the AEDisposeDesc function to dispose of tokens. This function does the job as long as disposing of tokens involves nothing more than simply disposing of a descriptor record. Otherwise, you need to provide custom token disposal function. For example, suppose the data field of a token descriptor record contains a handle to a block that in turn contains references to storage for the Apple event object referred to by the token. In this case, the application can provide a token disposal function that performs the tasks required to dispose of the token and any associated structures.

Whenever more than one Apple event object passes a test, AEResolve can either return a list of tokens or make use of a target application's ability to mark its own objects. Sometimes a list of tokens can become unmanageably large. For example, if a Get Data event asks for the names and addresses of all customers with a specified zip code who have purchased a specified product, the object accessor function that locates all the customers with the specified zip code might return a list of many thousands of tokens; the elements identified by those tokens would then have to be tested for the specified product. However, if your application uses some method of marking objects, you can choose simply to mark the requested objects rather than returning a list of tokens. "Writing Marking Callback Functions" on page 6-62 describes how to do this. If your application supports marking by modifying its own data structures, you must provide a token disposal function.

When one of your application's Apple event handlers calls the AEResolve function, the handler should pass a value in the callbackFlags parameter that specifies whether your application supports whose descriptor records or provides marking callback functions. You can add the following constants, as appropriate, to provide a value for the callbackFlags parameter:

CONST kAEIDoMinimum  =  $0000; {does not handle whose tests or }
                                 { provide marking callbacks}
      kAEIDoWhose    =  $0001; {supports key form formWhose}
      kAEIDoMarking  =  $0004; {provides marking functions}

For example, this code instructs the Apple Event Manager to call any marking functions previously set with the AESetObjectCallbacks function while resolving the object specifier record in the objectSpecifier parameter:

VAR
   objectSpecifier:    AEDesc;
   resultToken:        AEDesc;
   myErr:              OSErr;

myErr := AEResolve(objectSpecifier, kAEIDoMarking, resultToken); 

If any of the marking callback functions are not installed, AEResolve returns the error errAEHandlerNotFound.

IMPORTANT

If your application doesn't specify kAEIDoWhose, the Apple Event Manager attempts to resolve all object specifier records of key form formTest. To do so, the Apple Event Manager uses your application's object-counting and object-comparison functions, and returns a token of type typeAEList.

If your application does specify kAEIDoWhose, the Apple Event Manager does not attempt to resolve object specifier records of any key form. In this case, the object-counting and object-comparison functions are never called; your application determines the formats and types of all tokens; and your application must interpret whose descriptor records created by the Apple Event Manager during the resolution of object specifier records. For more information, see "Handling Whose Tests," which begins on page 6-47.

---

Subtopics

Writing an Object-Counting Function

Writing an Object-Comparison Function

Writing Marking Callback Functions