JSctypes

Note: {{{1}}}

Overview

js-ctypes is a foreign-function library for Mozilla’s privileged JavaScript. It provides C-compatible data types and allows JS code to call functions in shared libraries (dll, so, dylib) and implement callback functions. The interface and implementation are modeled on the <a href="http://docs.python.org/lib/module-ctypes.html">Python ctypes module</a>.

The main objective for the library is to help developers avoid building binary (C++) <a href="http://developer.mozilla.org/en/docs/XPCOM">XPCOM</a> components when only a simple wrapper is needed. Such situations include:

1. Developer wants functionality not built into the Mozilla platform, but easily supported by the native OS.
2. Developer wants to use a 3rd party library in an extension or XUL app.
3. Developer has methods in native code for performance reasons.

The usual answer to these problems is creating a binary (C++) component to act as a wrapper so the native features can be exposed to JavaScript via XPCOM. However, the process of building binary XPCOM components is significantly harder than <a href="http://developer.mozilla.org/en/docs/How_to_Build_an_XPCOM_Component_in_Javascript">JavaScript components</a>. The macros and memory management rules of binary components are harder than JavaScript, but its really the compiler and linker flags, IDL, makefiles and SDK versioning that make the process painful. The build process must be repeated for each platform too. For many cases, its just too much work.

The goal of js-ctypes is to allow developers to declare methods in binary libraries and then expose those methods as callable JavaScript functions. Developers can then create pure JavaScript library wrappers around binary libraries - without making binary XPCOM wrappers.

Example Usage

/* Load JS Ctypes Javascript module */
Components.utils.import("resource://gre/modules/ctypes.jsm");

/* Load windows api dll */
var lib = ctypes.open("C:\\WINDOWS\\system32\\user32.dll");

/* Declare the signature of the function we are going to call */
var msgBox = lib.declare("MessageBoxW",
                         ctypes.stdcall_abi,
                         ctypes.int32_t,
                         ctypes.int32_t,
                         ctypes.ustring,
                         ctypes.ustring,
                         ctypes.int32_t);
var MB_OK = 3;

/* Do it! */
var ret = msgBox(0, "Hello world", "title", MB_OK);

/* Display the returned value */
alert("MessageBox result : "+ret);

lib.close();

Instead of defining the whole path, you may also just give the file name.

var lib = ctypes.open("user32.dll");

Or even without the extension.

var lib = ctypes.open("user32");

If the full path is not given, Windows uses the following search order to locate the DLL:

1. The current directory of the task that is using the DLL.
2. The \WINNT directory.
3. The \WINNT\SYSTEM directory.
4. The \WINNT\SYSTEM32 directory.
5. The directory of the executable for the task that is using the DLL.
6. A directory listed in the PATH environment variable.

(taken from http://support.microsoft.com/kb/164501/)

Note: This functionality cannot be accessed from JavaScript used in web content. Only JavaScript that runs with chrome privileges (extensions and Firefox UI for example) can use js-ctypes.

Technical Notes and Limitations

The js-ctypes code uses the same <a href="http://sourceware.org/libffi/">libffi</a> library as the Python ctypes module. It is currently known to work on Windows, Mac and Linux.

Getting the Code

The code can be checked out using Subversion:

svn co http://svn.mozilla.org/projects/js-ctypes/trunk/

It can also be viewed online <a href="http://viewvc.svn.mozilla.org/vc/projects/js-ctypes/">here</a>.

Build Instructions

Until js-ctypes makes its way into the Mozilla tree, building it will be a bit of a chore.

You'll first want to check out and build the Mozilla tree. See the <a href="http://developer.mozilla.org/en/docs/Build_Documentation">Build Documentation</a> for information on how to do this. The rest of these instructions assume that the path to your mozilla tree source is called PATH_TO_MOZILLA and that your objdir is in PATH_TO_OBJDIR.

You'll first want to create a directory called PATH_TO_MOZILLA/toolkit/components/js-ctypes and put the svn checkout there.

Then, from your objdir root, run the following command:

PATH_TO_MOZILLA/build/autoconf/make-makefile toolkit/components/js-ctypes

This should build the necessary Makefiles in your objdir, creating directories as necessary.

Now enter the PATH_TO_OBJDIR/toolkit/components/js-ctypes directory and run make.

Once that's done, you should be able to enter PATH_TO_OBJDIR/dist/bin and use <a href="http://www.mozilla.org/scriptable/XPCShell.html">xpcshell</a> to play around with the component (see the example usage code above).

Contributing

Contributions are welcome! We have a Bugzilla component (<a href="https://bugzilla.mozilla.org/buglist.cgi?query_format=advanced&product=Other+Applications&component=js-ctypes&resolution=---&chfieldto=Now">see bugs</a>, <a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Other%20Applications&component=js-ctypes">file bug</a>). Please feel free to join #labs on irc.mozilla.org if you have any other questions.