Contents

OSLDisposeTokenProcPtr

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.

Declaration

typealias OSLDisposeTokenProcPtr = (UnsafeMutablePointer<AEDesc>?) -> OSErr

Parameters

  • unneededToken:

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

Return Value

A result code. See Result Codes. 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 MyDisposeTokenCallback 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.

See Also

Callbacks