Inside Macintosh: Interapplication Communication /

Chapter 5 - Creating and Sending Apple Events

Creating an Apple Event

You create an Apple event by using the AECreateAppleEvent function. You supply parameters that specify the event class and event ID, the target address, the return ID, and the transaction ID, and a buffer for the returned Apple event. The AECreateAppleEvent function creates and returns, in the buffer you specify, an Apple event with the attributes set as your application requested. You should not directly manipulate the contents of the Apple event; rather, use Apple Event Manager functions to add additional attributes or parameters to it.

The example that follows creates an imaginary Multiply event using the AECreateAppleEvent function.

myErr := AECreateAppleEvent(kArithmeticClass, kMultEventID,
                            targetAddress, kAutoGenerateReturnID,
                            kAnyTransactionID, theAppleEvent);  

The event class, specified by the kArithmeticClass constant, identifies this event as belonging to a class of Apple events for arithmetic operations. The event ID specifies the particular Apple event within the class--in this case, an Apple event that performs multiplication.

You specify the target of the Apple event in the third parameter to AECreateAppleEvent. The target address can identify an application on the local computer or another computer on the network. You can specify the address using a target ID record or session reference number. For processes on the local computer, you can also use a process serial number or application signature to specify the address. See "Specifying a Target Address" on page 5-10 for more information.

In the fourth parameter, you specify the return ID of the Apple event, which associates this Apple event with the server's reply. The AECreateAppleEvent function assigns the specified return ID value to the keyReturnIDAttr attribute of the Apple event. If a server returns a standard reply Apple event (that is, an event of event class 'aevt' and event ID 'ansr') in response to this event, the Apple Event Manager assigns the reply event the same return ID. When you receive a reply Apple event, you can check the keyReturnIDAttr attribute to determine which outstanding Apple event the reply is responding to. You can use the kAutoGenerateReturnID constant to request that the Apple Event Manager generate a return ID that is unique to this session for the Apple event. Otherwise, you are responsible for making it unique.

The fifth parameter specifies the transaction ID attribute of the Apple event. A transaction is a sequence of Apple events that are sent back and forth between the client and server applications, beginning with the client's initial request for a service. All Apple events that are part of one transaction must have the same transaction ID.

You can use a transaction ID to indicate that an Apple event is one of a sequence of Apple events related to a single transaction. The kAnyTransactionID constant indicates that the Apple event is not part of a transaction.

The AECreateAppleEvent function creates an Apple event with only the specified attributes and no parameters. To add parameters or additional attributes, you can use other Apple Event Manager functions.

---

Subtopics

Adding Parameters to an Apple Event

Specifying Optional Parameters for an Apple Event

Specifying a Target Address