Callback objects

Callback objects are created at runtime, using several functions from the Dexterity object function library. To create a callback, you must create the callback object, add methods and properties, and make the object available to other applications.

Creating a callback object

Use the DexObject_Create() function to create the callback object. This function returns a reference to the callback that is created. An application can have multiple callback objects, so you should store this callback reference in a location where it can be stored safely and easily retrieved. You will need to use the reference when you add properties and methods to the callback.

Adding properties

To add properties to the callback object, use the DexObject_AddProperty() function. Properties store specific data items in the callback object. Their values can be set or retrieved by both the Dexterity-based application and external applications accessing the callback object through COM.

Adding methods

To add methods to the callback object, use the DexObject_AddMethod() function. Methods on the callback object can be called from the Dexterity-based application, but are primarily called by other applications accessing the callback object through COM. Methods are the primary way other applications can initiate actions in your application.

When a method in the callback object is called, the corresponding user-defined function in the Dexterity-based application is run. The parameters for the method on the callback are determined by the parameters on the user-defined function that runs in response to the callback method. Use the following guidelines when specifying the parameter types for the user-defined function:

Use “in” parameters for values that will be passed from the external application into the callback method.
Use “inout” parameters for values that can pass values from the external application into the callback method, and also return a value from the method.

Making the callback object accessible

To make the callback object accessible to other applications, you must add it to the running object table. The running object table is managed by the operating system. It maintains a list of all COM objects that can currently be accessed. Use the COM_RegisterRunningObject() function to add a callback object to the running object table. When you use this function, you specify the name that is given to the callback object. Use a name that describes the application that created the callback, as well as the purpose of the callback. Other applications must use this name to retrieve a reference to the callback object.

Note that other applications have no way of determining the name of any callback object, or the properties and methods that are part of the object. If you want other applications to be able to access the callback objects you create, you must provide documentation for the callback.

Be sure to include the following:

The complete name of the callback object. The name is case-sensitive.
The names of the properties in the callback, along with their associated data types.
The names of the methods in the callback, along with the return value (if any), the parameters for the methods, and their associated data types.

Responding to method calls

The user-defined function that runs in response to a COM method call is the code that actually performs the work of the method. Often, it’s useful to be able to access the callback object from within the user-defined function that is run for the method. To access the properties or methods for the current callback object, use the this statement.

You can also throw exceptions in the user-defined function associated with the method. Any exceptions you throw will be propagated back through COM to the application that called the method in the callback object. For example the following sanScript code in the user-defined function associated with a method will produce a COM exception. The value 1001 is passed as the exception class, and the value 1 is passed as the exception subclass.

throw 1001, 1, "User not logged in";

We recommend that you use values greater than 1000, but less than 32,767 for the exception class.

This example produces the following COM exception dialog in a Visual Basic application.

Notice that the exception class is passed in as the error number, while the exception subclass is enclosed in brackets and prepended to the exception message.