Your shared-library C/C++ code defines its interface to JavaScript in two sets of functions, collected in
SoServerInterface and SoObjectInterface function-pointer structures.
Return values from most functions are integer constants. The error code kESErrOK == 0
indicates success.
SoServerInterface
SoServerInterface
is a structure of function pointers which enable the shared-library code to call
JavaScript objects. It is passed to the global ESClientInterface() function for initialization when the library is
loaded, and again for cleanup when the library is unloaded. Between these calls, your shared-library code
must store the structure and use it to access the communication functions.
You can store information for every object and class in your C code. The recommended method is to create
a data structure during the initialize() and free it during finalize(). You can then access that data with
setClientData() and getClientData().
The SoServerInterface structure contains these function pointers:
SoServerInterface {
SoServerDumpServer_f
SoServerDumpObject_f
dumpServer; //debugging, show server in console
dumpObject; //debugging, show object in console
SoServerAddClass_f
addClass; //define a JS class
SoServerAddMethod_f
SoServerAddMethods_f
SoServerAddProperty_f
SoServerAddProperties_f
addMethod; // define a method
addMethods; // define a set of methods
addProperty; // define a property
addProperties; // define a set of properties
SoServerGetClass_f
SoServerGetServer_f
getClass; // get class for an instance
getServer; // get server for an instance
SoServerSetClientData_f
SoServerGetClientData_f
setClientData; //set data in instance
getClientData; //get data from instance
SoServerEval_f
eval; // call JavaScript interpreter
SoServerTaggedDataInit_f taggedDataInit; // init tagged data
SoServerTaggedDataFree_f taggedDataFree; // free tagged data
}
These functions allow your C/C++ shared library code to create, modify, and access JavaScript classes and
objects. The functions must conform to the following type definitions.
dumpServer()
ESerror_t dumpServer (SoHServer hServer);
Prints the contents of this server to the JavaScript Console in the ExtendScript Toolkit, for
debugging.
Returns an error code, kESErrOK
on success.
dumpObject()
ESerror_t dumpObject (SoHObject hObject);
Prints the contents of this object to the JavaScript Console in the ExtendScript Toolkit, for
debugging.
Returns an error code, kESErrOK
on success.
addClass()
ESerror_t addClass (SoHServer hServer, char* name, SoObjectInterface_p pObjectInterface);
hServer
|
The Support structures reference for this shared library, as passed to your global
ESClientInterface() function on initialization. |
name
|
String. The unique name of the new class. The name must begin with an
uppercase alphabetic character. |
pObjectInterface
|
A pointer to an SoObjectInterface. A structure containing pointers to the
object interface methods for instances of this class. |
Creates a new JavaScript class.
Returns an error code, kESErrOK
on success.
addMethod()
ESerror_t addMethod (SoHObject hObject, const char* name, int id, char* desc);
hObject
|
The Support structures reference for an instance of this class. |
name
|
String. The unique name of the new method. |
id
|
Number. The unique identifier for the new method. |
desc
|
String. A descriptive string for the new method. |
Adds new method to an instance.
Returns an error code, kESErrOK
on success.
addMethods()
ESerror_t addMethods (SoHObject hObject, SoCClientName_p pNames);
hObject
|
The Support structures reference for an instance of this class. |
pNames[]
|
SoCClientName. A structure containing the names and identifiers of
methods to be added. |
Adds a set of new methods to an instance.
Returns an error code, kESErrOK
on success.
addProperty()
ESerror_t addProperty (SoHObject hObject, const char* name, int id, char* desc);
hObject
|
The Support structures reference for an instance of this class. |
name
|
String. The unique name of the new property. |
id
|
Number. The unique identifier for the new property. |
desc
|
String. Optional. A descriptive string for the new property, or null. |
Adds new property to an instance.
Returns an error code, kESErrOK
on success.
addProperties()
ESerror_t addProperties (SoHObject hObject, SoCClientName_p pNames);
hObject
|
The Support structures reference for an instance of this class. |
pNames[]
|
SoCClientName. A structure containing the names and identifiers of
properties to be added. |
Adds a set of new properties to an instance.
Returns an error code, kESErrOK
on success.
getClass()
ESerror_t getClass (SoHObject hObject, char* name, int name_l);
hObject
|
The Support structures reference for an instance of this class. |
name
|
String. A buffer in which to return the unique name of the class. |
name_1
|
Number. The size of the name buffer. |
Retrieves this object’s parent class name.
Returns an error code, kESErrOK
on success.
getServer()
ESerror_t getServer (SoHObject hObject, SoHServer* phServer, SoServerInterface_p* ppServerInterface);
Retrieves the interface methods for this object, and the server object that manages it.
Returns an error code, kESErrOK
on success.
setClientData()
ESerror_t setClientData (SoHObject hObject, void* pData);
hObject
|
The Support structures reference for an instance of this class. |
pData
|
A pointer to the library-defined data. |
Sets your own data to be stored with an object.
Returns an error code, kESErrOK
on success.
getClientData()
ESerror_t setClientData (SoHObject hObject, void** pData);
hObject
|
The Support structures reference for an instance of this class. |
pData
|
A buffer in which to return a pointer to the library-defined data. |
Retrieves data that was stored with setClientData().
Returns an error code, kESErrOK
on success.
eval()
ESerror_t eval (SohServer hServer, char* string, TaggedData* pTaggedData);
hServer
|
The Support structures reference for this shared library, as passed to your global
ESClientInterface() function on initialization. |
string
|
A string containing the JavaScript expression to evaluate. |
pTaggedData
|
A pointer to a TaggedData object in which to return the result of evaluation. |
Calls the JavaScript interpreter to evaluate a JavaScript expression.
Returns an error code, kESErrOK
on success.
taggedDataInit()
ESerror_t taggedDataInit (SoHSever hServer, TaggedData* pTaggedData);
Initializes a TaggedData structure.
Returns an error code, kESErrOK
on success.
taggedDataFree()
ESerror_t setClientData (SoHServer hServer, TaggedData* pTaggedData);
Frees memory being used by a TaggedData structure.
Returns an error code, kESErrOK
on success.
SoObjectInterface
When you add a JavaScript class with SoServerInterface.addClass(), you must provide this interface.
JavaScript calls the provided functions to interact with objects of the new class.
The SoObjectInterface is an array of function pointers defined as follows:
SoObjectInterface {
SoObjectInitialize_f initialize;
SoObjectPut_f put;
SoObjectGet_f get;
SoObjectCall_f call;
SoObjectValueOf_f valueOf;
SoObjectToString_f toString;
SoObjectFinalize_f finalize;
}
All SoObjectInterface
members must be valid function pointers, or NULL. You must implement
initialize()
and finalize()
. The functions must conform to the following type definitions.
initialize()
ESerror_t initialize (SoHObject hObject, int argc, TaggedData* argv);
hObject
|
The Support structures reference for an instance of this class. |
argc, argv
|
The number of and pointer to arguments passed to the constructor, in the form of TaggedData. |
Required. Called when JavaScript code instantiates this class with the new operator:
var xx = New MyClass(arg1, ...)
The initialization function typically adds properties and methods to the object. Objects of the same
class can offer different properties and methods, which you can add with the addMethod() and
addProperty() functions in the stored SoServerInterface.
Returns an error code, kESErrOK
on success.
put()
ESerror_t put (SoHObject hObject, SoCClientName* name, TaggedData* pValue);
Called when JavaScript code sets a property of this class:
If you provide NULL
for this function, the JavaScript object is read-only.
Returns an error code, kESErrOK
on success.
get()
ESerror_t get (SoHObject hObject, SoCClientName* name, TaggedData* pValue);
Called when JavaScript code accesses a property of this class:
Returns an error code, kESErrOK
on success.
call()
ESerror_t call (SoHObject hObject, SoCClientName* name, int argc, TaggedData* argv, TaggedData* pResult);
hObject
|
The Support structures reference for an instance of this class. |
name
|
The name of the property, a pointer to an SoCClientName. |
argc, argv
|
The number and pointer to arguments passed to the call, in the form of TaggedData |
pResult
|
A buffer in which to return the result of the call, in the form of TaggedData |
Called when JavaScript code calls a method of this class:
Required in order for JavaScript to call any methods of this class.
Returns an error code, kESErrOK
on success.
valueOf()
ESerror_t valueOf (SoHObject hObject, TaggedData* pResult);
hObject
|
The Support structures reference for an instance of this class. |
pResult
|
A buffer in which to return the result of the value, in the form of TaggedData |
Creates and returns the value of the object, with no type conversion.
Returns an error code, kESErrOK
on success.
toString()
ESerror_t toString (SoHObject hObject, TaggedData* pResult);
hObject
|
The Support structures reference for an instance of this class. |
pResult
|
A buffer in which to return the result of the string, in the form of TaggedData |
Creates and returns a string representing the value of this object.
Returns an error code, kESErrOK
on success.
finalize()
ESerror_t finalize (SoHObject hObject);
Required. Called when JavaScript deletes an instance of this class.
Use this function to free any memory you have allocated.
Returns an error code, kESErrOK
on success.