Adobe ExtendScript Toolkit

ExtendScript ToolKit

# SampleLib.cpp File Reference

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. More...

`#include "SampleLib.h"`
`#include "SoSharedLibDefs.h"`
`#include "SoCClient.h"`
`#include <stdlib.h>`
`#include <stdio.h>`
`#include <string.h>`
`#include <math.h>`

## 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. JavaScipt calls this function to release the memory associated with the string. Used for the direct interface.
SAMPLIB void * | ESMallocMem (size_t nBytes)
| Allocate some memory. Used for the object interface.
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. 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.
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' })".

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)
ESerror_t | objectValueOf (SoHObject hObject, TaggedData *pResult)
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
static char * | signatures
SoObjectInterface * | gpObjectInterface = NULL
SoServerInterface * | gpServer = NULL
SoHServer | ghServer = NULL
int | ME = 0
SoObjectInterface | objectInterface

## 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

## 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

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

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

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

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.

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.

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

ESerror_t objectFinalize | ( | SoHObject | hObject | ) |

Calls when the object is released from memory.

Parameters:

  | hObject | - The reference for this instance

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

## Variable Documentation

SoHServer ghServer = NULL

The server object

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().

int ME = 0

Counter for instances created

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.

Copyright© 2008 Adobe Systems Incorporated. All rights reserved.

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