Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records

Writing Object Accessor Functions

If the direct parameter for an Apple event consists of an object specifier record, your handler for the event should call the AEResolve function to resolve the object specifier record: that is, to find the Apple event objects or properties it describe. The AEResolve function resolves object specifier records with the help of object accessor functions provided by your application. For an overview of the way AEResolve works with your application's object accessor functions to locate Apple event objects, see "Resolving Object Specifier Records," which begins on page 6-4.

This section describes how to write object accessor functions. You need to read this section if your application supports the Core suite or any of the functional-area suites in the Apple Event Registry: Standard Suites.

Your application should provide object accessor functions that can find Apple event objects and their properties for all object classes supported by your application, including their corresponding properties and element classes. Because the Apple Event Manager dispatches object accessor functions according to the class ID of the requested Apple event object and the descriptor type of the token that identifies its container, you have a great deal of flexibility in deciding what object accessor functions you need to write for your application. The installation and dispatching of object accessor functions are described in "Installing Entries in the Object Accessor Dispatch Tables," which begins on page 6-27.

For example, if your application is a word processor, one object accessor function will probably work equally well for Apple event objects of object classes cParagraph, cItem, and cWord located in containers identified by tokens of descriptor type myTextToken. If you use a single descriptor type for tokens that identify any containers in which objects of these three object classes can be found, you can dispatch requests for all such elements to the same object accessor function. However, the same word processor might use one descriptor type for tokens identifying containers of class cCell and another descriptor type for tokens identifying containers of class cColumn--in which case it would need an object accessor function for each descriptor type.

For each object class that your application supports, your application should also provide one object accessor function that can find all the properties of that object class, or one object accessor function that can find all the properties of several object classes.

Here's the declaration for a sample object accessor function:

FUNCTION MyObjectAccessor (desiredClass: DescType; 
                           containerToken: AEDesc; 
                           containerClass: DescType;
                           keyForm: DescType; keyData: AEDesc;
                           VAR theToken: AEDesc; 
                           theRefCon: LongInt): OSErr;

The AEResolve function passes the following information to your object accessor function: the object class ID of the requested Apple event objects, the object class of their container, a token that identifies the specific container in which to look for them, the key form and key data that specify how to locate them, and the reference constant associated with the object accessor function. Your object accessor function uses this information to locate the requested objects.

Most applications that resolve object specifier records need to support only the key forms formPropertyID, formName, formUniqueID, formAbsolutePosition, formRelativePosition, and formRange explicitly. You do not need to support these key forms for all object classes; for example, words usually do not have names, so most applications should return errAEEventNotHandled if they receive a request for a word by name.

If your application provides an object-counting function and an object-comparison function in addition to the appropriate object accessor functions, the Apple Event Manager can handle formTest automatically.

The Apple Event Manager uses the key form formWhose internally to optimize resolution of object specifier records that specify formTest. Only applications that translate tests into their own query languages need to support formWhose explicitly. "Handling Whose Tests," which begins on page 6-47, describes formWhose in detail.

If your object accessor function successfully locates the requested Apple event objects, your application should return the noErr result code and a token that identifies them. The token can be of any descriptor type, as long as it is a descriptor record. For example, to identify a file, your application might use a descriptor record of descriptor type typeAlias or typeFSS. To identify an open document, your application might define its own descriptor type, such as typeMyDocToken, for a descriptor record whose data handle refers to a pointer to a document record. For more information about tokens, see "Defining Tokens" on page 6-45.

IMPORTANT

Object accessor functions must not have side effects that change the number or order of elements in a container while an object specifier record is being resolved. If the number of elements in a container is changed during the resolution of an object specifier record, the Apple Event Manager may not be able to locate all the elements.

---

Subtopics

Writing Object Accessor Functions That Find Apple Event Objects

Writing Object Accessor Functions That Find Properties

Defining Tokens

Handling Whose Tests