Carbon


OSLDisposeTokenProcPtr

Header: AEObjects.h Carbon status: Supported

Defines a pointer to a dispose token callback function. Your dispose token function, required only if you use a complex token format, disposes of the specified token.

typedef OSErr(* OSLDisposeTokenProcPtr) (
    AEDesc *unneededToken
);

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

OSErr MyOSLDisposeTokenCallback (
    AEDesc *unneededToken
);
Parameter descriptions
unneededToken

A pointer to the token to dispose of. (Token is defined in AEDisposeToken.) On successful return, your function must set this to the null descriptor.

function result

A result code. Your token disposal function should return noErr if it successfully disposed of the token and errAEEventNotHandled if it can’t dispose of the token. When the Apple Event Manager receives the result code errAEEventNotHandled after calling a token disposal function, it attempts to use other methods of disposing of the specified token, such as calling an equivalent system token disposal function if one is available or, if that fails, by calling AEDisposeDesc.

DISCUSSION

The Apple Event Manager calls your token disposal function whenever it needs to dispose of a token. It also calls your disposal function when your application calls the AEDisposeToken function. If your application does not provide a token disposal function, the Apple Event Manager calls AEDisposeDesc instead.

Your token disposal function must be able to dispose of all of the token types used by your application.

If your application supports marking, a call to MyDisposeToken to dispose of a mark token lets your application know that it can unmark the objects marked with that mark token, as described in the Discussion section for OSLGetMarkTokenProcPtr.

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

OSLDisposeTokenUPP MyDisposeTokenUPP;

MyDisposeTokenUPP = NewOSLDisposeTokenUPP (&MyDisposeTokenCallback);

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

If you wish to call your token disposal callback function directly, you can use the InvokeOSLDisposeTokenUPP function.

After you are finished with your token disposal callback function, you can dispose of the UPP with the DisposeOSLDisposeTokenUPP function. However, if you will use the same token disposal 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.

VERSION NOTES

Revisit, based on system object accessor dispatch table write-up.

Use of the system object accessor dispatch table is not recommended for Carbon applications—see “Installing Object Accessors” (to be supplied later) for more information.


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