Jsctypes/api - Revision history

Cpeterson: Bug 1063962 renamed ctypes.jschar to ctypes.char16_t and, to maintain backwards compatibility, bug 1064935 added an alias for ctypes.jschar to ctypes.char16_t.

2014-09-30T04:23:39Z

Bug 1063962 renamed ctypes.jschar to ctypes.char16_t and, to maintain backwards compatibility, bug 1064935 added an alias for ctypes.jschar to ctypes.char16_t.

← Older revision		Revision as of 04:23, 30 September 2014
Line 39:		Line 39:
	:'''<code>ctypes.char, ctypes.signed_char, ctypes.unsigned_char</code>''' - Character types that behave like the corresponding C types. (These are very much like <code>int8_t</code> and <code>uint8_t</code>, but they differ in some details of conversion. For example, <code>ctypes.char.array(30)(str)</code> converts the string ''str'' to UTF-8 and returns a new <code>CData</code> object of array type.)		:'''<code>ctypes.char, ctypes.signed_char, ctypes.unsigned_char</code>''' - Character types that behave like the corresponding C types. (These are very much like <code>int8_t</code> and <code>uint8_t</code>, but they differ in some details of conversion. For example, <code>ctypes.char.array(30)(str)</code> converts the string ''str'' to UTF-8 and returns a new <code>CData</code> object of array type.)

	:'''<code>ctypes.~~jschar~~</code>''' - A 16-bit unsigned character type. (This is distinct from <code>uint16_t</code> in details of conversion behavior. js-ctypes autoconverts C <code>~~jschar~~</code>s to JavaScript strings of length 1.)		:'''<code>ctypes.char16_t</code>''' - A 16-bit unsigned character type representing a UTF-16 code unit. (This is distinct from <code>uint16_t</code> in details of conversion behavior. js-ctypes autoconverts C <code>char16_t</code>s to JavaScript strings of length 1.) For backwards compatibility, <code>ctypes.jschar</code> is an alias for <code>char16_t</code>.

	:'''<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>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.)
Line 109:		Line 109:
	ctypes.void_t.name		ctypes.void_t.name
	===> "void"		===> "void"
	ctypes.~~jschar~~.ptr.name		ctypes.char16_t.ptr.name
	===> "~~jschar~~ *"		===> "char16_t *"

	const FILE = new ctypes.StructType("FILE").ptr;		const FILE = new ctypes.StructType("FILE").ptr;
Line 217:		Line 217:
	::* If ''val'' is a size value (defined above): Let ''u'' = <code>ArrayType(''t''.elementType, ''val'')</code> and return <code>new ''u''</code>.		::* 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 <code>~~jschar~~</code> and ''val'' is a string: Return a new <code>CData</code> object of type <code>ArrayType(ctypes.~~jschar~~, ''val''.length + 1)</code> containing the contents of ''val'' followed by a null character.		::* If <code>''t''.elementType</code> is <code>char16_t</code> and ''val'' is a string: Return a new <code>CData</code> object of type <code>ArrayType(ctypes.char16_t, ''val''.length + 1)</code> containing the contents of ''val'' followed by a null character.

	::* 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.		::* 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.
Line 421:		Line 421:
	* 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''.		* 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''.

	* 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 type <code>char16_t</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, return the JavaScript number equal to its integer value. (This is sensitive to the signedness of the character type. Also, we assume no character types are so wide that they don't fit into a JavaScript number.)		* If ''x'' is of any other character type, return the JavaScript number equal to its integer value. (This is sensitive to the signedness of the character type. Also, we assume no character types are so wide that they don't fit into a JavaScript number.)
Line 455:		Line 455:
	:* Otherwise fail.		:* Otherwise fail.

	* If ''t'' is <code>ctypes.~~jschar~~</code>:		* If ''t'' is <code>ctypes.char16_t</code>:
	:* 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>.		:* 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>.
	:* 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 ≤ ''val'' < 2<sup>16</sup>), the result is that value.		:* If ''val'' is a number that can be exactly represented as a value of type <code>char16_t</code> (that is, an integer in the range 0 ≤ ''val'' < 2<sup>16</sup>), the result is that value.
	:* Otherwise fail.		:* Otherwise fail.

Line 476:		Line 476:
	* If ''t'' is an array type:		* If ''t'' is an array type:
	:* If ''val'' is a JavaScript string:		:* If ''val'' is a JavaScript string:
	::* If <code>''t''.elementType</code> is <code>~~jschar~~</code> and <code>''t''.length >= ''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 > ''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.		::* If <code>''t''.elementType</code> is <code>char16_t</code> and <code>''t''.length >= ''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 > ''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.
	::* If <code>''t''.elementType</code> is an 8-bit character type:		::* If <code>''t''.elementType</code> is an 8-bit character type:
	:::* If ''t'' is not well-formed UTF-16, fail.		:::* If ''t'' is not well-formed UTF-16, fail.
Line 764:		Line 764:
	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.		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.

	'''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.		'''Unicode.''' This problem does not apply to conversions between JS strings and <code>char16_t</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.		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>char16_t</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.		'''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>char16_t </code> suggest that the referent might be modified.

Nchaim at 19:44, 1 June 2012

2012-06-01T19:44:57Z

← Older revision		Revision as of 19:44, 1 June 2012
Line 616:		Line 616:

	// cast from (uint32_t ) to (uint8_t )		// cast from (uint32_t ) to (uint8_t )
	let q = ctypes.cast(ctypes.uint8_t.ptr~~, p~~);		let q = ctypes.cast(p, ctypes.uint8_t.ptr);

	// first byte of buffer		// first byte of buffer

J^: fix FILE * sytax

2010-07-07T20:11:27Z

fix FILE * sytax

← Older revision		Revision as of 20:11, 7 July 2010
Line 78:		Line 78:
	const HANDLE = new ctypes.PointerType("HANDLE");		const HANDLE = new ctypes.PointerType("HANDLE");
	const HANDLES = new ctypes.ArrayType(HANDLE);		const HANDLES = new ctypes.ArrayType(HANDLE);
	const FILE = new ctypes.~~PointerType~~("FILE *");		const FILE = new ctypes.StructType("FILE").ptr;
	const IOBuf = new ctypes.ArrayType(ctypes.uint8_t, 4096);		const IOBuf = new ctypes.ArrayType(ctypes.uint8_t, 4096);

Line 112:		Line 112:
	===> "jschar *"		===> "jschar *"

	const FILE = new ctypes.~~PointerType~~("FILE *");		const FILE = new ctypes.StructType("FILE").ptr;
	FILE.name		FILE.name
	===> "FILE *"		===> "FILE*"

	const fn_t = new ctypes.FunctionType(ctypes.stdcall, ctypes.int, [ ctypes.voidptr_t, ctypes.voidptr_t ]);		const fn_t = new ctypes.FunctionType(ctypes.stdcall, ctypes.int, [ ctypes.voidptr_t, ctypes.voidptr_t ]);
Line 563:		Line 563:

	// A new opaque pointer type.		// A new opaque pointer type.
	FILE_ptr = new ctypes.~~PointerType~~("FILE *");		FILE_ptr = new ctypes.StructType("FILE").ptr;

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

Dwitte: /* Libraries */

2010-03-16T23:20:53Z

Libraries

← Older revision		Revision as of 23:20, 16 March 2010
Line 9:		Line 9:
	<code>Library</code> objects have the following methods:		<code>Library</code> objects have the following methods:

	:'''<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>''lib''.declare(''name'', ''abi'', ''rtype'', ''<nowiki>[argtype1, ...]</nowiki>'')</code>''' - Declare a function. ''(TODO: all the details)'' This always returns a new callable <code>CData</code> object representing a function pointer to ''name'', or throws an exception.

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

Dwitte: /* Pointers */

2010-03-16T22:59:05Z

Pointers

← Older revision		Revision as of 22:59, 16 March 2010
Line 289:		Line 289:

	:'''<code>''cptr''.''contents'' = ''val''</code>''' - Let ''cval'' = <code>ImplicitConvert(''val'', the base type of the pointer)</code>. If conversion fails, throw a <code>TypeError</code>. Otherwise store ''cval'' in the pointed-to contents of ''cptr''.		:'''<code>''cptr''.''contents'' = ''val''</code>''' - Let ''cval'' = <code>ImplicitConvert(''val'', the base type of the pointer)</code>. If conversion fails, throw a <code>TypeError</code>. Otherwise store ''cval'' in the pointed-to contents of ''cptr''.

			== Functions ==

			<code>CData</code> objects of function types are callable:

			:'''<code>''let result = cfn(arg''1'', ...)''</code>''' - Let ''(carg''1'', ...)'' be <code>CData</code> objects representing the arguments to the C function ''cfn'', and ''cresult'' be a <code>CData</code> object representing its return value. Let ''carg''n = <code>ImplicitConvert(''arg''n, the type of the argument)</code>, and let ''result'' = <code>ConvertToJS(''cresult'')</code>. Call the C function with arguments represented by ''(carg''1'', ...)'', and store the result in ''cresult''. If conversion fails, throw a <code>TypeError</code>.

	== Arrays ==		== Arrays ==

Dwitte: /* Properties of types */

2010-03-16T22:42:09Z

Properties of types

← Older revision		Revision as of 22:42, 16 March 2010
Line 169:		Line 169:
	Function types also have:		Function types also have:

	:'''<code>''t''.abi</code>''' - Read-only. The ABI of the function; one of the ''ctypes'' ABI objects.		:'''<code>''t''.abi</code>''' - Read-only. The ABI of the function; one of the ctypes ABI objects.

	:'''<code>''t''.returnType</code>''' - Read-only. The return type.		:'''<code>''t''.returnType</code>''' - Read-only. The return type.

Dwitte: /* Properties of types */

2010-03-16T22:41:12Z

Properties of types

← Older revision		Revision as of 22:41, 16 March 2010
Line 101:		Line 101:
	:For primitive types this is just the name of the corresponding C/C++ type.		:For primitive types this is just the name of the corresponding C/C++ type.

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

	:''(Open issue: This conflicts with the usual meaning of .name for functions, and types are callable like functions.)''		:''(Open issue: This conflicts with the usual meaning of .name for functions, and types are callable like functions.)''
Line 115:		Line 115:
	FILE.name		FILE.name
	===> "FILE *"		===> "FILE *"

			const fn_t = new ctypes.FunctionType(ctypes.stdcall, ctypes.int, [ ctypes.voidptr_t, ctypes.voidptr_t ]);
			fn_t.name
			===> "int (__stdcall )(void, void*)"

	const struct_tm = new ctypes.StructType("tm", [{tm_sec: ctypes.int}, ...]);		const struct_tm = new ctypes.StructType("tm", [{tm_sec: ctypes.int}, ...]);
Line 162:		Line 166:

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

			Function types also have:

			:'''<code>''t''.abi</code>''' - Read-only. The ABI of the function; one of the ''ctypes'' ABI objects.

			:'''<code>''t''.returnType</code>''' - Read-only. The return type.

			:'''<code>''t''.argTypes</code>''' - Read-only. A sealed array of argument types.

	Struct types also have:		Struct types also have:
Line 183:		Line 195:
	: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.		: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.

	: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>.		: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,Function}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>. The prototype of a function type is <code>ctypes.FunctionType.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>.		: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 five type constructors <code>ctypes.{C,Array,Struct,Pointer,Function}Type</code>.

	== Calling types ==		== Calling types ==

Dwitte: /* User-defined types */

2010-03-16T22:33:04Z

User-defined types

← Older revision		Revision as of 22:33, 16 March 2010
Line 82:		Line 82:

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

	const comparator_t = new ctypes.FunctionType(ctypes.default_abi, ctypes.int, [ ctypes.voidptr_t, ctypes.voidptr_t ]);		const comparator_t = new ctypes.FunctionType(ctypes.default_abi, ctypes.int, [ ctypes.voidptr_t, ctypes.voidptr_t ]);

Dwitte: /* User-defined types */

2010-03-16T22:32:34Z

User-defined types

← Older revision		Revision as of 22:32, 16 March 2010
Line 82:		Line 82:

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

			const comparator_t = new ctypes.FunctionType(ctypes.default_abi, ctypes.int, [ ctypes.voidptr_t, ctypes.voidptr_t ]);

	== Properties of types ==		== Properties of types ==

Dwitte: /* User-defined types */

2010-03-16T22:31:08Z

User-defined types

← Older revision		Revision as of 22:31, 16 March 2010
Line 53:		Line 53:
	:'''<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.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.FunctionType(''abi'', ''rt'', [ ''at1'', ... ])</code>''' - Return a function pointer <code>CType</code> corresponding to the C type <code>rt (*) (at1, ...)</code>~~, with ''abi''~~, where ''abi'' is a ctypes ABI type and ''rt'' and ''at1'', ... are <code>CType</code>s. Otherwise throw a <code>TypeError</code>.		:'''<code>new ctypes.FunctionType(''abi'', ''rt'', [ ''at1'', ... ])</code>''' - Return a function pointer <code>CType</code> corresponding to the C type <code>rt (*) (at1, ...)</code>, where ''abi'' is a ctypes ABI type and ''rt'' and ''at1'', ... are <code>CType</code>s. 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>.		:'''<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>.