Defining entry points for direct access¶
A library to be loaded and accessed directly through an ExternalObject instance must publish the following entry points. These must be exported as C functions, not C++ functions:
The following entry points are required if you wish to use an ExternalObject instance:
char* ESInitialize (TaggedData* argv, long argc);
||The pointer to and number of arguments passed to the constructor, in the form of TaggedData.|
Called when your library is loaded into memory.
Returns a string of function signatures; see Library initialization.
long ESGetVersion (void );
Takes no arguments, and returns a version number for the library as a long integer.
void ESFreeMem (void* p);
||A pointer to the string.|
Called to free memory allocated for a null-terminated string passed to or from library functions.
Each function must accept the following arguments:
- An array of TaggedData.
- An argument count.
- A variant data structure that takes the return value.
string- Must be UTF-8 encoded. 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.
If, when a function is invoked, a supplied parameter is undefined, ExtendScript sets the data type to
undefined and does not attempt to convert the data to the requested type.
ExtendScript calls ESInitialize() to initialize the library.
The function receives an argument vector containing the additional arguments passed in to the ExternalObject constructor.
If you choose to return a set of function name-signature strings, each string associates a function name with that function’s parameter types, if any. For example:
["functionName1_argtypes", "functionName2_argtypes", "functionName3"]
For each function, the string begins with the function name, followed by an underscore character and a list of argument data types, represented as a single character for each argument. If the function does not have arguments, you can omit the trailing underscore character (unless there is an underscore in the function name).
The characters that indicate data types are:
|a||Any type. The argument is not converted. This is the default, if no type is supplied or if a type code is unrecognized.|
|d||signed 32 bit integer|
|u||unsigned 32 bit integer|
|f||64 bit floating point|
For example, suppose your library defines these two entry points:
One (Integer a, String b); Two ();
The signature strings for these two functions would be
You cannot define function overloading by returning multiple different signatures for one function. Attempting to do so produces undefined results.
Define the entry point ESInitialize() to free any memory you have allocated when your library is
library. When the reference count for a library reaches 0, the library is automatically unloaded; your
termination function is called, and the
ExternalObject instance is deleted. Note that deleting the
ExternalObject instance does not unload the library if there are remaining references.