Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 3 - Introduction to Apple Events / Working With Object Specifier Records

Finding Apple Event Objects

Most of the Apple events in the Core suite and the functional-area suites defined in the Apple Event Registry: Standard Suites can include parameters that consist of object specifier records. Your application's handlers for these events can use the AEResolve function to resolve object specifier records: that is, to locate the Apple event objects they describe.

The AEResolve function parses an object specifier record and performs related tasks that are the same for all object specifier records. When necessary, the AEResolve function calls application-defined functions to perform tasks that are unique to the application, such as locating a specific Apple event object in the application's data structures.

Your application can provide two kinds of application-defined functions for use by AEResolve. Object accessor functions locate Apple event objects. Every application that supports simple object specifier records must provide one or more object accessor functions. Object callback functions perform other tasks that only an application can perform, such as counting, comparing, or marking Apple event objects.

Each time AEResolve calls one of your application's object accessor functions successfully, the object accessor function returns a special descriptor record, called a token, that identifies either an element in a specified container or a property of a specified Apple event object. The token can be of any descriptor type, including descriptor types you define yourself.

You install object accessor functions by using the AEInstallObjectAccessor function. Much like the AEInstallEventHandler function, AEInstallObjectAccessor uses an object accessor dispatch table to map requests for Apple event objects to the appropriate object accessor functions in your application. These requests refer to objects of a specified object class in containers identified by a token of a specified descriptor type.

Responding to an Apple event that includes an object specifier record typically involves these steps:

1. After determining that the event is an Apple event, your application calls AEProcessAppleEvent.
2. The AEProcessAppleEvent function uses the Apple event dispatch table to dispatch the event to the your application's handler for that event.
3. The Apple event handler extracts the Apple event parameters, and passes the object specifier records they contain to AEResolve.
4. The AEResolve function uses the object accessor dispatch table to call one or more object accessor functions, one at a time, that can identify the nested Apple event objects described by each object specifier record. Each object accessor function returns a token for the object it finds, which in turn helps to determine which object accessor function the AEResolve function will use to locate the next Apple event object.
5. The AEResolve function returns the final token for the requested object to the application's handler.

The resolution of an object specifier record always begins with the outermost container it specifies. For example, to locate a table named "Summary of Sales" in the document named "Sales Report," the AEResolve function first calls an object accessor function that can locate the document, then uses the token returned by that function to identify an object accessor function that can locate the table. It then returns the token for the table to the Apple event handler that called AEResolve.

The chapter "Resolving and Creating Object Specifier Records" in this book describes in detail how to resolve object specifier records and how to write and install object accessor and object callback functions.