ExtendScript ToolKit

# SampleLib.cpp File Reference

## Detailed Description

The sample shows how to implement an external object and to extend the JavaScript DOM, showing in particular how to use the object-oriented interface.

The sample demonstrates the two mechansisms for extending the JavaScript DOM, the direct interface and the indirect (object-oriented) interface.

Direct Interface:
This enables you to expose methods of your shared library as a method in the JavaScript environment. This allows you to pass simple data types back to JavaScript from the External Object such as Strings, booleans, integers and scripts.

For information on how to call the individual methods from JavaScript, see the comments for each methods or see the loadSampleLib.jsx script file that accompanies this sample.

Indirect Interface:
This enables you to create new classes of objects in JavaScript with properties and methods. Your Shared Library is called when these methods or properties are used in in JavaScript.

If you are working with an installed (Release) build of Adobe Bridge CS3, then we recommend you choose the Release configuration of the shared library when testing the SampleLib. You can modify the shared library (Debug or Release) that is loaded in the loadSampleLib.jsx file itself.

See the JavaScript Tools Guide for more information on the direct interface and indirect (object-oriented) interface.

See SoSharedLibDefs.h for error codes and return types

See SoCClient.h for the indirect (object-oriented) interface

See sampleprojects for information on how to build the library

See installing for information on how to install and use the library

## Classes
struct | myData_s
## Typedefs
typedef struct myData_s | myData_t
typedef myData_t * | myData_p
## Functions
void * | unused (void *x)
SAMPLIB long | ESGetVersion ()
| Returns the version number of the library.
SAMPLIB char * | ESInitialize (TaggedData *argv, long argc)
| Initialize the library and return function signatures.
SAMPLIB void | ESTerminate ()
| Terminate the library.
SAMPLIB void | ESFreeMem (void *p)
| Free any string memory which has been returned as function result.
SAMPLIB void * | ESMallocMem (size_t nBytes)
| Allocate some memory.
SAMPLIB long | setVersion (TaggedData *argv, long argc, TaggedData *result)
| Change the version number by setting the global "version".
static char * | stringize (TaggedData *p)
| Helper function to "Stringize" each argument.
SAMPLIB long | createObject (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that takes arguments with a known type (because there is a signature for it).
SAMPLIB long | createArray (TaggedData *argv, long argc, TaggedData *result)
SAMPLIB long | paramAny (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that takes an argument of any type.
SAMPLIB long | paramBool (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that takes a boolean argument.
SAMPLIB long | paramUInt32 (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that takes an unsigned integer argument.
SAMPLIB long | paramInt32 (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that takes a signed integer argument.
SAMPLIB long | paramFloat64 (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that takes an 64 bit floating point argument.
SAMPLIB long | paramString (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that takes a string argument.
SAMPLIB long | built (TaggedData *argv, long argc, TaggedData *result)
| Example of a function that returns a string.
ESerror_t | objectInitialize (SoHObject hObject, int argc, TaggedData *argv)
| Called whenever a ne object is constructed.
ESerror_t | objectGet (SoHObject hObject, SoCClientName *name, TaggedData *pResult)
| Retrieves the value of a property of this object.
ESerror_t | objectPut (SoHObject hObject, SoCClientName *name, TaggedData *pValue)
| Sets a value of a property of this object.
ESerror_t | objectCall (SoHObject hObject, SoCClientName *name, int argc, TaggedData *argv, TaggedData *pResult)
| Calls a method of this object.
ESerror_t | objectToString (SoHObject hObject, TaggedData *pResult)
| Not used in this sample.
ESerror_t | objectValueOf (SoHObject hObject, TaggedData *pResult)
| Not used in this sample.
ESerror_t | objectFinalize (SoHObject hObject)
| Calls when the object is released from memory.
SAMPLIB int | ESClientInterface (SoCClient_e kReason, SoServerInterface *pServer, SoHServer hServer)
## Variables
static long | libraryVersionNumber = 1
| This is the version number, and can be modified by setVersion().
static char * | signatures
| String string that contains the signatures of every ESFunction defined here, used to support the JavaScript reflection interface.
SoObjectInterface * | gpObjectInterface = NULL
| Array of function pointers to communiate use of the new class.
SoServerInterface * | gpServer = NULL
| Structure of function pointers which enable the client to call JavaScript.
SoHServer | ghServer = NULL
| The server object.
int | ME = 0
| Counter for instances created.
SoObjectInterface | objectInterface
| Array of SoObjectInterface.

## Typedef Documentation

typedef myData_t* myData_p

typedef struct myData_s myData_t

## Function Documentation

SAMPLIB long built | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that returns a string.

If memory has not been allocated correctly then returns an out of memory error.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | result | The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::string, TaggedData_s::type, and unused().

Referenced by objectGet().

SAMPLIB long createArray | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

References TaggedData_s::data, TaggedData_s::string, stringize(), and TaggedData_s::type.

SAMPLIB long createObject | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that takes arguments with a known type (because there is a signature for it).

Returns a script that creates a small JavaScript object containing one property. Argument 1 contains the name of the property, argument 2 contains the value. Return a script that creates an object: "({ 'name':'value' })".

If the arguments are not correct then a bad argument error code is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | result | The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::string, stringize(), and TaggedData_s::type.

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

References SoServerInterface_s::addClass, ghServer, kSoCClient_init, kSoCClient_term, and ME.

SAMPLIB void ESFreeMem | ( | void * | p | ) |

Free any string memory which has been returned as function result.

JavaScipt calls this function to release the memory associated with the string. Used for the direct interface.

Parameters:

  | *p | Pointer to the string

SAMPLIB long ESGetVersion | ( |  | ) |

Returns the version number of the library.

ExtendScript publishes this number as the version property of the object created by new ExternalObject. Used by the direct interface.

References libraryVersionNumber.

SAMPLIB char* ESInitialize | ( | TaggedData * | argv,
|  | long | argc |
| ) |  |  |

Initialize the library and return function signatures.

These signatures have no effect on the arguments that can be passed to the functions. They are used by JavaScript to cast the arguments, and to populate the reflection interface.

References signatures, and unused().

SAMPLIB void* ESMallocMem | ( | size_t | nBytes | ) |

Allocate some memory.

Used for the object interface.

Parameters:

  | nBytes | The amount of space to allocate

Returns:
  Pointer to the allocated space

SAMPLIB void ESTerminate | ( |  | ) |

Terminate the library.

Does any necessary clean up that is needed.

ESerror_t objectCall | ( | SoHObject | hObject,
|  | SoCClientName * | name,
|  | int | argc,
|  | TaggedData * | argv,
|  | TaggedData * | pResult |
| ) |  |  |

Calls a method of this object.

Parameters:

  | hObject | - The reference for this instance
  | name | - The name of the method to call
  | argv | - The JavaScript argument
  | argc | - The argument count
  | pResult | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::fltval, TaggedData_s::intval, SoCClientName_s::name_sig, TaggedData_s::string, TaggedData_s::type, and unused().

ESerror_t objectFinalize | ( | SoHObject | hObject | ) |

Calls when the object is released from memory.

Parameters:

  | hObject | - The reference for this instance

References SoServerInterface_s::getClientData, and SoServerInterface_s::setClientData.

ESerror_t objectGet | ( | SoHObject | hObject,
|  | SoCClientName * | name,
|  | TaggedData * | pResult |
| ) |  |  |

Retrieves the value of a property of this object.

Parameters:

  | hObject | - The reference for this instance
  | name | - The name of the property
  | pResult | - Pointer to the result being returned to JavaScript

References built(), TaggedData_s::data, TaggedData_s::fltval, SoServerInterface_s::getClientData, TaggedData_s::intval, SoCClientName_s::name_sig, TaggedData_s::string, and TaggedData_s::type.

ESerror_t objectInitialize | ( | SoHObject | hObject,
|  | int | argc,
|  | TaggedData * | argv |
| ) |  |  |

Called whenever a ne object is constructed.

        var myObj = new SampleObject(param1);

Parameters:

  | hObject | - The reference for this instance
  | argc | - The argument count
  | argv | - The arguments passed in the constructor

References myData_s::a, SoServerInterface_s::addMethods, SoServerInterface_s::addProperties, myData_s::b, ME, myData_s::me, SoServerInterface_s::setClientData, SoServerInterface_s::taggedDataInit, and unused().

ESerror_t objectPut | ( | SoHObject | hObject,
|  | SoCClientName * | name,
|  | TaggedData * | pValue |
| ) |  |  |

Sets a value of a property of this object.

Parameters:

  | hObject | - The reference for this instance
  | name | - The name of the property to update
  | pValue | - A pointer to the value to write to the property

References TaggedData_s::data, SoServerInterface_s::getClientData, SoCClientName_s::name_sig, and TaggedData_s::string.

ESerror_t objectToString | ( | SoHObject | hObject,
|  | TaggedData * | pResult |
| ) |  |  |

Not used in this sample.

To implement, change from NULL to objectToString in array of SoObjectInterface.

See also:
  objectInterface

References TaggedData_s::data, SoServerInterface_s::getClientData, TaggedData_s::string, and TaggedData_s::type.

ESerror_t objectValueOf | ( | SoHObject | hObject,
|  | TaggedData * | pResult |
| ) |  |  |

Not used in this sample.

To implement, change from NULL to objectToString in array of SoObjectInterface.

See also:
  objectInterface

References TaggedData_s::data, SoServerInterface_s::getClientData, TaggedData_s::string, and TaggedData_s::type.

SAMPLIB long paramAny | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that takes an argument of any type.

If the arguments are not correct then a bad argument error code is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | - the argument count
  | result | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::fltval, TaggedData_s::intval, TaggedData_s::string, and TaggedData_s::type.

SAMPLIB long paramBool | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that takes a boolean argument.

If the arguments are not correct then a bad argument error code is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | result | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and TaggedData_s::type.

SAMPLIB long paramFloat64 | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that takes an 64 bit floating point argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | result | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::fltval, and TaggedData_s::type.

SAMPLIB long paramInt32 | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that takes a signed integer argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | - The argument count
  | result | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and TaggedData_s::type.

SAMPLIB long paramString | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that takes a string argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned. If memory has not been allocated correctly then returns an out of memory error.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | result | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::string, and TaggedData_s::type.

SAMPLIB long paramUInt32 | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Example of a function that takes an unsigned integer argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | result | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and TaggedData_s::type.

SAMPLIB long setVersion | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | result |
| ) |  |  |

Change the version number by setting the global "version".

     myObj.setVersion(2);

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | result | - The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and libraryVersionNumber.

static char* stringize | ( | TaggedData * | p | ) | `[static]`

Helper function to "Stringize" each argument.

If the argument is not a string, convert it to a string. If it is a string, escape all quotes in the string with a backslash and quote the entire string.

Parameters:

  | p | Pointer to a TaggedData

Returns:
  Return a dynamic buffer containing the string.

References TaggedData_s::data, TaggedData_s::intval, TaggedData_s::string, and TaggedData_s::type.

Referenced by createArray(), and createObject().

void* unused | ( | void * | x | ) |

Referenced by built(), ESInitialize(), objectCall(), and objectInitialize().

## Variable Documentation

SoHServer ghServer = NULL

The server object.

Referenced by ESClientInterface().

SoObjectInterface* gpObjectInterface = NULL

Array of function pointers to communiate use of the new class.

SoServerInterface* gpServer = NULL

Structure of function pointers which enable the client to call JavaScript.

long libraryVersionNumber = 1`[static]`

This is the version number, and can be modified by setVersion().

Referenced by ESGetVersion(), and setVersion().

int ME = 0

Counter for instances created.

Referenced by ESClientInterface(), and objectInitialize().

SoObjectInterface objectInterface

Initial value:

    {  objectInitialize
    ,  objectPut
    ,  objectGet
    ,  objectCall
    ,  NULL
    ,  NULL
    ,  objectFinalize
    }

Array of SoObjectInterface.

Provides the interface which is used by JavaScript to communicate the use of the object

char* signatures`[static]`

Initial value:

        "setVersion_d,"
        "createObject_ss,"
        "createArray,"
        "paramAny_a,"
        "paramString_s,"
        "paramBool_b,"
        "paramUInt32_u,"
        "paramInt32_d,"
        "paramFloat64_f"
        "built"

String string that contains the signatures of every ESFunction defined here, used to support the JavaScript reflection interface.

Note that this is a single comma-separated values string, concatenated by the compiler.

Referenced by ESInitialize().

Copyright© 2008 Adobe Systems Incorporated. All rights reserved.

Terms of Use Online Privacy Policy Adobe and accessibility Avoid software piracy Permissions and Trademarks