Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Handling Apple Events

Disposing of Apple Event Data Structures

Whenever a client application uses Apple Event Manager functions to create a descriptor record, descriptor list, or Apple event record, the Apple Event Manager allocates memory for these data structures in the client's application heap. Likewise, when a server application extracts a descriptor record from an Apple event by using Apple Event Manager functions, the Apple Event Manager creates a copy of the descriptor record, including the data to which its handle refers, in the server's application heap.

Whenever you finish using a descriptor record or descriptor list that you have created or extracted from an Apple event, you should dispose of the descriptor record--and thereby deallocate the memory it uses--by calling the AEDisposeDesc function. If the descriptor record you pass to AEDisposeDesc (such as an Apple event record or an AE record) includes other nested descriptor records, one call to AEDisposeDesc will dispose of them all.

When a client application adds a descriptor record to an Apple event (for example, when it creates a descriptor record by calling AECreateDesc and then puts a copy of it into a parameter of an Apple event by calling AEPutParamDesc), it is still responsible for disposing of the original descriptor record. After a client application has finished using both the Apple event specified in the AESend function and the reply Apple event, it should dispose of their descriptor records by calling AEDisposeDesc. The client application should dispose of them even if AESend returns a nonzero result code.

The Apple event that a server application's handler receives is a copy of the original event created by the client application. When a server application's handler returns to AEProcessAppleEvent, the Apple Event Manager disposes of the server's copy (in the server's application heap) of both the Apple event and the reply event. The server application is responsible for disposing of any descriptor records created while extracting data from the Apple event or adding data to the reply event.

In general, outputs from Apple Event Manager functions are your application's responsibility. Once you finish using them, you should use AEDisposeDesc to dispose of any Apple event data structures created or returned by these functions:

AECoerceDesc	AEDuplicateDesc
AECoercePtr	AEGetAttributeDesc
AECreateAppleEvent	AEGetKeyDesc
AECreateDesc	AEGetNthDesc
AECreateList	AEGetParamDesc

If you attempt to dispose of descriptor records returned by successful calls to these functions without using AEDisposeDesc, your application may not be compatible with future versions of the Apple Event Manager. However, if any of these functions return a nonzero result code, they return a null descriptor record, which does not need to be disposed of.

Outputs from functions, such as AEGetKeyPtr, that use a buffer rather than a descriptor record to return data do not require the use of AEDisposeDesc. It is therefore preferable to use these functions for any data that is not identified by a handle.

Some of the functions described in the chapter "Resolving and Creating Object Specifier Records" in this book also create descriptor records. If you set the disposeInputs parameter to FALSE for any of the following functions, you should dispose of any Apple event data structures that they create or return:

CreateCompDescriptor	CreateObjSpecifier
CreateLogicalDescriptor	CreateRangeDescriptor

Your application is also responsible for disposing of some of the tokens it creates in the process of resolving an object specifier record. For information about token disposal, see "Defining Tokens" on page 6-39.