CData

  • Revision slug: Mozilla/js-ctypes/js-ctypes_reference/CData
  • Revision title: CData
  • Revision id: 109749
  • Created:
  • Creator: MattBrubeck
  • Is current revision? No
  • Comment formatting; one or more formatting changes

Revision Content

{{ gecko_minversion_header("1.9.3") }}

{{ draft() }}

CData object represents a C value or function located in memory.

Method overview

Methods available on all CData objects

CData address()
String toSource()
String toString()

Methods available on struct objects

CData addressOfField(name)

Methods available on array objects

CData addressOfElement(name)

Methods available on string objects

CData readString(name)

Properties

Properties of all CData objects

Property Type Description
constructor CType

The data type of the CData object. Read only.

Note: This is never ctypes.void_t or an array type with an unspecified length.
value object The JavaScript equivalent of the CData object's value. This will throw a TypeError exception if the value can't be converted.

Properties of struct objects

Every struct object has a getter and a setter for each member field of the structure.

Properties of pointer objects

Property Type Description
contents CData Reading this property returns a CData object referring to the pointed-to contents of the object. Writing to this value writes the C conversion of the data into the pointed-to memory. If converting the data fails, a TypeError exception is thrown.

Properties of array objects

Property Type Description
length Number The length of the array. Read only.

In addition, each element in the array can be referenced by index using standard bracket notation, such as myArray[index].

Methods available on all CData objects

address()

Returns a CData object of the pointer type ctypes.PointerType(dataObject.constructor) whose value points to the C object referred to by the object. This provides a way to get a pointer to the actual data of the C value represented by the CData object.

CData address()
Parameters

None.

Return value

A CData object of the pointer type ctypes.PointerType(dataObject.constructor) whose value points to the C object referred to by the object.

toSource()

Returns the string "t(arg)", where t and arg are implementation-defined JavaScript expressions intended to represent type type of the CData object and its value, respectively.

String toSource()
Parameters

None.

Return value

A string that, ideally, should be able to be evaluated to produce a new CData object containing a copy of the original object. However, this only works if the object's type happens to be bound to an appropriate name in scope.

In theory, in other words, the following JavaScript expression should return a copy of the original CData object:

eval(dataObject.toSource());

Methods available on struct objects

addressOfField()

Returns a new CData object of the appropriate pointer type, whose value points to the specified field of the structure on which the method was called.

CData addressOfField(
  name
); 
Parameters
name
The name of the field whose address is to be returned.
Return value

A new CData object of the appropriate pointer type, whose value points to the contents of the specified field.

Exceptions thrown
TypeError
name is not a JavaScript string, or doesn't name a member field of the structure.

Methods available on array objects

addressOfElement()

Returns a new CData object of the appropriate pointer type, whose value points to the specified array element on which the method was called.

CData addressOfElement(
  idx
);
Parameters
idx
A numeric value indicating the offset into the array of the element for which to return a pointer. If this value isn't a valid JavaScript number that's also a valid index into the array, a TypeError exception is thrown.
Return value

A new CData object pointing to the specified element.

Note: The type of the returned object will be determined by ctypes.PointerType(theArrayType.constructor.elementType)).

Methods available on string objects

These methods must be called on objects that are arrays or pointers to 8-bit or 16-bit character or integer types, terminated by a null character.

readString()

Converts a character array to a JavaScript string.  8-bit strings are assumed to be encoded as UTF-8.

String readString();
Parameters

None.

Return value

A new String object that is a copy of the original string contents.

See also

Revision Source

<p>{{ gecko_minversion_header("1.9.3") }}</p>
<p>{{ draft() }}</p>
<p>A <code>CData</code> object represents a C value or function located in memory.</p>
<h2>Method overview</h2>
<h3>Methods available on all CData objects</h3>
<table class="standard-table"> <tbody> <tr> <td><span style="font-family: monospace;">CData <a href="/en/js-ctypes/js-ctypes_reference/CData#address()" title="en/js-ctypes/js-ctypes reference/CData#address()">address</a>()</span><code><br> </code></td> </tr> <tr> <td><code>String <a href="/en/js-ctypes/js-ctypes_reference/CData#toSource()" title="en/js-ctypes/js-ctypes reference/CData#toSource()">toSource</a>()<br> </code></td> </tr> <tr> <td><code>String <a href="/en/js-ctypes/js-ctypes_reference/CData#toString()" title="en/js-ctypes/js-ctypes reference/CData#toString()">toString</a>()<br> </code></td> </tr> </tbody>
</table>
<h3>Methods available on struct objects</h3>
<table class="standard-table"> <tbody> <tr> <td><span style="font-family: monospace;">CData <a href="/en/js-ctypes/js-ctypes_reference/CData#addressOfField()" title="en/js-ctypes/js-ctypes reference/CData#addressOfField()">addressOfField</a>(name)</span><code><br> </code></td> </tr> </tbody>
</table>
<h3>Methods available on array objects</h3>
<p><span style="font-family: monospace;">CData <a href="/en/js-ctypes/js-ctypes_reference/CData#addressOfElement()" title="en/js-ctypes/js-ctypes reference/CData#addressOfElement()">addressOfElement</a>(name)</span></p>
<h3>Methods available on string objects</h3>
<p><span style="font-family: monospace;">CData <a href="/en/js-ctypes/js-ctypes_reference/CData#readString()" title="en/js-ctypes/js-ctypes reference/CData#readString()">readString</a>(name)</span></p>
<h2>Properties</h2>
<h3>Properties of all CData objects</h3>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Property</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>constructor</code></td> <td><a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a></td> <td> <p>The data type of the <code>CData</code> object. <strong>Read only.</strong></p> <div class="note"><strong>Note:</strong> This is never <code>ctypes.void_t</code> or an array type with an unspecified length.</div> </td> </tr> <tr> <td><code>value</code></td> <td>object</td> <td>The JavaScript equivalent of the <code>CData</code> object's value. This will throw a <code>TypeError</code> exception if the value can't be converted.</td> </tr> </tbody>
</table>
<h3>Properties of struct objects</h3>
<p>Every struct object has a getter and a setter for each member field of the structure.</p>
<h3>Properties of pointer objects</h3>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Property</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>contents</code></td> <td><code>CData</code></td> <td>Reading this property returns a <code>CData</code> object referring to the pointed-to contents of the object. Writing to this value writes the C conversion of the data into the pointed-to memory. If converting the data fails, a <code>TypeError</code> exception is thrown.</td> </tr> </tbody>
</table>
<h3>Properties of array objects</h3>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Property</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>length</code></td> <td><a href="/en/Core_JavaScript_1.5_Reference/Global_Objects/Number" title="en/Core JavaScript 1.5 Reference/Global Objects/Number"><code>Number</code></a></td> <td>The length of the array. <strong>Read only.</strong></td> </tr> </tbody>
</table>
<p>In addition, each element in the array can be referenced by index using standard bracket notation, such as <code>myArray[<em>index</em>]</code>.</p>
<h2>Methods available on all CData objects</h2>
<h3>address()</h3>
<p>Returns a <code>CData</code> object of the pointer type <code>ctypes.PointerType(<em>dataObject</em>.constructor)</code> whose value points to the C object referred to by the object. This provides a way to get a pointer to the actual data of the C value represented by the <code>CData</code> object.</p>
<pre>CData address()
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>A <code>CData</code> object of the pointer type <code>ctypes.PointerType(<em>dataObject</em>.constructor)</code> whose value points to the C object referred to by the object.</p>
<h3>toSource()</h3>
<p>Returns the string "<em>t</em>(<em>arg</em>)", where <em>t</em> and <em>arg</em> are implementation-defined JavaScript expressions intended to represent type type of the CData object and its value, respectively.</p>
<pre>String toSource()
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>A string that, ideally, should be able to be evaluated to produce a new <code>CData</code> object containing a copy of the original object. However, this only works if the object's type happens to be bound to an appropriate name in scope.</p>
<p>In theory, in other words, the following JavaScript expression should return a copy of the original <code>CData</code> object:</p>
<pre class="brush: js">eval(dataObject.toSource());
</pre>
<h2>Methods available on struct objects</h2>
<h3>addressOfField()</h3>
<p>Returns a new <code>CData</code> object of the appropriate pointer type, whose value points to the specified field of the structure on which the method was called.</p>
<pre>CData addressOfField(
  name
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>name</code></dt> <dd>The name of the field whose address is to be returned.</dd>
</dl>
<h6>Return value</h6>
<p>A new <code>CData</code> object of the appropriate pointer type, whose value points to the contents of the specified field.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd><code>name</code> is not a JavaScript string, or doesn't name a member field of the structure.</dd>
</dl>
<h2>Methods available on array objects</h2>
<h3>addressOfElement()</h3>
<p>Returns a new <code>CData</code> object of the appropriate pointer type, whose value points to the specified array element on which the method was called.</p>
<pre>CData addressOfElement(
  idx
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>idx</code></dt> <dd>A numeric value indicating the offset into the array of the element for which to return a pointer. If this value isn't a valid JavaScript number that's also a valid index into the array, a <code>TypeError</code> exception is thrown.</dd>
</dl>
<h6>Return value</h6>
<p>A new <code>CData</code> object pointing to the specified element.</p>
<div class="note"><strong>Note:</strong> The type of the returned object will be determined by <code>ctypes.PointerType(<em>theArrayType</em>.constructor.elementType))</code>.</div>
<h2>Methods available on string objects</h2>
<p>These methods must be called on objects that are arrays or pointers to 8-bit or 16-bit character or integer types, terminated by a null character.</p>
<h3>readString()</h3>
<p>Converts a character array to a JavaScript string.  8-bit strings are assumed to be encoded as UTF-8.</p>
<pre>String readString();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>A new <code>String</code> object that is a copy of the original string contents.</p>
<h2>See also</h2>
<ul> <li><a href="/en/js-ctypes/Using_js-ctypes/Working_with_data" title="en/js-ctypes/Using js-ctypes/Working with data">Working with data</a></li>
</ul>
Revert to this revision