ctypes

  • Revision slug: Mozilla/js-ctypes/js-ctypes_reference/ctypes
  • Revision title: ctypes
  • Revision id: 4218
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 51 words added, 3 words removed

Revision Content

{{ gecko_minversion_header("2.0") }}

{{ draft() }}

The ctypes object contains methods and predefined data types used to create and manage a library.

Method overview

CType ArrayType(type[, length]);
CData cast(data, type);
CType FunctionType(abi, returnType[, argType1, ...]);
CData Int64(n);
String libraryName(name);
Library open(libSpec);
CType PointerType(typeSpec);
CType StructType(name[, fields]);
CData UInt64(n);

Constants

ABI constants

These constants are used to specify the ABI used to call a native function in the library.

Constant Description
default_abi Corresponds to cdecl; standard libraries use this ABI. You also use this for all system calls on Mac OS X and Linux.
stdcall_abi Used for calling functions declared with stdcall on Windows. These functions' names are automatically mangled for you by js-ctypes.
winapi_abi Used for calling Windows system functions. These are declared as stdcall on Windows, but do not have mangled names like those used by stdcall_abi above. This has not landed yet; see {{ bug("585175") }}.

Predefined data types

Primitive types

These types behave the same on all platforms.

Type Description
int8_t Signed 8-bit integer.
uint8_t Unsigned 8-bit integer.
int16_t Signed 16-bit integer.
uint16_t Unsigned 16-bit integer.
int32_t Signed 32-bit integer.
uint32_t Unsigned 32-bit integer.
int64_t Signed 64-bit integer.
uint64_t Unsigned 64-bit integer.
float32_t 32-bit floating-point value.
float64_t 64-bit floating-point value.
Note: Some 64-bit values are outside the range of numeric values supported by JavaScript. Because of this, ctypes.int64 and ctypes.uint64 do not automatically convert to JavaScript numbers. Instead, they convert to objects of the wrapper types ctypes.Int64 and ctypes.UInt64, which are JavaScript objects rather than CData objects. See 64-bit integers for details.

Types that act like specific C types

These types are designed to work exactly like the corresponding type on the native platform.

Type Description
bool A Boolean type that behaves like the corresponding C type on the platform.
short A short integer type that behaves like the corresponding C type on the platform.
unsigned_short An unsigned short integer type that behaves like the corresponding C type on the platform.
int An integer type that behaves like the int C type on the platform.
unsigned_int An unsigned integer type that behaves like the unsigned int C type on the platform.
long

A long integer type that behaves like the corresponding C type on the platform.

Note: This automatically converts to an Int64 JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.
unsigned_long

An unsigned long integer type that behaves like the corresponding C type on the platform.

Note: This automatically converts to a UInt64 JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.
long_long
A integer type at least 64 bits wide.
unsigned_long_long
An unsigned integer type at least 64 bits wide.
float A floating point value that behaves like the float type on the platform.
double A double-precision floating point value that behaves like the double type on the platform.

Character types

Character types are 8-bit values that behave like their C counterparts. They're similar to the int8_t and uint8_t types, except conversion is handled differently.

For example, ctypes.char.array(30)(str) converts the string str to UTF-8 and returns a new CData object of array type.

Type Description
char

A character type that behaves like the char C type on the platform.

signed_char A signed character that behaves like the char type on the platform.
unsigned_char An unsigned character that behaves like the unsigned char type on the platform.

Types whose size varies depending on platform

Because it's unknown whether these values will be 32-bit or 64-bit, they are not automatically converted into JavaScript numbers. Instead, these convert into ctypes.Int64 or ctypes.UInt64 JavaScript objects; see 64-bit integers for details.

Type Description
size_t A platform-dependent size type.
ssize_t A platform-dependent size type.
intptr_t A platform-dependent integer representation of a pointer.
uintptr_t A platform-dependent unsigned integer representation of a pointer.

JavaScript characters

16-bit C Unicode characters are handled by js-ctypes using the jschar type.

Type Description
jschar A 16-bit unsigned character. This is different from uint16_t in that C jschar values are automatically converted into 1-character JavaScript strings. These are Unicode characters.

Special C types

These types represent C types that have special meanings.

Type Description
void_t

The special C type void. This can only be used as a return value type.

Note: You must use void_t, not void, since void is a keyword in JavaScript.
voidptr_t The C type void *. This is a pointer to an indeterminate type of data.

Large integer types

Because JavaScript doesn't support large (64-bit) integers, js-ctypes provides two data types allowing access to 64-bit integer data.

Type Description
Int64 A JavaScript object representing a 64-bit signed integer.
UInt64 A JavaScript object representing a 64-bit unsigned integer.

Methods

ArrayType()

Returns a new CType representing an array data type.

CType ArrayType(
  type[,
  length]
);
Parameters
type
The type of the elements in the array type to create.
length
The number of entries the array type should be able to contain. If you don't specify this parameter, the array's length is unspecified.
Return value

A CType representing the newly declared array type.

Exceptions thrown
TypeError
type is not a CType, or type.size is undefined. If length is specified but is not a valid array length, this can also be thrown.
RangeError
The size of the resulting array can't be represented as both a size_t and as a JavaScript number.

cast()

Casts the specified CData object to a new type, returning a new CData object representing the value in the new type. See Type casting for details.

CData cast(
  data,
  type
);
Parameters
data
The CData object to type cast.
type
The type to which to cast the value. This can be one of the Predefined data types, or any user-defined types.
Return value

A new CData object representing the same data, but with the specified type.

FunctionType()

Returns a new CType object describing a C function.

CType FunctionType(
  abi,
  returnType[,
  argType1, ...]
);
Parameters
abi
The ABI type for the function; this is one of the ABI constants.
returnType
CType indicating the type of the value returned by the function.
argType1... argTypeN
Zero or more CType objects indicating the types of each of the parameters passed into the C function.
Return value

A CType describing the function type. The equivalent C function type declaration would be:

returnType (*) ([argType1, ..., argTypeN]);
Exceptions thrown
TypeError
ABI is not a valid ABI type, or returnType or any of the argument types are not valid CType objects.

libraryName()

Returns the correct platform-specific filename for a given library name (e.g. libnss3.dylib for nss3 on OS X.)

String libraryName(
  name
);
Parameters
name
The name of the library.
Return value

String containing the platform-specific filename of the library.

open()

Opens a library, which may be specified either by pathname or {{ interface("nsILocalFile") }}. The library is loaded from the specified full path, or, if a partial path is specified, from the appropriate library directory based on the platform on which the application is running. See Library search paths for more details.

Library open(
  libSpec
);
Parameters
libSpec
The native library to open, specified as either a pathname string or an {{ interface("nsILocalFile") }}.
Return value

A Library object representing the opened library.

PointerType()

Returns a CType object describing a new pointer data type.

CType PointerType(
  typeSpec
);
Parameters
typeSpec
Specifies the type to which the pointer type points. This can be any CType object to declare the new type as a pointer to that type. To create an opaque pointer type, pass a string to use as the opaque type's name.
Return value

A CType object describing the newly created data type.

Exceptions thrown
TypeError
Thrown if the parameter isn't either a string or a CType.
Examples

Creating a type "pointer to 32-bit integer" looks like this:

var intPtrType = new ctypes.PointerType(ctypes.int32_t);

Creating an opaque pointer type is also easy; for example, this creates an opaque type we can use to represent a CFStringRef on Mac OS X:

var CFStringRef = new ctypes.PointerType("CFStringRef");

StructType()

Returns a CType object describing a new structure data type. This data type provides the ability to define and manipulate values of the C struct type.

Note: At this time, there isn't a way to denote a packed structure (that is, one created in C using #pragma pack).
CType StructType(
  name[,
  fields]
);
Parameters
name
The name of the structure. Must be a string.
fields {{ optional_inline() }}
An array of field descriptors, describing all the entries in the structure. If this isn't specified, the structure is considered opaque and you can't access its contents directly. You can call the resulting type's define() method to assign it a non-opaque type later.
Return value

A CType object describing the newly created struct data type.

Exceptions thrown
TypeError
The name is not a string, or one or more of the fields does not have a defined size.
RangeError
The size of the structure, in bytes, cannot be represented both as a size_t and as a JavaScript Number.
Describing fields

The fields array is comprised of field descriptors, one for each field in the structure. Each field descriptor contains the field's name and its type, such as {'serialNumber': ctypes.int}. A complete field descriptor list might look like this:

[ {'serialNumer': ctypes.int}, {'userName': ctypes.char.ptr} ]

See also

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p>{{ draft() }}</p>
<p>The <code>ctypes</code> object contains methods and predefined data types used to create and manage a library.</p>
<h2>Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>CType <a href="/en/js-ctypes/js-ctypes_reference/ctypes#ArrayType()" title="en/js-ctypes/js-ctypes reference/ctypes#ArrayType()">ArrayType</a>(type[, length]);</code></td> </tr> <tr> <td><code>CData <a href="/en/js-ctypes/js-ctypes_reference/ctypes#cast%28%29" title="en/js-ctypes/js-ctypes reference/ctypes#cast()">cast</a>(data, type);</code></td> </tr> <tr> <td><code>CType <a href="/en/js-ctypes/js-ctypes_reference/ctypes#FunctionType()" title="en/js-ctypes/js-ctypes reference/ctypes#FunctionType()">FunctionType</a>(abi, returnType[, argType1, ...]);</code></td> </tr> <tr> <td><code>CData <a href="/en/js-ctypes/js-ctypes_reference/ctypes#Int64()" title="en/js-ctypes/js-ctypes reference/ctypes#Int64()">Int64</a>(n);</code></td> </tr> <tr> <td><code>String <a href="/en/js-ctypes/js-ctypes_reference/ctypes#libraryName%28%29" title="en/js-ctypes/js-ctypes reference/ctypes#libraryName()">libraryName</a>(name);</code></td> </tr> <tr> <td><code>Library <a href="/en/js-ctypes/js-ctypes_reference/ctypes#open%28%29" title="en/js-ctypes/js-ctypes reference/ctypes#open()">open</a>(libSpec);</code></td> </tr> <tr> <td><code>CType <a href="/en/js-ctypes/js-ctypes_reference/ctypes#PointerType()" title="en/js-ctypes/js-ctypes reference/ctypes#PointerType()">PointerType</a>(typeSpec);</code></td> </tr> <tr> <td><code>CType <a href="/en/js-ctypes/js-ctypes_reference/ctypes#StructType()" title="en/js-ctypes/js-ctypes reference/ctypes#StructType()">StructType</a>(name[, fields]);</code></td> </tr> <tr> <td><code>CData <a href="/en/js-ctypes/js-ctypes_reference/ctypes#UInt64()" title="en/js-ctypes/js-ctypes reference/ctypes#UInt64()">UInt64</a>(n);</code></td> </tr> </tbody>
</table>
<h2>Constants</h2>
<h3>ABI constants</h3>
<p>These constants are used to specify the ABI used to call a native function in the library.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td><code>default_abi</code></td> <td>Corresponds to <code>cdecl</code>; standard libraries use this ABI. You also use this for all system calls on Mac OS X and Linux.</td> </tr> <tr> <td><code>stdcall_abi</code></td> <td>Used for calling functions declared with <code>stdcall</code> on Windows. These functions' names are automatically mangled for you by js-ctypes.</td> </tr> <tr> <td><code>winapi_abi</code></td> <td>Used for calling Windows system functions. These are declared as stdcall on Windows, but do not have mangled names like those used by <code>stdcall_abi</code> above. <strong>This has not landed yet; see {{ bug("585175") }}.</strong></td> </tr> </tbody>
</table>
<h2>Predefined data types</h2>
<h4>Primitive types</h4>
<p>These types behave the same on all platforms.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>int8_t</code></td> <td>Signed 8-bit integer.</td> </tr> <tr> <td><code>uint8_t</code></td> <td>Unsigned 8-bit integer.</td> </tr> <tr> <td><code>int16_t</code></td> <td>Signed 16-bit integer.</td> </tr> <tr> <td><code>uint16_t</code></td> <td>Unsigned 16-bit integer.</td> </tr> <tr> <td><code>int32_t</code></td> <td>Signed 32-bit integer.</td> </tr> <tr> <td><code>uint32_t</code></td> <td>Unsigned 32-bit integer.</td> </tr> <tr> <td><code>int64_t</code></td> <td>Signed 64-bit integer.</td> </tr> <tr> <td><code>uint64_t</code></td> <td>Unsigned 64-bit integer.</td> </tr> <tr> <td><code>float32_t</code></td> <td>32-bit floating-point value.</td> </tr> <tr> <td><code>float64_t</code></td> <td>64-bit floating-point value.</td> </tr> </tbody>
</table>
<div class="note"><strong>Note:</strong> Some 64-bit values are outside the range of numeric values supported by JavaScript. Because of this, <code>ctypes.int64</code> and <code>ctypes.uint64</code> do not automatically convert to JavaScript numbers. Instead, they convert to objects of the wrapper types <code>ctypes.Int64</code> and <code>ctypes.UInt64</code>, which are JavaScript objects rather than CData objects. See <a href="/en/js-ctypes/Using_js-ctypes/Working_with_data#64-bit_integers" title="en/js-ctypes/Using js-ctypes/Working with data#64-bit integers">64-bit integers</a> for details.</div>
<h4>Types that act like specific C types</h4>
<p>These types are designed to work exactly like the corresponding type on the native platform.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>bool</code></td> <td>A Boolean type that behaves like the corresponding C type on the platform.</td> </tr> <tr> <td><code>short</code></td> <td>A short integer type that behaves like the corresponding C type on the platform.</td> </tr> <tr> <td><code>unsigned_short</code></td> <td>An unsigned short integer type that behaves like the corresponding C type on the platform.</td> </tr> <tr> <td><code>int</code></td> <td>An integer type that behaves like the <code>int</code> C type on the platform.</td> </tr> <tr> <td><code>unsigned_int</code></td> <td>An unsigned integer type that behaves like the <code>unsigned int</code> C type on the platform.</td> </tr> <tr> <td><code>long</code></td> <td> <p>A long integer type that behaves like the corresponding C type on the platform.</p> <div class="note"><strong>Note:</strong> This automatically converts to an <code>Int64</code> JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.</div> </td> </tr> <tr> <td><code>unsigned_long</code></td> <td> <p>An unsigned long integer type that behaves like the corresponding C type on the platform.</p> <div class="note"><strong>Note:</strong> This automatically converts to a <code>UInt64</code> JavaScript object on all platforms, since it's unknown whether this is a 32-bit or 64-bit value. This is done for compatibility's sake.</div> </td> </tr> <tr> <td><code>long_long<br> </code></td> <td>A integer type at least 64 bits wide.</td> </tr> <tr> <td><code>unsigned_long_long<br> </code></td> <td>An unsigned integer type at least 64 bits wide.</td> </tr> <tr> <td><code>float</code></td> <td>A floating point value that behaves like the <code>float</code> type on the platform.</td> </tr> <tr> <td><code>double</code></td> <td>A double-precision floating point value that behaves like the <code>double</code> type on the platform.</td> </tr> </tbody>
</table>
<h4>Character types</h4>
<p>Character types are 8-bit values that behave like their C counterparts. They're similar to the <code>int8_t</code> and <code>uint8_t</code> types, except conversion is handled differently.</p>
<p>For example, <code>ctypes.char.array(30)(str)</code> converts the string <code>str</code> to UTF-8 and returns a new <code>CData</code> object of array type.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>char</code></td> <td> <p>A character type that behaves like the <code>char</code> C type on the platform.</p> </td> </tr> <tr> <td><code>signed_char</code></td> <td>A signed character that behaves like the <code>char</code> type on the platform.</td> </tr> <tr> <td><code>unsigned_char</code></td> <td>An unsigned character that behaves like the <code>unsigned char</code> type on the platform.</td> </tr> </tbody>
</table>
<h4>Types whose size varies depending on platform</h4>
<p>Because it's unknown whether these values will be 32-bit or 64-bit, they are not automatically converted into JavaScript numbers. Instead, these convert into <code>ctypes.Int64</code> or <code>ctypes.UInt64</code> JavaScript objects; see <a href="/en/js-ctypes/Using_js-ctypes/Working_with_data#64-bit_integers" title="en/js-ctypes/Using js-ctypes/Working with data#64-bit integers">64-bit integers</a> for details.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>size_t</code></td> <td>A platform-dependent size type.</td> </tr> <tr> <td><code>ssize_t</code></td> <td>A platform-dependent size type.</td> </tr> <tr> <td><code>intptr_t</code></td> <td>A platform-dependent integer representation of a pointer.</td> </tr> <tr> <td><code>uintptr_t</code></td> <td>A platform-dependent unsigned integer representation of a pointer.</td> </tr> </tbody>
</table>
<h4>JavaScript characters</h4>
<p>16-bit C Unicode characters are handled by js-ctypes using the <code>jschar</code> type.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>jschar</code></td> <td>A 16-bit unsigned character. This is different from <code>uint16_t</code> in that C <code>jschar</code> values are automatically converted into 1-character JavaScript strings. These are Unicode characters.</td> </tr> </tbody>
</table>
<h4>Special C types</h4>
<p>These types represent C types that have special meanings.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>void_t</code></td> <td> <p>The special C type <code>void</code>. This can only be used as a return value type.</p> <div class="note"><strong>Note:</strong> You must use <code>void_t</code>, not <code>void</code>, since <code>void</code> is a keyword in JavaScript.</div> </td> </tr> <tr> <td><code>voidptr_t</code></td> <td>The C type <code>void *</code>. This is a pointer to an indeterminate type of data.</td> </tr> </tbody>
</table>
<h4>Large integer types</h4>
<p>Because JavaScript doesn't support large (64-bit) integers, js-ctypes provides two data types allowing access to 64-bit integer data.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>Int64</code></td> <td>A JavaScript object representing a 64-bit signed integer.</td> </tr> <tr> <td><code>UInt64</code></td> <td>A JavaScript object representing a 64-bit unsigned integer.</td> </tr> </tbody>
</table>
<h2>Methods</h2>
<h3>ArrayType()</h3>
<p>Returns a new <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> representing an array data type.</p>
<pre>CType ArrayType(
  type[,
  length]
);
</pre>
<h6>Parameters</h6>
<dl> <dt>type</dt> <dd>The type of the elements in the array type to create.</dd> <dt>length</dt> <dd>The number of entries the array type should be able to contain. If you don't specify this parameter, the array's length is unspecified.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> representing the newly declared array type.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd><code>type</code> is not a <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a>, or <code>type.size</code> is undefined. If <code>length</code> is specified but is not a valid array length, this can also be thrown.</dd> <dt><code>RangeError</code></dt> <dd>The size of the resulting array can't be represented as both a <code>size_t</code> and as a JavaScript number.</dd>
</dl>
<h3 name="cast()">cast()</h3>
<p>Casts the specified <a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData"><code>CData</code></a> object to a new type, returning a new <a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData"><code>CData</code></a> object representing the value in the new type. See <a href="/en/js-ctypes/Using_js-ctypes/Working_with_data#Type_casting" title="en/js-ctypes/Using js-ctypes/Working with data#Type casting">Type casting</a> for details.</p>
<pre>CData cast(
  data,
  type
);</pre>
<h6>Parameters</h6>
<dl> <dt><code>data</code></dt> <dd>The <a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData"><code>CData</code></a> object to type cast.</dd> <dt><code>type</code></dt> <dd>The type to which to cast the value. This can be one of the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#Predefined_data_types" title="en/js-ctypes/js-ctypes reference/ctypes#Predefined data types">Predefined data types</a>, or any user-defined types.</dd>
</dl>
<h6>Return value</h6>
<p>A new <code>CData</code> object representing the same data, but with the specified type.</p>
<h3>FunctionType()</h3>
<p>Returns a new <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> object describing a C function.</p>
<pre>CType FunctionType(
  abi,
  returnType[,
  argType1, ...]
);
</pre>
<h6>Parameters</h6>
<dl> <dt>abi</dt> <dd>The ABI type for the function; this is one of the <a href="/en/js-ctypes/js-ctypes_reference/ctypes#ABI_constants" title="en/js-ctypes/js-ctypes reference/ctypes#ABI constants">ABI constants</a>.</dd> <dt>returnType</dt> <dd>A <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> indicating the type of the value returned by the function.</dd> <dt>argType1... argTypeN</dt> <dd>Zero or more <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> objects indicating the types of each of the parameters passed into the C function.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> describing the function type. The equivalent C function type declaration would be:</p>
<pre>returnType (*) ([argType1, ..., argTypeN]);
</pre>
<h6>Exceptions thrown</h6>
<dl> <dt>TypeError</dt> <dd>ABI is not a valid <a href="/en/js-ctypes/js-ctypes_reference/ctypes#ABI_constants" title="en/js-ctypes/js-ctypes reference/ctypes#ABI constants">ABI type</a>, or <code>returnType</code> or any of the argument types are not valid <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> objects.</dd>
</dl>
<h3 name="libraryName()">libraryName()</h3>
<p>Returns the correct platform-specific filename for a given library name (e.g. <code>libnss3.dylib</code> for <code>nss3</code> on OS X.)</p>
<pre class="eval">String libraryName(
  name
);
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>name</code></dt> <dd>The name of the library.</dd>
</dl>
<h6>Return value</h6>
<p>String containing the platform-specific filename of the library.</p>
<h3 name="open()">open()</h3>
<p>Opens a library, which may be specified either by pathname or {{ interface("nsILocalFile") }}. The library is loaded from the specified full path, or, if a partial path is specified, from the appropriate library directory based on the platform on which the application is running. See <a href="/en/js-ctypes/Using_js-ctypes#Library_search_paths" title="en/js-ctypes/Using js-ctypes#Library search paths">Library search paths</a> for more details.</p>
<pre class="eval">Library open(
  libSpec
);
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>libSpec</code></dt> <dd>The native library to open, specified as either a pathname string or an {{ interface("nsILocalFile") }}.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/js-ctypes/js-ctypes_reference/Library" title="en/js-ctypes/js-ctypes reference/Library"><code>Library</code></a> object representing the opened library.</p>
<h3>PointerType()</h3>
<p>Returns a <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> object describing a new pointer data type.</p>
<pre>CType PointerType(
  typeSpec
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>typeSpec</code></dt> <dd>Specifies the type to which the pointer type points. This can be any <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> object to declare the new type as a pointer to that type. To create an opaque pointer type, pass a string to use as the opaque type's name.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> object describing the newly created data type.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd>Thrown if the parameter isn't either a string or a <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a>.</dd>
</dl>
<h6>Examples</h6>
<p>Creating a type "pointer to 32-bit integer" looks like this:</p>
<pre>var intPtrType = new ctypes.PointerType(ctypes.int32_t);
</pre>
<p>Creating an opaque pointer type is also easy; for example, this creates an opaque type we can use to represent a CFStringRef on Mac OS X:</p>
<pre>var CFStringRef = new ctypes.PointerType("CFStringRef");
</pre>
<h3>StructType()</h3>
<p>Returns a <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> object describing a new structure data type. This data type provides the ability to define and manipulate values of the C <code>struct</code> type.</p>
<div class="note"><strong>Note:</strong> At this time, there isn't a way to denote a packed structure (that is, one created in C using <code>#pragma pack</code>).</div>
<pre>CType StructType(
  name[,
  fields]
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>name</code></dt> <dd>The name of the structure. Must be a string.</dd> <dt><code>fields</code> {{ optional_inline() }}</dt> <dd>An array of field descriptors, describing all the entries in the structure. If this isn't specified, the structure is considered opaque and you can't access its contents directly. You can call the resulting type's <code>define()</code> method to assign it a non-opaque type later.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/js-ctypes/js-ctypes_reference/CType" title="https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/CType"><code>CType</code></a> object describing the newly created <code>struct</code> data type.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd>The name is not a string, or one or more of the fields does not have a defined size.</dd> <dt><code>RangeError</code></dt> <dd>The size of the structure, in bytes, cannot be represented both as a <code>size_t</code> and as a JavaScript Number.</dd>
</dl>
<h6>Describing fields</h6>
<p>The <code>fields</code> array is comprised of field descriptors, one for each field in the structure. Each field descriptor contains the field's name and its type, such as <code>{'serialNumber': ctypes.int}</code>. A complete field descriptor list might look like this:</p>
<pre>[ {'serialNumer': ctypes.int}, {'userName': ctypes.char.ptr} ]
</pre>
<h2>See also</h2>
<ul> <li><a href="/en/JavaScript/Code_modules/ctypes.jsm" title="en/JavaScript code modules/ctypes.jsm">ctypes.jsm</a></li> <li><a href="/en/js-ctypes/Using_js-ctypes" title="en/js-ctypes/Using js-ctypes">Using js-ctypes</a></li>
</ul>
Revert to this revision