Carbon


OSLGetErrDescProcPtr

Header: AEObjects.h Carbon status: Supported

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 record if an error occurs during a call to the AEResolve function.

typedef OSErr(* OSLGetErrDescProcPtr) (
    AEDesc **appDescPtr
);

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

OSErr MyOSLGetErrDescCallback (
    AEDesc **appDescPtr
);
Parameter descriptions
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 record if an error occurs.

function result

A result code. Your error descriptor function should return noErr 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 record 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 record to the address supplied by your callback, overwriting whatever was there previously.

If an error occurs during the resolution of the object specifier record, the Apple Event Manager calls your get error descriptor callback function again and writes the descriptor record it is currently working with—often an object specifier record—to the address supplied by your callback. If AEResolve returns an error during the resolution of an object specifier record, this address contains the descriptor record responsible for the error.

You should always write a null descriptor record 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 record. 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 OSLGetErrDescUPP, using the function NewOSLGetErrDescUPP. You can do so with code like the following:

OSLGetErrorDescUPP MyGetErrorDescUPP;

MyGetErrorDescUPP = NewOSLGetErrorDescUPP (&MyGetErrorDescCallback);

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

If you wish to call your get error descriptor callback function directly, you can use the InvokeOSLGetErrDescUPP function.

After you are finished with your get error descriptor callback function, you can dispose of the UPP with the DisposeOSLGetErrDescUPP function. However, if you will use the same get error descriptor callback 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)