Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 5 - Creating and Sending Apple Events / Creating an Apple Event

Specifying a Target Address

When you create an Apple event, you must specify the address of the target. The target address identifies the particular application or process to which you want to send the Apple event. You can send Apple events to applications on the local computer or on remote computers on the network.

These are the descriptor types that identify the four methods of addressing an Apple event:

typeApplSignature	The application signature of the target
typeSessionID	The session reference number of the target
typeTargetID	The target ID record of the target
typeProcessSerialNumber	The process serial number of the target

To address an Apple event to a target on a remote computer on the network, you must use either the typeSessionID or typeTargetID descriptor type.

If your application sends an Apple event to itself, it should address the Apple event using a process serial number of kCurrentProcess. This is the fastest way for your application to send an Apple event to itself. For more information, see "Addressing an Apple Event for Direct Dispatching" on page 5-13.

You can use any of the four address types when sending an Apple event to another application on the local computer. The chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials describes all four types of addresses. Your application can also use another address type if it provides a coercion handler that coerces the address type into one of the four address types that the Apple Event Manager recognizes. See "Writing and Installing Coercion Handlers," which begins on page 4-41, for more information.

To allow the user to choose the target of an Apple event, use the PPCBrowser function. This function presents a standard user interface for choosing a target application, much as the Standard File Package provides a standard user interface for opening and saving files. The PPCBrowser function returns, in a target ID record, information about the application the user chose. Listing 5-3 on page 5-12 shows how to use the PPCBrowser function to let the user choose a target.

Creating an Address Descriptor Record

You specify the address using an address descriptor record (a descriptor record of data type AEAddressDesc). You must create a descriptor record of this type and then add it to the Apple event using the AECreateAppleEvent function.

You can use the AECreateDesc function to create address descriptor records for any of the four types of target addresses. Listing 5-2 shows four possible ways to create an address, each using a different address type.

Listing 5-2 Creating a target address

PROCEDURE MySetTargetAddresses(VAR targetAddress1, 
                               targetAddress2, targetAddress3, 
                               targetAddress4: AEAddressDesc; 
                               toTargetID: TargetID; 
                               thePSN: ProcessSerialNumber; 
                               theSignature: OSType; 
                               theSessionRef: PPCSessRefNum);
VAR
   myErr:   OSErr;
BEGIN
   myErr := AECreateDesc(typeTargetID, @toTargetID,
                         SizeOf(toTargetID), targetAddress1);
   myErr := AECreateDesc(typeProcessSerialNumber, @thePSN, 
                         SizeOf(thePSN), targetAddress2);
   myErr := AECreateDesc(typeApplSignature, @theSignature, 
                         SizeOf(theSignature), targetAddress3);
   myErr := AECreateDesc(typeSessionID, @theSessionRef, 
                         SizeOf(theSessionRef), targetAddress4);
   {add your own error checking}
END;

To create an address descriptor record, specify the following as parameters to AECreateDesc: the descriptor type for the address, a pointer to the buffer containing the address, and the size of the buffer. The AECreateDesc function returns an address descriptor record with the specified characteristics.

After creating an address, you can specify it as a parameter to the AECreateAppleEvent function. See "Creating an Apple Event," which begins on page 5-3, for an example using the AECreateAppleEvent function.

When you specify an address to the AECreateAppleEvent function, the Apple Event Manager stores the address in the keyAddressAttr attribute of the Apple event.

If you use the PPCBrowser function to allow the user to choose an Apple event's target, your application must create a target ID record based on the user's choice. Listing 5-3 shows how to create a target ID record using the information returned from the PPCBrowser function and create an address descriptor record using the AECreateDesc function.

Listing 5-3 Specifying a target address in an Apple event by using the PPCBrowser function

FUNCTION MyGetTargetAddress (myPrompt: Str255; myAppStr: Str255;
                              VAR myPortInfo: PortInfoRec; 
                              VAR targetAddress: AEAddressDesc; 
                              VAR toTargetID: targetID): OSErr;
VAR
   myErr:   OSErr;
BEGIN             
   {use PPCBrowser to let user choose the target}
   myErr := PPCBrowser(myPrompt, myAppStr, FALSE, 
                        toTargetID.location, 
                        myPortInfo, NIL, '');
   MyGetTargetAddress := myErr;
   IF myErr <> noErr THEN Exit(MyGetTargetAddress);

   toTargetID.name := myPortInfo.name;

   {create the descriptor record for the target address}
   MyGetTargetAddress := AECreateDesc(typeTargetID, @toTargetID, 
                                       SizeOf(toTargetID), 
                                       targetAddress);
END;

See the chapter "Program-to-Program Communications Toolbox" in this book for more information on using the PPCBrowser function.

Addressing an Apple Event for Direct Dispatching

As described in the chapter "Recording Apple Events" in this book, a recordable application must send itself Apple events in response to user actions. Your application can send itself Apple events by using an address descriptor record of descriptor type typeProcessSerialNumber with the lowLongOfPSN field set to kCurrentProcess and the highLongOfPSN set to 0. The Apple Event Manager processes such Apple events immediately, executing the appropriate Apple event handler directly without going through the normal event-processing sequence. For this reason, your application will not appear to run more slowly when it sends Apple events to itself.

Apple events your application sends to itself this way do not appear in your application's high-level event queue. This not only speeds up delivery of the event but also avoids situations in which an Apple event sent in response to a user action arrives in the event queue after some other event that really occurred later than the user action. For example, suppose a user chooses Cut from the Edit menu and then clicks in another window. If the Cut event arrives in the queue after the window activate event, a selection in the wrong window might be cut.

Your application can send events to itself using other forms of addressing, such as the true process serial number returned by GetCurrentProcess. Because direct dispatching avoids event sequence problems, applications should generally send events to themselves by using an address descriptor record of descriptor type typeProcessSerialNumber with the kCurrentProcess constant rather than using a true process serial number or an application signature.

IMPORTANT

When Apple event recording has been turned on, the Apple Event Manager records every event that your application sends to itself unless you specify the kAEDontRecord flag in the sendMode parameter of the AESend function.