Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Sending Events

PostHighLevelEvent

You can use the PostHighLevelEvent function to send a high-level event to
another application.

FUNCTION PostHighLevelEvent (theEvent: EventRecord;
                              receiverID: Ptr; msgRefcon: LongInt;
                              msgBuff: Ptr; msgLen: LongInt;
                              postingOptions: LongInt): OSErr;

theEvent

The event to send. Your application should fill out the what, message, and where fields of the event record. Specify the kHighLevelEvent constant in the what field, the event class of the high-level event in the message field, and the event ID in the where field. You do not need to fill out the when or modifiers fields; the Event Manager automatically assigns the appropriate values to these fields when you send the message.

receiverID

The recipient of the high-level event. When sending an event to another application on the local computer, you can specify the recipient of the event by session reference number, process serial number, signature, or port name and location name. When sending an event to an application on a remote computer, you can specify the recipient only by the session reference number or by the port name and location name.

To specify a port name and location name, provide the address of a target ID record in the receiverID parameter. To specify a process serial number, provide its address in the receiverID parameter. To specify a session reference number, or signature, provide the data (cast to the Ptr data type) in the receiverID parameter.

msgRefcon

A unique number that identifies the communication associated with this event. Your application can set this field to any value it chooses. If you are replying to a high-level event, you should use the same value in the msgRefcon parameter as specified in the high-level event that originated the request.

msgBuff

A pointer to a data buffer that contains any additional data for the event.

msgLen

The size (in bytes) of the data buffer pointed to by the msgBuff parameter.

postingOptions

Options associated with the receiverID parameter and delivery options associated with the event. You can specify one or more delivery options to indicate whether you want the other application to receive the event at the next opportunity and to indicate whether you want acknowledgment that the event was received by the other application. You use the options associated with the receiverID parameter to indicate how you are specifying the recipient of the event--whether by port name and location name in a target ID record, by session reference number, by process serial number, or by signature.

You can use a combination of these constants in the postingOptions parameter:

            CONST                   
            nAttnMsg 
               = $00000001; {give this message priority}
            nReturnReceipt 
               = $00000200; {return receipt requested}
            receiverIDisTargetID 
               = $00005000; {ID is port name and location name}
            receiverIDisSessionID
               = $00006000; {ID is PPC session reference number}
            receiverIDisSignature
               = $00007000; {ID is creator signature}
            receiverIDisPSN   
               = $00008000; {ID is process serial number}

DESCRIPTION

The PostHighLevelEvent function posts the high-level event to the specified process.

If the application to which you are sending a high-level event terminates, you receive
the result code sessionClosedErr the next time your application calls PostHighLevelEvent to send another high-level event to the terminated application. If you do not care about any state information about that session, you can just resend your event. Otherwise, you must restart another session and resend your event.

If your application is running in the background and posts a high-level event that requires the network authentication dialog box to be displayed, PostHighLevelEvent returns the noUserInteractionAllowed result code, does not display the network authentication dialog box, and does not send the event. If your application receives the noUserInteractionAllowed result code, you can use the Notification Manager to inform the user that your application needs attention. When the user brings your application to the foreground, you can repost the event. If the reposting is successful, your application can continue to post high-level events without further user interaction. Note that PostHighLevelEvent can return noUserInteractionAllowed only on the first posting of a high-level event to a remote target.

SPECIAL CONSIDERATIONS

The PostHighLevelEvent 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 PostHighLevelEvent function are

Trap macro	Selector
_OSDispatch	$0034

SEE ALSO

For details on how to send Apple events to other applications using the AESend function, see Inside Macintosh: Interapplication Communication.

RESULT CODES

noErr	0	No error
connectionInvalid	-609	Connection is invalid
noUserInteractionAllowed	-610	Cannot interact directly with user
sessionClosedErr	-917	Session closed