Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records

Installing Entries in the Object Accessor Dispatch Tables

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 describes. The AEResolve function resolves the object specifier record with the help of object accessor functions provided by your application. Your application installs entries for its object accessor functions in an object accessor dispatch table, which is used by the Apple Event Manager to map requests for Apple event objects or their properties to the appropriate object accessor functions.

After being called by AEResolve, an object accessor function should return a token that identifies (in whatever manner is appropriate for your application) the specified Apple event object or property. An object accessor function also returns a result code that indicates whether it found the Apple event object or property. The token, which is a descriptor record of data type AEDesc, can be of any descriptor type, including descriptor types you define yourself. 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.

Each object accessor function provided by your application should either find elements of a specified object class contained in an Apple event object identified by a token of a specified descriptor type, or find properties of an Apple event object identified by a token of a specified descriptor type. To determine which object accessor function to dispatch, the Apple Event Manager uses the object class ID specified in an object specifier record and the descriptor type of the token that identifies the requested object's container. For object accessor functions that find properties, you should specify the object class ID as the constant cProperty.

To install entries in your application's object accessor dispatch table, use the AEInstallObjectAccessor function. For each object class and property your application supports, you should install entries that specify

• the object class of the requested Apple event object or property
• the descriptor type of the token used to identify the container for the requested Apple event object or property
• the address of the object accessor function that finds objects or properties of the specified object class in containers described by tokens of the specified descriptor type
• a reference constant

You provide this information in the first four parameters to the AEInstallObjectAccessor function. The fifth parameter allows you to indicate whether the entry should be added to your application's object accessor dispatch table or the system object accessor dispatch table.

The system object accessor dispatch table is a table in the system heap that contains object accessor functions available to all processes running on the same computer. The object accessor functions in your application's object accessor dispatch table are available only to your application. If AEResolve cannot find an object accessor function for the Apple event object class in your application's object accessor dispatch table, it looks in the system object accessor dispatch table. If it doesn't find an object accessor function there either, it returns the result code errAEAccessorNotFound.

If AEResolve successfully calls the appropriate object accessor function in either the application object accessor dispatch table or the system object accessor dispatch table, the object accessor function returns a token and result code. The AEResolve function uses the token and result code to continue resolving the object specifier record. If, however, the token identifies the final Apple event object or property in the container hierarchy, AEResolve returns the token for the final resolution in the theToken parameter.

If the AEResolve function calls an object accessor function in the system object accessor dispatch table, your Apple event handler may not recognize the descriptor type of the token returned by the function. If this happens, your handler should attempt to coerce the token to an appropriate descriptor type. If coercion fails, return the result code errAEUnknownObjectType. When your handler returns this result code, the Apple Event Manager attempts to locate a system Apple event handler that can recognize the token.

It is up to you to decide how many object accessor functions you need to write and install for your application. You can install one object accessor function that locates Apple event objects of several different object classes, or you can write separate object accessor functions for certain object classes. Similarly, you may want to use only one descriptor type for all the tokens returned by your object accessor functions, or you may want to use several descriptor types. The sections that follow provide examples of alternative approaches.

For more information about object accessor functions, see "Writing Object Accessor Functions," which begins on page 6-34.

---

Subtopics

Installing Object Accessor Functions That Find Apple Event Objects

Installing Object Accessor Functions That Find Properties