CData

Draft
This page is not complete.

A 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 pointer objects

bool isNull()

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, as a CType. 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 pointer objects

isNull()

Determines whether or not the pointer's value is null.

bool isNull();
Parameters

None.

Return value

true if the pointer's value is null, otherwise false.

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. See Working with strings for more information on how to convert strings.

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.

If the 8-bit string contains invalid encoded character, a TypeError exception is thrown.

String readString();
Parameters

None.

Return value

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

readStringReplaceMalformed()

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

If the 8-bit string contains invalid encoded character, no exception is thrown.

String readStringReplaceMalformed();
Parameters

None.

Return value

A new String object that is a copy of the original string contents. Invalid encoded characters will be replaced by �(U+FFFD).

See also

Document Tags and Contributors

Contributors to this page: Sheppy, MattBrubeck, ethertank, chucklee, kscarfone
Last updated by: ethertank,