js-ctypes reference

  • Revision slug: Mozilla/js-ctypes/js-ctypes_reference
  • Revision title: js-ctypes reference
  • Revision id: 4055
  • Created:
  • Creator: bholley
  • Is current revision? No
  • Comment 18 words added

Revision Content

{{ gecko_minversion_header("2.0") }}{{ draft() }}

There are several steps required to use js-ctypes. This reference presents these topics roughly in the order that you'll need them.

Importing the js-ctypes Module

In order to use js-ctypes, you must import the ctypes.jsm module in your code. This creates a global variable called ctypes.

The Global ctypes Object

You can use the ctypes object to load libraries, construct types, and perform miscellaneous tasks such as type casting. The ctypes object also provides numerous predefined types that correspond to primitives and common typedefs in C.

Working With Libraries

Loading a library with ctypes.open() returns a Library object. This is used mostly to declare native functions provided by the library so that js-ctypes knows how to call them.

Types and Data

To use js-ctypes effectively, it is important to understand the different kinds of objects that the module provides. There are three major categories:

  1. Type Constructors. These are functions that define new types, and thus return a CType object. These include ctypes.PointerType(), ctypes.ArrayType(), ctypes.StructType(), and ctypes.FunctionType(). There are also convenience type constructors built into existing CType objects:
    • The .ptr property, which dynamically creates a new type describing a pointer to the existing type.
    • The .array() method, which dynamically creates a new type describing an array of objects of the previous type.
  2. Types. These represent a type in C, and are thus represented by CType objects. These objects have two main purposes. First, they provide a concrete representation of different data types, allowing the programmer to describe the arguments and return type of a native function. See CTypes.declare(). Second, they serve as constructors to create concrete instances of the given type, i.e. CData objects.
  3. Data. These are instances of types, represented by CData objects and instantiated by calling CType objects as functions.

These distinctions are crucial, and understanding them will alleviate much of the confusion surrounding js-ctypes. Calling a Type Constructor will return a CType. Calling a CType will return a CData. You declare the arguments and return value of a native function with CType objects. You call a native function with CData objects.

64-Bit Integer Handling

See Int64 and UInt64.

Revision Source

<p>{{ gecko_minversion_header("2.0") }}{{ draft() }}</p>
<p>There are several steps required to use js-ctypes. This reference presents these topics roughly in the order that you'll need them.</p>
<h2>Importing the js-ctypes Module</h2>
<p>In order to use js-ctypes, you must <a href="/en/JavaScript_code_modules/ctypes.jsm" title="en/JavaScript code modules/ctypes.jsm">import the <code>ctypes.jsm</code> module</a> in your code. This creates a global variable called <code>ctypes</code>.</p>
<h2>The Global ctypes Object</h2>
<p>You can use the <a href="/en/js-ctypes/js-ctypes_reference/ctypes" title="en/js-ctypes/js-ctypes reference/ctypes"><code>ctypes</code></a> object to load libraries, construct types, and perform miscellaneous tasks such as type casting. The <code><code>ctypes</code></code> object also provides numerous <a href="/en/js-ctypes/js-ctypes_reference/ctypes#Predefined_data_types" title="en/js-ctypes/js-ctypes reference/ctypes#Predefined data types">predefined types</a> that correspond to primitives and common typedefs in C.</p>
<h2>Working With Libraries</h2>
<p>Loading a library with <code><a href="/en/js-ctypes/js-ctypes_reference/ctypes#open()" title="en/js-ctypes/js-ctypes reference/ctypes#open()">ctypes.open()</a></code> returns a <code><a href="/en/js-ctypes/js-ctypes_reference/Library" title="en/js-ctypes/js-ctypes reference/Library">Library</a></code> object. This is used mostly to declare native functions provided by the library so that js-ctypes knows how to call them.</p>
<h2>Types and Data</h2>
<p>To use js-ctypes effectively, it is important to understand the different kinds of objects that the module provides. There are three major categories:</p>
<ol> <li><strong>Type Constructors</strong>. These are functions that define new types, and thus return a <code><a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType">CType</a></code> object. These include <code><a href="/en/js-ctypes/js-ctypes_reference/ctypes#PointerType()" title="en/js-ctypes/js-ctypes reference/ctypes#PointerType()">ctypes.PointerType()</a></code>, <code><a href="/en/js-ctypes/js-ctypes_reference/ctypes#ArrayType()" title="en/js-ctypes/js-ctypes reference/ctypes#ArrayType()">ctypes.ArrayType()</a></code>, <code><a href="/en/js-ctypes/js-ctypes_reference/ctypes#StructType()" title="en/js-ctypes/js-ctypes reference/ctypes#StructType()">ctypes.StructType()</a></code>, and <code><a href="/en/js-ctypes/js-ctypes_reference/ctypes#FunctionType()" title="en/js-ctypes/js-ctypes reference/ctypes#FunctionType()">ctypes.FunctionType()</a></code>. There are also convenience type constructors built into existing <code><a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType">CType</a></code> objects:<br> <ul> <li>The <span id="1314126976186S" style="display: none;"> </span><code>.<span id="1314126975740E" style="display: none;"> </span>ptr</code> property, which dynamically creates a new type describing a pointer to the existing type.</li> <li>The <a href="/en/js-ctypes/js-ctypes_reference/CType#array()" title="en/js-ctypes/js-ctypes reference/CType#array()"><code>.array()</code></a> method, which dynamically creates a new type describing an array of objects of the previous type.</li> </ul> </li> <li><strong>Types</strong>. These represent a type in C, and are thus represented by <code><a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType">CType</a></code> objects. These objects have two main purposes. First, they provide a concrete representation of different data types, allowing the programmer to describe the arguments and return type of a native function. See <code><a href="/en/js-ctypes/js-ctypes_reference/ctypes#declare()" title="en/js-ctypes/js-ctypes reference/CTypes#declare()">CTypes.declare()</a></code>. Second, they serve as constructors to create concrete instances of the given type, i.e. <code><a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData">CData</a></code> objects.</li> <li><strong>Data</strong>. These are instances of types, represented by <a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData"><code>CData</code></a> objects and instantiated by calling <a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a> objects as functions.</li>
</ol>
<p>These distinctions are crucial, and understanding them will alleviate much of the confusion surrounding js-ctypes. Calling a Type Constructor will return a <code>CType</code>. Calling a <code>CType</code> will return a <code>CData</code>. You <em>declare</em> the arguments and return value of a native function with <code>CType</code> objects. You <em>call</em> a native function with <code>CData</code> objects.</p>
<h2>64-Bit Integer Handling</h2>
<p>See <a href="/en/js-ctypes/js-ctypes_reference/Int64" title="en/js-ctypes/js-ctypes reference/Int64">Int64</a> and <a href="/en/js-ctypes/js-ctypes_reference/UInt64" title="en/js-ctypes/js-ctypes reference/UInt64">UInt64</a>.</p>
Revert to this revision