Callbacks

  • Revision slug: Mozilla/js-ctypes/js-ctypes_reference/Callbacks
  • Revision title: Callbacks
  • Revision id: 52001
  • Created:
  • Creator: bholley
  • Is current revision? No
  • Comment 63 words added, 1 words removed

Revision Content

C functions occasionally take function pointers as arguments, which are generally used as callbacks. In these cases, js-ctypes allows you can pass a regular javascript function as the callback. This is very powerful, since it allows native code to transparently call into javascript.

Creating callbacks

Since callbacks are function pointers in C, js-ctypes has special handling for function pointer types. Consider the following code:

function myJSCallback(foo, bar) { .... };
var funcType = ctypes.FunctionType(...);
var funcPtrType = funcType.ptr;
var regularFuncPtr = funcPtrType();
var callback = funcPtrType(myJSCallback); 

js-ctypes detects that funcPtrType is a type of function pointer, and adds a special case to its constructor. In the ordinary case, invoking the type object creates a regular CData object containing a word-sized pointer. However, if the first argument is a function, js-ctypes creates a special object (known internally as a CClosure) that wraps the javascript function within an ordinary C function. This can all be done in a single line of code, like so:

var callback = ctypes.FunctionType(...).ptr(function(...) {...});
Note that the use of .ptr() here isn't a method call - we're accessing a property that dynamically creates a callable object, and then invoking the result.

If two arguments are passed to the callback constructor, the second is used as the this parameter:

function myJSCallback() { alert(this.message); };
var receiver = { message: 'hi there!' };
var callback = funcPtrType(myJSCallback, receiver); // alerts with 'hi there' when the callback is invoked

Arguments and Return Values

js-ctypes automatically handles the conversion between javascript and C value representations. Before the javascript callback function is invoked, js-ctypes converts the arguments passed by the caller to javascript values. Where possible, js-ctypes will convert arguments to primitive types. For arguments of complex types, temporary CData objects will be created.

The return value is converted in a similar manner.

Revision Source

<p>C functions occasionally take function pointers as arguments, which are generally used as callbacks. In these cases, js-ctypes allows you can pass a regular javascript function as the callback. This is very powerful, since it allows native code to transparently call into javascript.</p>
<h2>Creating callbacks</h2>
<p>Since callbacks are function pointers in C, js-ctypes has special handling for function pointer types. Consider the following code:</p>
<pre>function myJSCallback(foo, bar) { .... };
var funcType = ctypes.FunctionType(...);
var funcPtrType = funcType.ptr;
var regularFuncPtr = funcPtrType();
var callback = funcPtrType(myJSCallback); 
</pre>
<p>js-ctypes detects that <code>funcPtrType</code> is a type of function pointer, and adds a special case to its constructor. In the ordinary case, invoking the type object creates a regular <a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData"><code>CData</code></a> object containing a word-sized pointer. However, if the first argument is a function, js-ctypes creates a special object (known internally as a CClosure) that wraps the javascript function within an ordinary C function. This can all be done in a single line of code, like so:</p>
<pre>var callback = ctypes.FunctionType(...).ptr(function(...) {...});
</pre>
<div class="note">Note that the use of .<code><code>ptr</code></code>() here isn't a method call - we're accessing a property that dynamically creates a callable object, and then invoking the result.</div>
<p>If two arguments are passed to the callback constructor, the second is used as the <code>this</code> parameter:</p>
<pre>function myJSCallback() { alert(this.message); };
var receiver = { message: 'hi there!' };
var callback = funcPtrType(myJSCallback, receiver); // alerts with 'hi there' when the callback is invoked
</pre><h2>Arguments and Return Values</h2>
<p>js-ctypes automatically handles the conversion between javascript and C value representations. Before the javascript callback function is invoked, js-ctypes converts the arguments passed by the caller to javascript values. Where possible, js-ctypes will convert arguments to primitive types. For arguments of complex types, temporary <a href="/en/js-ctypes/js-ctypes_reference/CData" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CData"><code>CData</code></a> objects will be created.</p>
<p>The return value is converted in a similar manner.</p>
Revert to this revision