defining-entry-points-for-indirect-access

Defining entry points for indirect access

The C-client object interface for external libraries allows your C or C++ shared-library code to define, create, use, and manage JavaScript objects.

Entry Points

The following entry points are required if you wish to use the object interface:

ESClientInterface()

int ESClientInterface (SoCClient_e kReason, SoServerInterface* pServer, SoHServer hServer)

Description

Your library must define this global function in order to use the object interface to JavaScript. The function is called twice in each session, immediately upon loading the library, and again when unloading it.

Parameters

Parameter	Description
`kReason`	The reason for this call, one of these constants:
	- `kSoCClient_init`: The function is being called for initialization upon load.
	- `kSoCClient_term`.: The function is being called for termination upon unload.
`pServer`	A pointer to an SoServerInterface containing function pointers for the entry points, which enable the shared-library code to call into JavaScript to create and access JavaScript classes and objects.
	The shared-library code is responsible for storing this structure between the initialization and termination call, and retrieving it to access the functions.
`hServer`	An Support structures reference for this shared library. The server is an object factory that creates and manages Support structures objects.
	The shared-library code is responsible for storing this structure between the initialization and termination calls. You must pass it to taggedDataInit() and taggedDataFree().

Returns

Returns an error code, kESErrOK on success.

ESMallocMem()

void * ESMallocMem (size_t nbytes)

Description

Provides a memory allocation routine to be used by JavaScript for managing memory associated with the library’s objects.

Parameters

Parameter	Description
`nbytes`	The number of bytes to allocate.

Returns

A pointer to the allocated block of memory.

Shared-library function API

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);

Description

Prints the contents of this server to the JavaScript Console in the ExtendScript Toolkit, for debugging.

Parameters

Parameter	Description
`hServer`	The Support structures reference for this shared library, as passed to your global ESClientInterface() function on initialization.

Returns

Returns an error code, kESErrOK on success.

dumpObject()

ESerror_t dumpObject (SoHObject hObject);

Description

Prints the contents of this object to the JavaScript Console in the ExtendScript Toolkit, for debugging.

Parameters

Parameter	Description
`hObject`	The Support structures reference for an instance of this class.

Returns

Returns an error code, kESErrOK on success.

addClass()

ESerror_t addClass (SoHServer hServer, char* name, SoObjectInterface_p pObjectInterface);

Description

Creates a new JavaScript class.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

addMethod()

ESerror_t addMethod (SoHObject hObject, const char* name, int id, char* desc);

Description

Adds new method to an instance.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

addMethods()

ESerror_t addMethods (SoHObject hObject, SoCClientName_p pNames);

Description

Adds a set of new methods to an instance.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

addProperty()

ESerror_t addProperty (SoHObject hObject, const char* name, int id, char* desc);

Description

Adds new property to an instance.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

addProperties()

ESerror_t addProperties (SoHObject hObject, SoCClientName_p pNames);

Description

Adds a set of new properties to an instance.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

getClass()

ESerror_t getClass (SoHObject hObject, char* name, int name_l);

Description

Retrieves this object’s parent class name.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

getServer()

ESerror_t getServer (SoHObject hObject, SoHServer* phServer, SoServerInterface_p* ppServerInterface);

Description

Retrieves the interface methods for this object, and the server object that manages it.

Parameters

Parameter	Description
`hObject`	The Support structures reference for an instance of this class.
`phServer`	A buffer in which to return the Support structures reference for this object.
`ppServerInterface`	A buffer in which to return the SoObjectInterface reference for this object.

Returns

Returns an error code, kESErrOK on success.

setClientData()

ESerror_t setClientData (SoHObject hObject, void* pData);

Description

Sets your own data to be stored with an object.

Parameters

Parameter	Description
`hObject`	The Support structures reference for an instance of this class.
`pData`	A pointer to the library-defined data.

Returns

Returns an error code, kESErrOK on success.

getClientData()

ESerror_t setClientData (SoHObject hObject, void** pData);

Description

Retrieves data that was stored with setClientData().

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

eval()

ESerror_t eval (SohServer hServer, char* string, TaggedData* pTaggedData);

Description

Calls the JavaScript interpreter to evaluate a JavaScript expression.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

taggedDataInit()

ESerror_t taggedDataInit (SoHSever hServer, TaggedData* pTaggedData);

Description

Initializes a TaggedData structure.

Parameters

Parameter	Description
`hServer`	The Support structures reference for this shared library, as passed to your global ESClientInterface() function on initialization.
`pTaggedData`	A pointer to a TaggedData.

Returns

Returns an error code, kESErrOK on success.

taggedDataFree()

ESerror_t setClientData (SoHServer hServer, TaggedData* pTaggedData);

Description

Frees memory being used by a TaggedData structure.

Parameters

Parameter	Description
`hServer`	The Support structures reference for this shared library, as passed to your global ESClientInterface() function on initialization.
`pTaggedData`	A pointer to a TaggedData.

Returns

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);

Description

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.

Parameters

Parameter	Description
`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.

Returns

Returns an error code, kESErrOK on success.

put()

ESerror_t put (SoHObject hObject, SoCClientName* name, TaggedData* pValue);

Description

Called when JavaScript code sets a property of this class:

xx.myproperty = "abc" ;

If you provide NULL for this function, the JavaScript object is read-only.

Parameters

Parameter	Description
`hObject`	The Support structures reference for an instance of this class.
`name`	The name of the property, a pointer to an SoCClientName.
`pValue`	The new value, a pointer to a TaggedData.

Returns

Returns an error code, kESErrOK on success.

get()

ESerror_t get (SoHObject hObject, SoCClientName* name, TaggedData* pValue);

Description

Called when JavaScript code accesses a property of this class:

alert(xx.myproperty);

Parameters

Parameter	Description
`hObject`	The Support structures reference for an instance of this class.
`name`	The name of the property, a pointer to an SoCClientName.
`pValue`	A buffer in which to return the property value, a TaggedData.

Returns

Returns an error code, kESErrOK on success.

call()

ESerror_t call (SoHObject hObject, SoCClientName* name, int argc, TaggedData* argv, TaggedData* pResult);

Description

Called when JavaScript code calls a method of this class:

xx.mymethod()

Required in order for JavaScript to call any methods of this class.

Parameters

Parameter	Description
`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

Returns

Returns an error code, kESErrOK on success.

valueOf()

ESerror_t valueOf (SoHObject hObject, TaggedData* pResult);

Description

Creates and returns the value of the object, with no type conversion.

Parameters

Parameter	Description
`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

Returns

Returns an error code, kESErrOK on success.

toString()

ESerror_t toString (SoHObject hObject, TaggedData* pResult);

Description

Creates and returns a string representing the value of this object.

Parameters

Parameter	Description
`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

Returns

Returns an error code, kESErrOK on success.

finalize()

ESerror_t finalize (SoHObject hObject);

Description

Required. Called when JavaScript deletes an instance of this class.

Use this function to free any memory you have allocated.

Parameters

Parameter	Description
`hObject`	The Support structures reference for an instance of this class.

Returns

Returns an error code, kESErrOK on success.

Support structures

These support structures are passed to functions that you define for your JavaScript interface:

Parameters

Parameter	Description
`SoHObject`	An opaque pointer `(long *)` to the C/C++ representation of a JavaScript object.
`SoHServer`	An opaque pointer `(long *)` to the server object, which acts as an object factory for the shared library.
`SoCClientName`	A structure that uniquely identifies methods and properties.
`TaggedData`	A structure that encapsulates data values with type information, to be passed between C/C++ and JavaScript.

SoCClientName

The SoCClientName data structure stores identifying information for methods and properties of JavaScript objects created by shared-library C/C++ code. It is defined as follows:

SoCClientName {
 char* name_sig ;
 uint32_t id ;
 char* desc ;
}

Parameters

Parameter	Description
`name_sig`	The name of the property or method, unique within the class. Optionally contains a signature following an underscore, which identifies the types of arguments to methods; see Function signatures. When names are passed back to your SoObjectInterface functions, the signature portion is omitted.
`id`	A unique identifying number for the property or method, or 0 to assign a generated UID. If you assign the UID, your C/C++ code can use it to avoid string comparisons when identifying JavaScript properties and methods. It is recommended that you either assign all UIDs explicitly, or allow them all to be generated.
`desc`	A descriptive string or `NULL`.

TaggedData

The TaggedData structure is used to communicate data values between JavaScript and shared-library C/C++ code. Types are automatically converted as appropriate:

typedef struct {
 union {
 long intval;
 double fltval;
 char* string;
 SoHObject* hObject;
 } data;
 long type;
 long filler;
} TaggedData;

Parameters

Parameter	Description
`intval`	Integer and boolean data values. Type is `kTypeInteger`, `kTypeUInteger`, or `kTypeBool`.
`fltval`	Floating-point numeric data values. Type is `kTypeDouble`.
String	String data values. All strings are UTF-8 encoded and null-terminated. Type is `kTypeString` or `kTypeScript`.
	- The library must define an entry point ESFreeMem(), which ExtendScript calls to release a returned string pointer. If this entry point is missing, ExtendScript does not attempt to release any returned string data.
	- When a function returns a string of type kTypeScript, ExtendScript evaluates the script and returns the result of evaluation as the result of the function call.
`hObject`	A C/C++ representation of a JavaScript object data value. Type is `kTypeLiveObject` or `kTypeLiveObjectRelease`.
	- When a function returns an object of type kTypeLiveObject, ExtendScript does not release the object.
	- When a function returns an object of type kTypeLiveObjectRelease, ExtendScript releases the object.
`type`	The data type tag. One of:
	- `kTypeUndefined`: a null value, equivalent of JavaScript `undefined`. The return value for a function is always set to this by default.
	- `kTypeBool`: a boolean value, 0 for `false`, 1 for `true`.
	- `kTypeDouble`: a 64-bit floating-point number.
	- `kTypeString`: a character string.
	- `kTypeLiveObject`: a pointer to an internal representation of an object (SoHObject).
	- `kTypeLiveObjectRelease`: a pointer to an internal representation of an object (SoHObject).
	- `kTypeInteger`: a 32-bit signed integer value.
	- `kTypeUInteger`: a 32-bit unsigned integer value.
	- `kTypeScript`: a string containing an executable JavaScript script.
`filler`	A 4-byte filler for 8-byte alignment.