mozilla

Revision 109343 of Library

  • Revision slug: Mozilla/js-ctypes/js-ctypes_reference/Library
  • Revision title: Library
  • Revision id: 109343
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 290 words added, 264 words removed

Revision Content

{{ gecko_minversion_header("1.9.3") }}

{{ draft() }}

Method overview

close();
obj declare(name, abi, returnType[, argType1, ...]);

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.
stdcall_abi Used for calling Windows API functions.

Primitive types

These constants define the primitive data types that behave the same on all platforms.

Constant 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.

Types that act like specific C types

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

Constant 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 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.
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 type constants

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.

Constant 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.
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 integer objects for details.

Types whose size varies depending on platform

size_t A platform-dependent size type. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.
ssize_t A platform-dependent size type. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.
intptr_t A platform-dependent integer representation of a pointer. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.
uintptr_t A platform-dependent unsigned integer representation of a pointer. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.

Methods

close()

Closes the library. You need to call this once you're done using the library.

close();
Parameters

None.

declare()

Declares an API from the native library, allowing it to be used from JavaScript. This can be used both for exported data symbols and for functions.

obj declare(
  name,
  abi,
  returnType[
  argType1,
  ...]
);
Parameters
name
The name of the symbol exported by the native library that is to be declared as usable from JavaScript
abi
The ABI used by the exported function; this will be ctypes.default_abi for most libraries, except for Windows system libraries, which will be ctypes.stdcall_abi.
returnType
The data type returned by the defined API, if it's a function. This parameter should not be provided if the API is an exported data symbol.
argType1...argTypeN
Zero or more parameter types may be specified for the parameters of the function being declared. These should not be provided if the API is an exported data symbol rather than a function.
Return value

A CData object representing the declared API.

Exceptions thrown
TypeError
The return type was specified as an array.

Revision Source

<p>{{ gecko_minversion_header("1.9.3") }}</p>
<p>{{ draft() }}</p>
<h2>Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>close();</code></td> </tr> <tr> <td><code>obj declare(name, abi, returnType[, argType1, ...])</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.</td> </tr> <tr> <td><code>stdcall_abi</code></td> <td>Used for calling Windows API functions.</td> </tr> </tbody>
</table>
<h3>Primitive types</h3>
<p>These constants define the primitive data types that behave the same on all platforms.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Description</td> </tr> <tr> <td>int8_t</td> <td>Signed 8-bit integer.</td> </tr> <tr> <td>uint8_t</td> <td>Unsigned 8-bit integer.</td> </tr> <tr> <td>int16_t</td> <td>Signed 16-bit integer.</td> </tr> <tr> <td>uint16_t</td> <td>Unsigned 16-bit integer.</td> </tr> <tr> <td>int32_t</td> <td>Signed 32-bit integer.</td> </tr> <tr> <td>uint32_t</td> <td>Unsigned 32-bit integer.</td> </tr> <tr> <td>int64_t</td> <td>Signed 64-bit integer.</td> </tr> <tr> <td>uint64_t</td> <td>Unsigned 64-bit integer.</td> </tr> <tr> <td>float32_t</td> <td>32-bit floating-point value.</td> </tr> <tr> <td>float64_t</td> <td>64-bit floating-point value.</td> </tr> </tbody>
</table>
<h3>Types that act like specific C types</h3>
<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">Constant</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 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.</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 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.</div> </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>
<h3>Character type constants</h3>
<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">Constant</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>
<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 64-bit integer objects for details.</div>
<h3>Types whose size varies depending on platform</h3>
<table class="standard-table"> <tbody> <tr> <td>size_t</td> <td>A platform-dependent size type. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.</td> </tr> <tr> <td>ssize_t</td> <td>A platform-dependent size type. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.</td> </tr> <tr> <td>intptr_t</td> <td>A platform-dependent integer representation of a pointer. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.</td> </tr> <tr> <td>uintptr_t</td> <td>A platform-dependent unsigned integer representation of a pointer. Because it's unknown whether this is a 32-bit or 64-bit value, it does not automatically convert to a JavaScript number, but instead converts to a JavaScript wrapper object, even on 32-bit platforms. See 64-bit integer objects for details.</td> </tr>  </tbody>
</table>
<h2>Methods</h2>
<h3 name="eatCookie.28.29">close()</h3>
<p>Closes the library. You need to call this once you're done using the library.</p>
<pre class="eval">close();
</pre>
<h6 name="Parameters">Parameters</h6>
<p>None.</p>
<h3 name="eatCookie.28.29">declare()</h3>
<p>Declares an API from the native library, allowing it to be used from JavaScript. This can be used both for exported data symbols and for functions.</p>
<pre class="eval">obj declare(
  name,
  abi,
  returnType[
  argType1,
  ...]
);
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>name</code></dt> <dd>The name of the symbol exported by the native library that is to be declared as usable from JavaScript</dd> <dt><code>abi</code></dt> <dd>The ABI used by the exported function; this will be <code>ctypes.default_abi</code> for most libraries, except for Windows system libraries, which will be <code>ctypes.stdcall_abi</code>.</dd> <dt><code>returnType</code></dt> <dd>The data type returned by the defined API, if it's a function. This parameter should not be provided if the API is an exported data symbol.</dd> <dt><code>argType1...argTypeN</code></dt> <dd>Zero or more parameter types may be specified for the parameters of the function being declared. These should not be provided if the API is an exported data symbol rather than a function.</dd>
</dl>
<h6>Return value</h6>
<p>A CData object representing the declared API.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd>The return type was specified as an array.</dd>
</dl>
Revert to this revision