Carbon


OSLAccessorProcPtr

Header: AEObjects.h Carbon status: Supported

Your object accessor function either finds elements or properties of an Apple event object.

typedef OSErr(* OSLAccessorProcPtr) (
    DescType desiredClass, 
    const AEDesc *container, 
    DescType containerClass, 
    DescType form, 
    const AEDesc *selectionData, 
    AEDesc *value, 
    SInt32 accessorRefcon
);

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

OSErr MyOSLAccessorCallback (
    DescType desiredClass, 
    const AEDesc *container, 
    DescType containerClass, 
    DescType form, 
    const AEDesc *selectionData, 
    AEDesc *value, 
    SInt32 accessorRefcon
);
Parameter descriptions
desiredClass

The object class of the desired Apple event object or objects. Constants for object class IDs are described in “Object Class ID Constants”.

container

A pointer to a descriptor that specifies the container of the desired Apple event object or objects.

containerClass

The object class of the container. Constants for object class IDs are described in “Object Class ID Constants”.

form

The key form specified by the object specifier record being resolved.Constants for key form are described in “Key Form and Descriptor Type Object Specifier Constants”.

selectionData

A pointer to a descriptor record containing the key data specified by the object specifier record being resolved.

value

A pointer to a descriptor record where your object accessor routine stores a descriptor record that identifies the found object.

accessorRefcon

A reference constant. The Apple Event Manager passes this value to your object accessor function each time it calls it. The reference constant may have a value of 0.

function result

A result code. Your object accessor function should return noErr if it successfully located the requested object and errAEEventNotHandled if it could not locate the object. When the Apple Event Manager receives the result code errAEEventNotHandled after calling an object accessor function, it attempts to use other methods of locating the requested objects, such as calling an equivalent system object accessor function.

DISCUSSION

To resolve an object specifier record, your application calls the AEResolve function. AEResolve in turn calls application-defined object accessor functions to locate specific Apple event objects and properties in the application’s data structures. Your application provides one or more object accessor functions that can locate all the element classes and properties it supports.

Each object accessor function provided by your application should either find elements or properties of an Apple event object. The AEResolve function uses the object class ID of the specified Apple event object and the descriptor type of the token that identifies the object’s container to determine which object accessor function to call. To install an object accessor function, use the AEInstallObjectAccessor function.

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

AEObjectAccessorUPP MyObjectAccessorUPP;

MyObjectAccessorUPP = NewAEObjectAccessorUPP (&MyObjectAccessorCallback);

You can then pass the UPP MyObjectAccessorUPP as a parameter to any function that installs or removes an object accessor, such as AEInstallObjectAccessor. If your application installs the same object accessor to handle more than one kind of object class or property of an Apple event, you can use the same UPP to install the accessor multiple times.

If you wish to call your object accessor callback function directly, you can use the InvokeOSLAccessorUPP function.

After you are finished with an object accessor callback function, and have removed it with the AERemoveObjectAccessor function, you can dispose of the UPP with the DisposeOSLAccessorUPP function. However, don’t dispose of the UPP if any remaining accessor function uses it or if you plan to install the accessor function again.

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)