Carbon


AEFilterProcPtr

Header: AEInteraction.h Carbon status: Supported

Defines a pointer to a function the Apple Event Manager calls while your application waits for a reply to an Apple event. Your filter function determines which high-level events your application is willing to handle.

typedef Boolean(* AEFilterProcPtr) (
    EventRecord *theEvent, 
    SInt32 returnID, 
    SInt32 transactionID, 
    const AEAddressDesc *sender
);

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

Boolean MyAEFilterCallback (
    EventRecord *theEvent, 
    SInt32 returnID, 
    SInt32 transactionID, 
    const AEAddressDesc *sender
);
Parameter descriptions
theEvent

A pointer to the event record for a high-level event. The next three parameters contain valid information only if the event is an Apple event.

returnID

Return ID for the Apple event.

transactionID

Transaction ID for the Apple event.

sender

A pointer to the address of the process that sent the Apple event.

function result

Your filter routine returns TRUE to accept the Apple event or FALSE to filter it out.

DISCUSSION

If your application provides a universal procedure pointer to a reply filter function as a parameter to the AESend function, the reply filter function can indicate any high-level events that it is willing to handle while your application is waiting for a reply.

If your filter function returns true, the Apple Event Manager will dispatch the event through the standard dispatch mechanism (equivalent to calling AEProcessAppleEvent).

To provide a pointer to your reply filter callback function, you create a universal procedure pointer (UPP) of type AEFilterUPP, using the function NewAEFilterUPP. You can do so with code like the following:

AEFilterUPP MyReplyFilterUPP;

MyReplyFilterUPP = NewAEFilterUPP (&MyReplyFilterCallback);

You can then pass the UPP MyReplyFilterUPP as a parameter to the AESend function.

If you wish to call your filter callback function directly, you can use the InvokeAEFilterUPP function.

After you are finished with your filter callback function, you can dispose of the UPP with the DisposeAEFilterUPP function. However, if you will use the same filter function in subsequent calls to AESend, you can reuse the same UPP, rather than dispose of it and later create a new UPP.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)