GetSpecificHighLevelEvent

Select and ( optionally) retrieve a specific

high level event from the queue

#include <EPPC.h> Event Manager

GetSpecificFilterProcPtr aFilter ; your filter function

void *yourDataPtr ; event selection criteria

OSErr *err ; error code returned by aFilter

aFilter is the name of your filter function. GetSpecificHighLevelEvent

calls your filter function once for each event in the high-level event

queue until your filter function returns TRUE or the end of the queue

is reached.

yourDataPtr specifies the criteria your filter function should use to select a

specific event. For example, you can specify the yourDataPtr

parameter as a msgRefcon value to search for a particular event or as

a pointer to a target ID record to search for a specific sender of an

event. Or you can search for a specific class of event.

err is the address of an error code returned by your aFilter function.

Returns: an operating system Error Code. It will be one of:

noErr (0) No error

noOutstandingHLE (-608) No outstanding high-level event

Here's how you declare your filter function aFilter:

pascal Boolean (void * yourDataPtr,

HighLevelEventMsgPtrmsgBuff,

const TargetID *sender);

In which:

yourDataPtr is a parameter which indicates the criteria your filter function

should use to search for a specific event.

msgBuff is a parameter which contains a pointer to a record of type

HighLevelEventMsg, which provides information about the event: the

eventRecord for the high-level event, the posting options of the

event, and so forth.

sender is a parameter which contains a pointer to the targetID of the

application that sent the event.

Your filter function can compare the contents of the yourDataPtr parameter

with the contents of the msgBuff or senderID parameters. If your filter

function finds a match, it should return TRUE. If your filter function does not

find a match, it should return FALSE. Your filter procedure can call

Referenced by (6):