Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records

Creating Object Specifier Records

If your application creates and sends Apple events that require the target application to locate Apple event objects, your application must create object specifier records for those events. This section describes how to use the four keyword-specified descriptor records described in "Descriptor Records Used in Object Specifier Records," which begins on page 6-7, to specify the object class ID, container, key form, and key data for an object specifier record.

Because the internal structure of an object specifier record is nearly identical to the internal structure of an AE record, it is possible to use AECreateList, AEPutPtr, and AEPutKeyDesc to add the four keyword-specified descriptor records to an AE record, then use AECoerceDesc to coerce the AE record to a descriptor record of type typeObjectSpecifier. However, it is usually preferable to use the CreateObjSpecifier function to accomplish the same goal. The CreateObjSpecifier function adds the keyword-specified descriptor records directly to an object specifier record, thus eliminating several steps that are required if you create an AE record first. The instructions that follow make use of CreateObjSpecifier.

To specify the class ID for an object specifier record, your application can specify the appropriate class ID value as the desiredClass parameter for the CreateObjSpecifier function, which uses it to create a keyword-specified descriptor record with the keyword keyAEDesiredClass as part of an object specifier record.

To specify the container for an object specifier record, your application must create a keyword-specified descriptor record with the keyword keyAEContainer that fully describes the container of the Apple event object. Because this container is usually another Apple event object, the container is usually specified by another object specifier record.

To specify the complete container hierarchy of an Apple event object, your application must create a series of nested object specifier records, starting with the object specifier record for the Apple event object whose container is outermost. With the exception of this first object specifier record, each object specifier record specifies another object specifier record in the chain as a container.

For example, Figure 6-2 on page 6-9 shows a series of nested object specifier records that specify the first row of a table named "Summary of Sales" in a document named "Sales Report." The logical organization of the same object specifier records is summarized in Table 6-7.

Table 6-7 Nested object specifier records that describe a container hierarchy

Keyword	Descriptor type	Data
keyAEDesiredClass	typeType	cRow
keyAEContainer	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cTable
keyAEContainer	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cDocument
keyAEContainer	typeNull	Data handle is NIL
keyAEKeyForm	typeEnumerated	formName
keyAEKeyData	typeChar	"Sales Report"
keyAEKeyForm	typeEnumerated	formName
keyAEKeyData	typeChar	"Summary of Sales"
keyAEKeyForm	typeEnumerated	formAbsolutePosition
keyAEKeyData	typeLongInteger	1

Note

The format used in Table 6-7 and similar tables throughout this chapter does not show the structure of nested object specifier records as they exist within an Apple event. Instead, this format shows what you would obtain after calling AEGetKeyDesc repeatedly to extract the object specifier records from an Apple event record.

When you call AEGetKeyDesc to extract a null descriptor record, AEGetKeyDesc returns a descriptor record of type AEDesc with a descriptor type of typeNull and a data handle whose value is 0.

To specify the default container for an object specifier record (such as the container for the document in Table 6-7), you can use AECreateDesc to create a null descriptor record, which you can then pass in the theContainer parameter of the CreateObjSpecifier function. The CreateObjSpecifier function uses the null descriptor record to create a keyword-specified descriptor record with the keyword keyAEContainer as part of an object specifier record.

The object specifier record that specifies the default container is always the first record you create in a series of nested object specifier records that specifies the complete container hierarchy for an Apple event object. Each one in the series uses the previously created object specifier record to specify its container. As with the null descriptor record, you can pass an object specifier record as the second parameter to the CreateObjSpecifier function, which uses it to create a keyword-specified descriptor record with the keyword keyAEContainer.

To specify the key form for an object specifier record, your application can specify a key form constant as the third parameter to the CreateObjSpecifier function, which uses it to create a keyword-specified descriptor record with the keyword keyAEKeyForm as part of an object specifier record. The standard key forms for object specifier records are summarized in Table 6-1 on page 6-13.

For example, the key form for the object specifier records in Table 6-7 that specify the document and the table is formName. In other words, the key data identifies the document and the table by their names. Similarly, the key form for the object specifier record in Table 6-7 that specifies the first row in the table is formAbsolutePosition. In other words, the key data identifies the position of the row compared to other rows in the same container.

To specify the key data for an object specifier record, your application must create a keyword-specified descriptor record with the keyword keyAEKeyData whose data handle refers to the appropriate data for the specified key form. You can use AECreateDesc, CreateCompDescriptor, CreateLogicalDescriptor, and related functions to create the descriptor record, which you can then pass in the fourth parameter of the CreateObjSpecifier function. The CreateObjSpecifier function uses this descriptor record to create a keyword-specified descriptor record with the keyword keyAEKeyData as part of an object specifier record.

---

Subtopics

Creating a Simple Object Specifier Record

Creating a Complex Object Specifier Record