Previous Book Contents Book Index Next

Inside Macintosh: Interapplication Communication /
Chapter 4 - Responding to Apple Events / Reference to Responding to Apple Events
Routines for Responding to Apple Events / Getting Data or Descriptor Records Out of Apple Event Parameters and Attributes


AEGetAttributePtr

You can use the AEGetAttributePtr function to get a pointer to a buffer that contains the data from a specified Apple event attribute.

FUNCTION AEGetAttributePtr (theAppleEvent: AppleEvent; 
                            theAEKeyword: AEKeyword; 
                            desiredType: DescType; 
                            VAR typeCode: DescType; dataPtr: Ptr; 
                            maximumSize: Size; 
                            VAR actualSize: Size): OSErr;
theAppleEvent
The Apple event containing the desired attribute.
theAEKeyword
The keyword that specifies the desired attribute.
TYPE AEKeyword = PACKED ARRAY[1..4] OF Char;
The keyword can be any of the constants listed in the description that follows.
desiredType
The desired descriptor type for the data to be returned; if the requested Apple event attribute is not of this type, the Apple Event Manager attempts to coerce it to this type. If the value of desiredType is typeWildCard, no coercion is performed, and the descriptor type of the returned data is the same as the descriptor type of the Apple event attribute.
typeCode
The descriptor type of the returned data.
dataPtr
A pointer to the buffer in which the returned data is stored.
maximumSize

The maximum length, in bytes, of the data to be returned. You must allocate at least this amount of storage for the buffer specified by the dataPtr parameter.
actualSize
The length, in bytes, of the data for the specified Apple event attribute. If this value is larger than the value of the maximumSize parameter, not all of the data for the attribute was returned.
DESCRIPTION
The AEGetAttributePtr function uses a buffer to return the data from an Apple event attribute with the specified keyword, which it attempts to coerce to the descriptor type specified by the desiredType parameter. You can specify the parameter theAEKeyWord using any of these constants:

CONST
   keyAddressAttr          = 'addr'; {address of target or }
                                     { client application}
   keyEventClassAttr       = 'evcl'; {event class}
   keyEventIDAttr          = 'evid'; {event ID}
   keyEventSourceAttr      = 'esrc'; {nature of source }
                                     { application}
   keyInteractLevelAttr    = 'inte'; {settings to allow the }
                                     { Apple Event Manager to }
                                     { bring server application }
                                     { to the foreground}
   keyMissedKeywordAttr    = 'miss'; {first required parameter }
                                     { remaining in Apple event}
   keyOptionalKeywordAttr  = 'optk'; {list of optional }
                                     { parameters for Apple }
                                     { event}
   keyOriginalAddressAttr  = 'from'; {address of original source }
                                     { of Apple event; available }
                                     { beginning with version }
                                     { 1.01 of Apple Event }
                                     { Manager} 
   keyReturnIDAttr         = 'rtid'; {return ID for reply Apple }
                                     { event}
   keyTimeoutAttr          = 'timo'; {length of time in ticks }
                                     { that client will wait }
                                     { for reply or result from } 
                                     { the server}
   keyTransactionIDAttr    = 'tran'; {transaction ID identifying }
                                     { a series of Apple events}
RESULT CODES
noErr0No error
memFullErr-108Not enough room in heap zone
errAECoercionFail -1700Data could not be coerced to the requested descriptor type
errAEDescNotFound -1701Descriptor record was not found
errAENotAEDesc-1704Not a valid descriptor record
errAEReplyNotArrived-1718Reply has not yet arrived
SEE ALSO
For an example of the use of the AEGetAttributePtr function, see "Getting Data Out of an Attribute" and "Writing Apple Event Handlers," which begin on page 4-28 and page 4-33, respectively.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996