Jsctypes/api: Difference between revisions

:'''<code>''lib''.declare(''name'', ''abi'', ''rtype'', ''<nowiki>[argtype1, ...]</nowiki>'')</code>''' - Declare a function. ''(TODO: all the details)'' This always returns a new function object or throws an exception.

:'''<code>ctypes.char, ctypes.signed_char, ctypes.unsigned_char</code>''' - Character types that behave like the corresponding C types. (These are distinct from <code>int8_t</code> and <code>uint8_t</code> in details of conversion behavior. For example, js-ctypes autoconverts between C characters and one-character JavaScript strings.)

:'''<code>ctypes.jschar</code>''' - A 16-bit unsigned character type. (This is distinct from <code>uint8_t</code> in details of conversion behavior. js-ctypes autoconverts C <code>jschar</code>s to JavaScript strings of length 1.)

  const FILE = new ctypes.PointerType("FILE *");

:For struct types and opaque pointer types, this is simply the string that was passed to the constructor. For other pointer types and array types this should try to generate valid C/C++ type expressions, which isn't exactly trivial.

  ctypes.jschar.ptr.name

   ===> "jschar *"

  const FILE = new ctypes.PointerType("FILE *");

   ===> "FILE *"

:Types have a hierarchy of prototype objects. The prototype of <code>ctypes.CType.prototype</code> is <code>Function.prototype</code>. The prototype of <code>ctypes.{Array,Struct,Pointer}Type.prototype</code> and of all the builtin types except <code>ctypes.voidptr_t</code> is <code>ctypes.CType.prototype</code>. The prototype of an array type is <code>ctypes.ArrayType.prototype</code>. The prototype of a struct type is <code>ctypes.StructType.prototype</code>. The prototype of a pointer type is <code>ctypes.PointerType.prototype</code>.

:Every <code>CType</code> ''t'' has <code>''t''.prototype.constructor === ''t''</code>; that is, its <code>.prototype</code> has a read-only, permanent, own <code>.constructor</code> property that refers to the type. The same is true of the four type constructors <code>ctypes.{C,Array,Struct,Pointer}Type</code>.

::* If <code>''t''.elementType</code> is <code>jschar</code> and ''val'' is a string: Return a new <code>CData</code> object of type <code>ArrayType(ctypes.jschar, ''val''.length&nbsp;+&nbsp;1)</code> containing the contents of ''val'' followed by a null character.

:'''<code>ctypes.Int64(''n'')</code>''' or '''<code>new ctypes.Int64(''n'')</code>''' - If ''n'' is an integer-valued number such that -2⁶³ &le; ''n'' &lt; 2⁶³, return a sealed <code>Int64</code> object with that value. Otherwise if ''n'' is a decimal or hexadecimal string (optionally with a leading minus sign) and represents a number within range, convert the string to an integer and construct an <code>Int64</code> object as above. Otherwise if ''n'' is an <code>Int64</code> or <code>UInt64</code> object, and represents a number within range, use the value to construct an <code>Int64</code> object as above. Otherwise throw a <code>TypeError</code>.

* If ''x'' is of type <code>jschar</code>, return a JavaScript string of length 1 containing the value of ''x'' (like <code>String.fromCharCode(x)</code>).

* If ''x'' is of any other character type, select the corresponding Unicode character. ''(Open issue: Unicode conversions.)'' Convert the character to UTF-16. Return a JavaScript string containing the UTF-16 code units. (If the character type is 1 byte with each value mapping to a Unicode BMP character, the result is a one-character JavaScript string.) ''(Note: If we ever support <code>wchar_t</code>, it might be best to autoconvert it to a number. On platforms where <code>wchar_t</code> is 32 bits, values over <code>0x10ffff</code> are not Unicode characters.)''

* If ''t'' is <code>ctypes.jschar</code>:

:* If ''val'' is a number that can be exactly represented as a value of type <code>jschar</code> (that is, an integer in the range 0 &le; ''val'' &lt; 2¹⁶), the result is that value.

::* If <code>''t''.elementType</code> is <code>jschar</code> and <code>''t''.length &gt;= ''val''.length</code>, the result is an array of type ''t'' whose first <code>''val''.length</code> elements are the 16-bit elements of ''val''. If <code>''t''.length &gt; ''val''.length</code>, then element <code>''val''.length</code> of the result is a null character. The values of the rest of the array elements are unspecified.

:* Otherwise fail.

* If ''t'' is a wrapped integer type, and ''val'' is a string consisting entirely of an optional minus sign, followed by the characters "0x" or "0X", followed by one or more hexadecimal digits, then the result is the same as casting the number named by ''val'' to type ''t'' with a C-style cast.

*If they are both array types, return <code>SameType(''t''.elementType, ''u''.targetType) &amp;&amp; ''t''.length === ''u''.length</code>.

(Of course you don't normally need to do this, as js-ctypes will autoconvert JS numbers to various C/C++ types for you.)

This kind of object is called a <code>CData</code> object, and they are described in detail in the "<code>CData</code> objects" section above.

  FILE_ptr = new ctypes.PointerType("FILE *");

  let q = ctypes.cast(ctypes.uint8_t.ptr, p);

'''Unicode.''' This problem does not apply to conversions between JS strings and <code>jschar</code> arrays or pointers; only <code>char</code> arrays or pointers.

Converting both ways raises issues about what encoding should be assumed. We assume JS strings are UTF-16 and <code>char</code> strings are UTF-8, which is not the right thing on Windows. However Windows offers a lot of APIs that accept 16-bit strings, and for those <code>jschar</code> is the right thing.

'''Casting away const.''' This problem arises only when converting from a JS string to a C/C++ pointer type.  The string data must not be modified, but the C/C++ types <code>char *</code> and <code>jschar *</code> suggest that the referent might be modified.