Carbon


OSLMarkProcPtr

Header: AEObjects.h Carbon status: Supported

Defines a pointer to an object marking callback function. Your object-marking function marks a specific Apple event object.

typedef OSErr(* OSLMarkProcPtr) (
    const AEDesc *dToken, 
    const AEDesc *markToken, 
    SInt32 index
);

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

OSErr MyOSLMarkCallback (
    const AEDesc *dToken, 
    const AEDesc *markToken, 
    SInt32 index
);
Parameter descriptions
dToken

A pointer to the token for the Apple event object to be marked. (Token is defined in AEDisposeToken.)

markToken

A pointer to the mark token used to mark the Apple event object.

index

The number of times your MyMark callback has been called for the current mark token (that is, the number of Apple event objects that have so far passed the test, including the element to be marked).

function result

A result code. Your object marking function should return noErr if it successfully marks the Apple event object and errAEEventNotHandled if it fails to mark the object. When the Apple Event Manager gets an error result of errAEEventNotHandled after calling an object marking function, it attempts to get mark the object by calling the equivalent system object marking function.

DISCUSSION

To mark an Apple event object using the current mark token, the Apple Event Manager calls the object-marking function provided by your application. In addition to marking the specified object, your MyMarkCallback function should record the mark count for each object that it marks. The mark count recorded for each marked object allows your application to determine which of a set of marked tokens pass a test, as described in the Discussion section for the OSLAdjustMarksProcPtr function.

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

OSLMarkUPP MyMarkUPP;

MyMarkUPP = NewOSLMarkUPP (&MyMarkCallback);

You can then pass the UPP MyMarkUPP as a parameter to the AESetObjectCallbacks function or the AEInstallSpecialHandler function.

If you wish to call your mark callback function directly, you can use the InvokeOSLMarkUPP function.

After you are finished with your mark callback function, you can dispose of the UPP with the DisposeOSLMarkUPP function. However, if you will use the same mark function in subsequent calls to the function AESetObjectCallbacks or the function AEInstallSpecialHandler, 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)