Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Receiving Events

AcceptHighLevelEvent

After receiving a high-level event (other than an Apple event), use the AcceptHighLevelEvent function to get any additional information associated
with the event.

FUNCTION AcceptHighLevelEvent (VAR sender: TargetID;
                                 VAR msgRefcon: LongInt;
                                 msgBuff: Ptr;
                                 VAR msgLen: LongInt): OSErr;

sender

Identifies the sender of the event; this information is returned in a target ID record. The sender parameter contains the session reference number that identifies the connection with the other application and the port name and location name of the sender.

msgRefcon

Uniquely identifies the communication associated with this event. If you send a response to this event, you should specify the same value for the msgRefcon parameter so that the sender of the event can associate the reply with the original request.

msgBuff

Specifies where the AcceptHighLevelEvent function should return any additional data associated with the event. Your application is responsible for allocating the memory for the additional data pointed
to by the msgBuff parameter and for setting the msgLen parameter to the number of bytes that you have allocated for the data.

If the msgBuff parameter points to an area in memory that is
not large enough to hold all the data associated with the event, AcceptHighLevelEvent returns as much data as the specified
memory area can hold, returns the amount of data remaining in the msgLen parameter, and returns the result code bufferIsSmall.

msgLen

Contains the size of the data (in bytes) pointed to by the msgBuff parameter. If AcceptHighLevelEvent returns the result code bufferIsSmall, the msgLen parameter contains the number of bytes remaining. You can call AcceptHighLevelEvent again to receive the rest of the data.

DESCRIPTION

When your application receives a high-level event, you can use the AcceptHighLevelEvent function to get additional data associated with the
event. The AcceptHighLevelEvent function returns information that identifies
the sender of the event and the unique message reference constant of the event.

Your application should allocate memory for any additional data associated with the event, then supply a pointer to the data area and also provide the length in bytes of the data area.

SPECIAL CONSIDERATIONS

The AcceptHighLevelEvent function may move or purge memory. You should not call this function from within an interrupt, such as in a completion routine or VBL task.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the AcceptHighLevelEvent function are

Trap macro	Selector
_OSDispatch	$0033

RESULT CODES

noErr	0	No error
bufferIsSmall	-607	Buffer is too small
noOutstandingHLE	-608	No outstanding high-level event

SEE ALSO

For details on how to process an Apple event using the AEProcessAppleEvent function, see Inside Macintosh: Interapplication Communication.