Defines a pointer to an error descriptor callback function. Your error descriptor callback function supplies a pointer to an address where the Apple Event Manager can store the current descriptor if an error occurs during a call to the AEResolve
function.
SDKs
- macOS 10.0+
- Mac Catalyst 13.0+
Framework
- Core Services
Declaration
Parameters
appDescPtr
A pointer to a pointer to a descriptor address. Your error descriptor callback function supplies a pointer to an address of a descriptor where the Apple Event Manager can store the current descriptor if an error occurs. See
AEDesc
.
Return Value
A result code. See Result Codes. Your error descriptor function should return no
if it completes successfully and a nonzero error value if it is unsuccessful. If it returns a nonzero value, the Apple Event Manager continues to resolve the object specifier as if it had never called the error callback function.
Discussion
Your get error descriptor callback function simply supplies a pointer to an address. Shortly after your application calls the AEResolve
function, the Apple Event Manager calls your get error descriptor callback function and writes a null descriptor to the address supplied by your callback, overwriting whatever was there previously.
If an error occurs during the resolution of the object specifier, the Apple Event Manager calls your get error descriptor callback function again and writes the descriptor it is currently working with—often an object specifier—to the address supplied by your callback. If AEResolve
returns an error during the resolution of an object specifier, this address contains the descriptor responsible for the error.
You should always write a null descriptor at the address provided by your get error descriptor callback function before calling AEResolve
. When recovering from an error, the Apple Event Manager, never writes to the address you provide unless it already contains a null descriptor. You may wish to maintain a single global variable of type AEDesc
and have your get error descriptor callback function always provide the address of that variable.
After AEResolve
returns, if your error descriptor is not the null descriptor, you are responsible for disposing of it.
To provide a pointer to your get error descriptor callback function, you create a universal procedure pointer (UPP) of type OSLGet
, using the function New
. You can do so with code like the following:
OSLGetErrorDescUPP MyGetErrorDescUPP;
MyGetErrorDescUPP = NewOSLGetErrorDescUPP (&MyGetErrorDescCallback)
You can then pass the UPP My
as a parameter to the AESet
function or the AEInstall
function.
If you wish to call your get error descriptor callback function directly, you can use the Invoke
function.
After you are finished with your get error descriptor callback function, you can dispose of the UPP with the Dispose
function. However, if you will use the same get error descriptor callback function in subsequent calls to the function AESet
or the function AEInstall
, you can reuse the same UPP, rather than dispose of it and later create a new UPP.