Jsctypes/api: Difference between revisions

<code>Library</code> objects have the following methods:

:If ''rtype'' is an array type, this throws a <code>TypeError</code>.

:If any ''argtypeN'' is an array type, the result is the same as if it had been the corresponding pointer type, <code>''argtypeN''.elementType.ptr</code>.  ''(Rationale: This is how C and C++ treat array types in function declarations.)''

= Types =

:''(<code>ctypes.long</code> and <code>ctypes.unsigned_long</code> autoconvert to 64-bit integer objects on all platforms. The rest autoconvert to JavaScript numbers. Rationale: Some platforms have 64-bit <code>long</code> and some do not.)''

:'''<code>ctypes.void_t</code>''' - The special C type <code>void</code>. This can be used as a return value type.  (<code>void</code> is a keyword in JavaScript.)

:'''<code>new ctypes.PointerType(''t'')</code>''' - If ''t'' is a <code>CType</code>, return the type "pointer to ''t''". The result is cached so that future requests for this pointer type produce the same <code>CType</code> object. If ''t'' is a string, instead return a new opaque pointer type named ''t''. Otherwise throw a <code>TypeError</code>.

:'''<code>new ctypes.ArrayType(''t'')</code>''' - Return an array type with unspecified length and element type ''t''.  If ''t'' is not a type or <code>''t''.size</code> is <code>undefined</code>, throw a <code>TypeError</code>.

  const HANDLE = new ctypes.PointerType("HANDLE");

  const HANDLES = new ctypes.ArrayType(HANDLE);

  const IOBuf = new ctypes.ArrayType(ctypes.uint8_t, 4096);

   

  const struct_tm = new ctypes.StructType('tm', [{'tm_sec': ctypes.int}, ...]);

== Properties of types ==

:For primitive types this is just the name of the corresponding C/C++ type.

:''(Open issue: This conflicts with the usual meaning of .name for functions, and types are callable like functions.)''

  ctypes.void_t.name

   ===> "void"

   

  FILE.name

   

  struct_tm.name

   ===> "tm"

   

  const Point = new ctypes.StructType(

  Point.toSource()

Pointer types also have:

:'''<code>''t''.targetType</code>''' - Read-only. The pointed-to type, or <code>null</code> if ''t'' is an opaque pointer type.

Struct types also have:

:Every <code>CType</code> has a read-only, permanent <code>.prototype</code> property.  The type-constructors <code>ctypes.{C,Pointer,Struct,Array}Type</code> each have a read-only, permanent <code>.prototype</code> property as well.

== Calling types ==

::* If ''val'' is a size value (defined above): Let ''u'' = <code>ArrayType(''t''.elementType, ''val'')</code> and return <code>new ''u''</code>.

::* If <code>''t''.elementType</code> is an 8-bit character type and ''val'' is a string: If ''val'' is not a well-formed UTF-16 string, throw a <code>TypeError</code>. Otherwise, let ''s'' = a sequence of bytes, the result of converting ''val'' from UTF-16 to UTF-8, and let ''n'' = the number of bytes in ''s''. Return a new <code>CData</code> object of type <code>ArrayType(''t''.elementType, ''n'' + 1)</code> containing the bytes in ''s'' followed by a null character.

These getters and setters can shadow the properties and methods described above.

== Arrays ==

== Casting ==

== Equality ==

== Int64 ==

<code>Int64</code> objects have the following methods:

These functions are not exactly JS functions or C/C++ functions. They're algorithms used elsewhere in the spec.

* If the type of ''x'' is <code>void</code>, return <code>undefined</code>.

* If ''x'' is an unsigned wrapped integer type (<code>unsigned long</code>, <code>uint64_t</code>, <code>size_t</code>, or <code>uintptr_t</code>), return a <code>ctypes.UInt64</code> object with value ''x''.

* Otherwise ''x'' is of an array, struct, or pointer type. If the argument ''x'' is already a <code>CData</code> object, return it. Otherwise allocate a  buffer containing a copy of the C/C++ value ''x'', and return a <code>CData</code> object of the appropriate type referring to the object in the new buffer.

''(Arrays of characters do not convert to JavaScript strings. Rationale: Suppose <code>x</code> is a <code>CData</code> object of a struct type with a member <code>a</code> of type <code>char[10]</code>. Then <code>x.a[1]</code> should return the character in element 1 of the array, even if <code>x.a[0]</code> is a null character.  Likewise, <code>x.a[0] = '\0';</code> should modify the contents of the array. Both are possible only if <code>x.a</code> is a <code>CData</code> object of array type, not a JavaScript string.)''

''t'' must not be <code>void</code> or an array type with unspecified length.  ''(Rationale: C/C++ variables and parameters cannot have such types. The parameter of a function declared <code>int f(int x[])</code> is <code>int *</code>, not <code>int[]</code>.)''

:* Otherwise fail.

:* If ''val'' is a string of length 1, the result is the 16-bit unsigned value of the code unit in the string. <code>''val''.charCodeAt(0)</code>.

:* Otherwise fail.

* If ''t'' is an array type:

:* If ''val'' is a JavaScript string:

::* If <code>''t''.elementType</code> is an 8-bit character type:

:::* If ''t'' is not well-formed UTF-16, fail.

:::* The result is an array of type ''t'' whose first ''n'' elements are the 8-bit values in ''s''. If <code>''t''.length &gt; ''n''</code>, then element ''n'' of the result is 0. The values of the rest of the array elements are unspecified.

::* Otherwise fail.

:* If ''val'' is a JavaScript array object:

::* If <code>''val''.length</code> is not a nonnegative integer, fail.

::* If <code>''val''.length !== ''t''.length</code>, fail.

::* Otherwise, the result is a C/C++ array of <code>''val''.length</code> elements of type <code>''t''.elementType</code>. Element ''i'' of the result is <code>ImplicitConvert(''val''[''i''], ''t''.elementType)</code>.

* Otherwise ''t'' is a struct type.

* If ''t'' is a pointer type and ''val'' is a number, <code>Int64</code> object, or <code>UInt64</code> object that can be exactly represented as an <code>intptr_t</code> or <code>uintptr_t</code>, the result is the same as casting that <code>intptr_t</code> or <code>uintptr_t</code> value to type ''t'' with a C-style cast.

* Otherwise fail.

*If ''t'' and ''u'' represent the same built-in type, even <code>void</code>, return true.

*If they are both pointer types, return <code>SameType(''t''.targetType, ''u''.targetType)</code>.

*If they are both struct types, return <code>''t'' === ''u''</code>.

*Otherwise return false.

This allocates a new C++ object of type <code>int32_t</code> (4 bytes of memory), zeroes it out, and returns a JS object that manages the allocated memory. Whenever the JS object is garbage-collected, the allocated memory will be automatically freed.

  let myfunc = mylib.declare("myfunc", ctypes.default_abi,

<code>ctypes.int32_t</code> is a <code>CType</code>. Like all other CTypes, it can be used for type specification when passed as an object, as above. (This will work for user-defined <code>CTypes</code> such as structs and pointers also - see later.)

Opaque pointers:

  // A new opaque pointer type.

   

  let fopen = mylib.declare("fopen", ctypes.default_abi,

   

  // cast from (uint32_t *) to (uint8_t *)

   

  // first byte of buffer

'''<code>''cdata''.writeString(''s'', ''[encoding[, length]]'')</code>''' - Determine the starting pointer ''p'' as above. If ''s'' is not a well-formed UTF-16 string, throw a <code>TypeError</code>.  ''(Open issue: Error handling.)'' Otherwise convert ''s'' to bytes in the specified ''encoding'' (default: UTF-8) and write at most ''length'' - 1 bytes, or all the converted bytes, if ''length'' is <code>undefined</code> or omitted, to memory starting at ''p''. Write a converted null character after the data. Return the number of bytes of data written, not counting the terminating null character.

''(Open issue: As proposed, these are not suitable for working with encodings where a zero byte might not indicate the end of text. For example, a string encoded in UTF-16 will typically contain a lot of zero bytes. Unfortunately, in the case of readString, the underlying library demands the length up front.)''

In C/C++, the type <code>char *</code> effectively promises nothing about the pointed-to data. Autoconverting would make it hard to use APIs that return non-null-terminated strings (or structs containing <code>char *</code> pointers that aren't logically strings). The workaround would be to declare them as a different type.