Adobe.com
Contents Files

Installing External Objects

Introduction

These pages describe getting started with external objects, which you can use to extend the ExtendScript DOM and call into shared libraries of your own written in C/C++.

External objects are a key extensibility pattern for Adobe Bridge and other Adobe applications that integrate ExtendScript. You might want to use them to call into your own existing platform-native libraries or exploit the ability to call into C/C++ code of your own from a scripting context.

Installing a Compiled External Object

Step 1: Installing

The External Objects sample should compile and work with the libraries (DLLs or frameworks) in the locations that they are compiled to; this is where the sample JavaScript files provided expect the libraries to be located.

Once you have successfully compiled and tested the sample code with the provided sample scripts, you should be aware of the recommended deployment pattern for Bridge extensions like your External Object library, which is effectively a plug-in to Bridge. If you change the location of the libraries to this location, be sure to change the paths in JavaScript files that load the libraries accordingly.

The recommended location for Bridge extensions is in the Bridge CS5 Extensions directory, which is shared by all users on a machine. All resources for an extension, including scripts, images and shared libraries, should be grouped in a directory and placed placed in:

  • Win
     %CommonProgramFiles%/Adobe/Bridge CS5 Extensions/   
    
  • Mac
     /Library/Application Support/Adobe/Bridge CS5 Extensions/  
    
The recommended structure for the directory that holds a Bridge extension "MyExtension" (a placeholder for the real name of your extension) would be similar to this:

   Bridge CS5 Extensions/
     MyExtension/
        MyExtension.jsx
        Read Me.txt
        manifest.xml
        Resources/
           Images/
              myext.png
           Scripts/
              001_myext.jsx
              002_myext.jsx
           Plugins/
              myext.dll
  

For the file in the example above named "MyExtension.jsx" to be loaded by Bridge on startup, it has to be in a folder that is an immediate child of the "Bridge CS5 Extensions" folder. However, the library can be placed anywhere in the file system as long as the correct path is used when instantiating an ExternalObject. It is recommended to place the library encapsulating your ExternalObject in a Plugins folder within your extension folder.

Step 2: Loading and Unloading

To load an external library from JavaScript, use the ExternalObject constructor:
 var myObj = new ExternalObject ("lib:" + libName); 

The constructor can take an arbitrary number of arguments, which are passed on to the library's initialization routine:

 myObj = new ExternalObject ("lib:" + libName, arg1, arg2); 

The specifier "lib:" is case sensitive. The library name can be the base name of the shared library as well as include the path to the library: Note: the ExternalObject architecture in future may be extended to wrap other types of external data; at present "lib:" is the marker for dynamically linked libraries.

  var libName = "C:\myLibraries\myLib.dll";
  var myObj = new ExternalObject ("lib:" + libName);

If the loader cannot load the library by its given name, it appends a file extension according to the operating system:

  • Windows: .DLL
  • Mac: .framework
If the library name does not contain a path specifier, but just the name of the library, then the loader first looks into the current folder for the library, which will be the application startup folder. If attaching the default extension does not work, the loader will then check the plug-ins folder within the program startup folder, Bridge for example would be:

  • Win - C:/Program Files/Adobe/Adobe Bridge CS5/Plug-Ins
  • Mac - /Applications/Adobe Bridge CS5/Plug-Ins
If you are following the recommendations above and using the Bridge CS5 Extensions directory, the library could be loaded as follows from a script executing from the root level of your "MyExtensions" folder, by writing:
  Folder.current = File ($.fileName).parent;
  var myLib = new ExternalObject("lib:Resources/Plugins/myLib.dll");

To unload a library, call the object's unload() method. This method unloads the library and leaves the object in an invalid state. Any attempts to access properties or methods of the library object once unloaded result in a runtime error.

  myLib.unload();

See Using the Sample Projects for information on how to find the sample projects

See Using the BasicExternalObject Sample for information on how to build the External Object sample

See Using the SampleLib Example for information on how to build the Sample Lib sample

Contents Files
Adobe Solutions Network
 
Copyright © 2010 Adobe Systems Incorporated. All rights reserved.
Terms of Use Online Privacy Policy Adobe and accessibility Avoid software piracy Permissions and Trademarks