Your Search Results

    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: jswisher
    Last updated by: jswisher,