JSctypes: Difference between revisions

Note! This article is outdated. See the devmo pages for the current version.https://developer.mozilla.org/en/js-ctypes

== 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:  

#Developer wants functionality not built into the Mozilla platform, but easily supported by the native OS.  

#Developer wants to use a 3rd party library in an extension or XUL app.  

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

<pre>/* Load JS Ctypes Javascript module */

alert("MessageBox result&nbsp;: "+ret);

</pre>  

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

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

</pre>  

Or even without the extension.  

<pre>var lib = ctypes.open("user32");

</pre>  

#The current directory of the task that is using the DLL.  

#The \WINNT directory.  

#The \WINNT\SYSTEM directory.  

#The \WINNT\SYSTEM32 directory.  

#The directory of the executable for the task that is using the DLL.  

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

<img _fck_mw_template="true" _fckrealelement="0" _fckfakelement="true" src="https://wiki.mozilla.org/extensions/FCKeditor/fckeditor/editor/images/spacer.gif" class="FCK__MWTemplate">

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

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

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 &lt;a href="http://developer.mozilla.org/en/docs/Build_Documentation"&gt;Build Documentation&lt;/a&gt; for information on how to do this. The rest of these instructions assume that the path to your mozilla tree source is called <tt>PATH_TO_MOZILLA</tt> and that your objdir is in <tt>PATH_TO_OBJDIR</tt>.  

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

<pre>PATH_TO_MOZILLA/build/autoconf/make-makefile toolkit/components/js-ctypes

</pre>  

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

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

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

<br>