Declaring types

  • Revision slug: Mozilla/js-ctypes/Using_js-ctypes/Declaring_types
  • Revision title: Declaring types
  • Revision id: 73090
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment explain how to use PointerType(); 257 words added, 31 words removed

Revision Content

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

The ctypes object offers a number of constructor methods that let you declare types. Every type is represented by a CType object, which, in turn, provides a constructor method you can call to define values of those types.

Types are declared in terms of other, already defined types. At the core of all this is a set of predefined types provided by js-ctypes. These are all primitive types, upon which all other types are eventually based.

Primitive types

Primitive types are those types that represent a single value in memory, as opposed to arrays, structures, or functions. You can define values of these types without declaring new types. For example, to define a new 32-bit integer variable with the value 5:

var i = ctypes.int32_t(5);

You can then pass a pointer to this value to a C function that requires a pointer to a 32-bit integer, like this:

some_c_function(i.address());

Declaring new primitive types

There are times when you want to create new types that are simply new names for existing primitive types. For example, on Windows, you may wish to be able to use the Windows-standard DWORD type name for unsigned 32-bit integers. To declare this type, you can simply do:

const DWORD = ctypes.uint32_t;

After doing this, DWORD is a CType that can then be used to represent 32-bit unsigned integers.

Pointers

There are two kinds of pointer types:

  • Pointer to a particular type
  • Opaque pointer

Declaring a pointer type is done using the ctypes.PointerType() method.

Declaring a pointer type

Declaring a pointer type as a pointer to a specific type is done by passing as a parameter to the ctypes.PointerType() method a CType object indicating the type to which the pointer should refer:

const IntPtr = new ctypes.PointerType(ctypes.int);

In this example, IntPtr is equivalent to this declaration in C:

typedef int *intPtr;

You can similarly declare a pointer type as a pointer to any user-defined type, including structures:

const UserRecord = new ctypes.StructType("UserRecord",
                        [{"name": ctypes.char.ptr},
                        {"id": ctypes.int32}]);
const UserRecordPtr = new ctypes.PointerType(UserRecord);

In this example, a new UserRecord type is defined, along with a new pointer type that can be used to reference it. The equivalent C code looks like this:

typedef struct UserRecord {
  char *name;
  int id;    // Assuming int is 32-bit here
} UserRecord;

typedef UserRecordPtr *UserRecord;

Declaring an opaque pointer type

Declaring an opaque pointer type is done by passing a string, indicating the name of the pointer type, to the ctypes.PointerType() method:

const HANDLE = new ctypes.PointerType("HANDLE");

This is equivalent to the following type declaration in C:

typedef void *HANDLE;

Revision Source

<p>{{ gecko_minversion_header("2.0") }}{{ draft() }}</p>
<p>The <code><a href="/en/js-ctypes/js-ctypes_reference/ctypes" title="en/js-ctypes/js-ctypes reference/ctypes">ctypes</a></code> object offers a number of constructor methods that let you declare types. Every type is represented by a <a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a> object, which, in turn, provides a constructor method you can call to define values of those types.</p>
<p>Types are declared in terms of other, already defined types. At the core of all this is a set of <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> provided by js-ctypes. These are all primitive types, upon which all other types are eventually based.</p>
<h2>Primitive types</h2>
<p><strong>Primitive types</strong> are those types that represent a single value in memory, as opposed to arrays, structures, or functions. You can define values of these types without declaring new types. For example, to define a new 32-bit integer variable with the value 5:</p>
<pre>var i = ctypes.int32_t(5);
</pre>
<p>You can then pass a pointer to this value to a C function that requires a pointer to a 32-bit integer, like this:</p>
<pre>some_c_function(i.address());
</pre>
<h3>Declaring new primitive types</h3>
<p>There are times when you want to create new types that are simply new names for existing primitive types. For example, on Windows, you may wish to be able to use the Windows-standard <code>DWORD</code> type name for unsigned 32-bit integers. To declare this type, you can simply do:</p>
<pre>const DWORD = ctypes.uint32_t;
</pre>
<p>After doing this, <code>DWORD</code> is a <a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a> that can then be used to represent 32-bit unsigned integers.</p>
<h2>Pointers</h2>
<p>There are two kinds of pointer types:</p>
<ul> <li>Pointer to a particular type</li> <li>Opaque pointer</li>
</ul>
<p>Declaring a pointer type is done using the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#PointerType()" title="en/js-ctypes/js-ctypes reference/ctypes#PointerType()"><code>ctypes.PointerType()</code></a> method.</p>
<h3>Declaring a pointer type</h3>
<p>Declaring a pointer type as a pointer to a specific type is done by passing as a parameter to the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#PointerType%28%29" title="en/js-ctypes/js-ctypes reference/ctypes#PointerType()"><code>ctypes.PointerType()</code></a> method a <a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a> object indicating the type to which the pointer should refer:</p>
<pre>const IntPtr = new ctypes.PointerType(ctypes.int);
</pre>
<p>In this example, <code>IntPtr</code> is equivalent to this declaration in C:</p>
<pre>typedef int *intPtr;
</pre>
<p>You can similarly declare a pointer type as a pointer to any user-defined type, including structures:</p>
<pre class="brush: js">const UserRecord = new ctypes.StructType("UserRecord",
                        [{"name": ctypes.char.ptr},
                        {"id": ctypes.int32}]);
const UserRecordPtr = new ctypes.PointerType(UserRecord);
</pre>
<p>In this example, a new <code>UserRecord</code> type is defined, along with a new pointer type that can be used to reference it. The equivalent C code looks like this:</p>
<pre>typedef struct UserRecord {
  char *name;
  int id;    // Assuming int is 32-bit here
} UserRecord;

typedef UserRecordPtr *UserRecord;
</pre>
<h3>Declaring an opaque pointer type</h3>
<p>Declaring an opaque pointer type is done by passing a string, indicating the name of the pointer type, to the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#PointerType%28%29" title="en/js-ctypes/js-ctypes reference/ctypes#PointerType()"><code>ctypes.PointerType()</code></a> method:</p>
<pre>const HANDLE = new ctypes.PointerType("HANDLE");
</pre>
<p>This is equivalent to the following type declaration in C:</p>
<pre>typedef void *HANDLE;
</pre>
Revert to this revision