Carbon


GetSpecificFilterProcPtr

Header: EPPC.h Carbon status: Unsupported

Defines a pointer to a filter callback function. The Event Manager 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.

typedef Boolean(* GetSpecificFilterProcPtr) (
    void *contextPtr, 
    HighLevelEventMsgPtr msgBuff, 
    const TargetID *sender
);

You would declare your function like this if you were to name it MyGetSpecificFilterCallback:

Boolean MyGetSpecificFilterCallback (
    void *contextPtr, 
    HighLevelEventMsgPtr msgBuff, 
    const TargetID *sender
);
contextPtr

The address of data that specifies the criteria your filter function should use to select a specific event. For example, you can specify in the contextPtr parameter the address of a reference constant to search for a particular event, the address of a target ID structure to search for a specific sender of an event, or the address of an event class to search for a specific class of event.

msgBuff

A pointer to a structure of type HighLevelEventMsg, which provides: the event structure for the high-level event and the reference constant of the event.

sender

The address of the target ID structure of the application that sent the event. The target ID structure is described in TargetID.

DISCUSSION

When you use GetSpecificHighLevelEvent to search the high-level event queue of your application for a specific event, you supply a pointer to a filter function. Your filter function can examine each event and determine whether that event is the desired event. If so, your filter function should return true.

Your filter function can compare the contents of the contextPtr parameter with the contents of the msgBuff and sender parameters. If your filter function finds a match, it can call AcceptHighLevelEvent, if necessary, and your filter function should return true. If your filter function does not find a match, it should return false.

The Event Manager defines the universal function pointer GetSpecificFilterUPP for an application-defined filter function.

typedef UniversalProcPtr GetSpecificFilterUPP;

The Event Manager also defines the macro NewGetSpecificFilterProc for obtaining a GetSpecificFilterUPP:

#define NewGetSpecificFilterProc(userRoutine) \(GetSpecificFilterUPP)

NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetSpecificFilterProcInfo, GetCurrentArchitecture())

You typically use the NewGetSpecificFilterProc macro like this:

GetSpecificFilterUPP myFilterFunctionProc;

myFilterFunctionProc = NewGetSpecificFilterProc(MyGetSpecificFilterCallback);

The Event Manager also defines the macro CallGetSpecificFilterProc for calling a GetSpecificFilterUPP. You normally don’t need to call this macro directly:

#define CallGetSpecificFilterProc(userRoutine, contextPtr, msgBuff, sender)\ CallUniversalProc((UniversalProcPtr)(userRoutine), uppGetSpecificFilterProcInfo, (contextPtr), (msgBuff), (sender))

AVAILABILITY

Not supported in Carbon.

CARBON NOTES

The High Level Event APIs (EPPC.h) are not supported in Carbon. Instead, use Apple events.


© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)