node-ctypes 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,6 +10,53 @@ import { mirrorAddress, mirrorsActive, refresh } from "../memory/mirror.js";
10
10
  import { ArgumentError } from "../platform/errors.js";
11
11
  import { encodeWide } from "../memory/buffer.js";
12
12
  import { buildWrapper } from "../structures/helpers/wrap.js";
13
+ import { byrefOwners, isScalarSubclass, resolveParameter, scalarView } from "../structures/helpers/common.js";
14
+
15
+ const activeArgumentOwners = new Set();
16
+
17
+ function retainArgument(owners, value) {
18
+ if (owners !== undefined && value !== null && (typeof value === "object" || typeof value === "function")) owners.push(value);
19
+ }
20
+
21
+ export function needsArgumentOwners(value) {
22
+ if (value === null || (typeof value !== "object" && typeof value !== "function")) return false;
23
+ if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
24
+ return "_buffer" in value || "_as_parameter_" in value || (mirrorsActive && mirrorAddress(value) !== undefined);
25
+ }
26
+ return true;
27
+ }
28
+
29
+ export function argumentsNeedOwners(args) {
30
+ for (let i = 0; i < args.length; i++) if (needsArgumentOwners(args[i])) return true;
31
+ return false;
32
+ }
33
+
34
+ // The registry is a GC root, including while another converter reenters JS.
35
+ export function callWithArgumentOwners(ffiFunc, method, args, converters, finish, resultHandler, checkedCall) {
36
+ const owners = [];
37
+ activeArgumentOwners.add(owners);
38
+ let pending = false;
39
+ try {
40
+ const converted = convertArguments(args, converters, owners);
41
+ const result =
42
+ resultHandler === undefined ? ffiFunc[method](...converted) : checkedCall === undefined ? ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](resultHandler, ...converted) : checkedCall(resultHandler, ...converted);
43
+ if (method === "callAsync") {
44
+ const completed = finish === undefined ? result : result.then((value) => finish(value, args));
45
+ const promise = completed.finally(() => activeArgumentOwners.delete(owners));
46
+ pending = true;
47
+ return promise;
48
+ }
49
+ return finish === undefined ? result : finish(result, args);
50
+ } finally {
51
+ if (!pending) activeArgumentOwners.delete(owners);
52
+ }
53
+ }
54
+
55
+ export function callWithResultHandler(ffiFunc, method, args, converters, handler, retainOwners, checkedCall) {
56
+ if (retainOwners) return callWithArgumentOwners(ffiFunc, method, args, converters, undefined, handler, checkedCall);
57
+ if (checkedCall !== undefined) return checkedCall(handler, ...convertArguments(args, converters));
58
+ return ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](handler, ...convertArguments(args, converters));
59
+ }
13
60
 
14
61
  /**
15
62
  * Base conversion of an object argument:
@@ -20,32 +67,44 @@ import { buildWrapper } from "../structures/helpers/wrap.js";
20
67
  * original address
21
68
  * - anything else unchanged
22
69
  */
23
- export function coerceObject(a) {
70
+ export function coerceObject(a, owners) {
71
+ return objectMemory(resolveParameter(a, owners), owners);
72
+ }
73
+
74
+ function objectMemory(a, owners) {
24
75
  if (a === null || typeof a !== "object") return a;
76
+ retainArgument(owners, a);
25
77
  const b = a._buffer;
26
78
  if (b !== undefined) {
79
+ retainArgument(owners, b);
27
80
  // Puntatore creato da indirizzo (fromAddress): senza Buffer va passato
28
81
  // l'indirizzo, altrimenti al C arriverebbe NULL.
29
82
  if (b === null && a._pointerType !== undefined) return a.address;
30
83
  if (mirrorsActive) return mirrorAddress(b) ?? b;
31
84
  return b;
32
85
  }
33
- if (a._as_parameter_ !== undefined) return a._as_parameter_;
86
+ const parameter = a._as_parameter_;
87
+ if (parameter !== undefined) {
88
+ retainArgument(owners, parameter);
89
+ return parameter;
90
+ }
34
91
  if (mirrorsActive) return mirrorAddress(a) ?? a;
35
92
  return a;
36
93
  }
37
94
 
38
95
  // Struct/union passato per valore: il nativo copia i byte del Buffer, che per
39
96
  // una copia di memoria nativa vanno prima riletti.
40
- function coerceStructValue(a) {
97
+ function coerceStructValue(a, owners) {
41
98
  if (a !== null && typeof a === "object") {
99
+ retainArgument(owners, a);
42
100
  const b = Buffer.isBuffer(a._buffer) ? a._buffer : a;
43
101
  if (Buffer.isBuffer(b)) {
102
+ retainArgument(owners, b);
44
103
  refresh(b);
45
104
  return b;
46
105
  }
47
106
  }
48
- return coerceObject(a);
107
+ return coerceObject(a, owners);
49
108
  }
50
109
 
51
110
  const isStructType = (t) => t !== null && (typeof t === "function" || typeof t === "object") && (typeof t._buildStruct === "function" || typeof t._buildUnion === "function" || t._isStructType === true);
@@ -59,15 +118,17 @@ const isStructType = (t) => t !== null && (typeof t === "function" || typeof t =
59
118
  function structArgument(T, index) {
60
119
  const instance = typeof T === "function" ? (values) => new T(values) : (values) => T.create(values);
61
120
  const coerce = mirrorsActive ? coerceStructValue : coerceObject;
62
- return (a) => {
121
+ return (a, owners) => {
122
+ a = resolveArgument(a, owners, index);
123
+ retainArgument(owners, a);
63
124
  if (Array.isArray(a)) {
64
125
  // Python rifiuta anche una tupla.
65
126
  throw new ArgumentError(`argument ${index + 1}: TypeError: expected ${T.name || "structure"} instance instead of Array`);
66
127
  }
67
128
  if (a !== null && typeof a === "object" && a._buffer === undefined && a._as_parameter_ === undefined && !ArrayBuffer.isView(a) && !(a instanceof ArrayBuffer)) {
68
- return coerce(instance(a));
129
+ return coerce(instance(a), owners);
69
130
  }
70
- return coerce(a);
131
+ return coerce(a, owners);
71
132
  };
72
133
  }
73
134
 
@@ -76,10 +137,11 @@ function structArgument(T, index) {
76
137
  * instance is passed by value (`abs(c_int(-5))`), other objects as
77
138
  * {@link coerceObject}.
78
139
  */
79
- export function coerceValue(a) {
80
- if (a === null || typeof a !== "object") return a;
140
+ export function coerceValue(a, owners) {
141
+ if (a === null || (typeof a !== "object" && typeof a !== "function")) return a;
142
+ retainArgument(owners, a);
81
143
  if (a._isSimpleCDataInstance === true) return a.value;
82
- return coerceObject(a);
144
+ return coerceObject(a, owners);
83
145
  }
84
146
 
85
147
  /**
@@ -87,9 +149,11 @@ export function coerceValue(a) {
87
149
  * argtypes): a SimpleCData instance is passed as is, and the native call uses
88
150
  * its type, as Python does (`printf("%f", c_double(2.0))`).
89
151
  */
90
- export function coerceVariadic(a) {
152
+ export function coerceVariadic(a, owners) {
153
+ a = resolveParameter(a, owners);
154
+ retainArgument(owners, a);
91
155
  if (a !== null && typeof a === "object" && a._isSimpleCDataInstance === true) return a;
92
- return coerceObject(a);
156
+ return coerceObject(a, owners);
93
157
  }
94
158
 
95
159
  /**
@@ -107,12 +171,15 @@ export function argumentConverters(argTypes, native) {
107
171
  const baseConverter = (t, index) => {
108
172
  if (isStructType(t)) return structArgument(t, index);
109
173
  if (t !== null && (typeof t === "function" || typeof t === "object") && t._isArrayType === true) return arrayArgument(t, index);
174
+ if (t !== null && typeof t === "object" && t._pointerTo !== undefined) return pointerArgument(t, index, native);
110
175
  if (typeof t !== "function" || t._isSimpleCData !== true) return coerceObject;
111
- if (!pointerKinds.has(t._type)) return coerceValue;
112
- return (a) => {
176
+ if (!pointerKinds.has(t._type)) return scalarArgument(t, index);
177
+ return (a, owners) => {
178
+ a = resolveArgument(a, owners, index);
113
179
  if (a === null || typeof a !== "object") return a;
180
+ retainArgument(owners, a);
114
181
  if (a._isSimpleCDataInstance === true && a instanceof t) return a.value;
115
- return coerceObject(a);
182
+ return coerceObject(a, owners);
116
183
  };
117
184
  };
118
185
  return argTypes.map((t, index) => {
@@ -122,6 +189,80 @@ export function argumentConverters(argTypes, native) {
122
189
  });
123
190
  }
124
191
 
192
+ function scalarArgument(T, index) {
193
+ const boolean = T._isBoolean === true;
194
+ return (value, owners) => {
195
+ if (value !== null && (typeof value === "object" || typeof value === "function")) value = resolveArgument(value, owners, index);
196
+ if (value === null || typeof value !== "object") return value;
197
+ retainArgument(owners, value);
198
+ if (value._isSimpleCDataInstance === true) {
199
+ if (!boolean && !(value instanceof T)) {
200
+ throw new ArgumentError(`argument ${index + 1}: TypeError: incompatible types, ${value.constructor.name} instance instead of ${T.name} instance`);
201
+ }
202
+ return value.value;
203
+ }
204
+ return objectMemory(value, owners);
205
+ };
206
+ }
207
+
208
+ function resolveArgument(value, owners, index) {
209
+ try {
210
+ return resolveParameter(value, owners);
211
+ } catch (error) {
212
+ throw new ArgumentError(`argument ${index + 1}: ${error?.name ?? "Error"}: ${error?.message ?? String(error)}`, { cause: error });
213
+ }
214
+ }
215
+
216
+ const compatibleType = (actual, expected) => actual === expected || (typeof actual === "function" && typeof expected === "function" && actual.prototype instanceof expected);
217
+
218
+ function pointerArgument(T, index, native) {
219
+ const base = T._pointerTo;
220
+ const fail = () => {
221
+ throw new ArgumentError(`argument ${index + 1}: TypeError: incompatible pointer, expected POINTER(${base.name ?? "type"})`);
222
+ };
223
+ const convert = (value, owners) => {
224
+ value = resolveArgument(value, owners, index);
225
+ if (value === null || value === undefined || typeof value === "bigint") return value;
226
+ if (typeof value === "number") {
227
+ if (!Number.isInteger(value)) fail();
228
+ return value;
229
+ }
230
+ if (typeof value === "string" && base._charKind === "char") return value;
231
+ if (typeof value === "string" && base._charKind === "wchar") {
232
+ const buffer = Buffer.concat([encodeWide(value, native.WCHAR_SIZE), Buffer.alloc(native.WCHAR_SIZE)]);
233
+ retainArgument(owners, buffer);
234
+ return buffer;
235
+ }
236
+ if (typeof base === "function" && value instanceof base) return objectMemory(value, owners);
237
+ const reference = value !== null && (typeof value === "object" || typeof value === "function") ? byrefOwners.get(value) : undefined;
238
+ if (reference !== undefined) {
239
+ if (reference.type !== undefined && !compatibleType(reference.type, base)) fail();
240
+ return objectMemory(value, owners);
241
+ }
242
+ if (value?._pointerType !== undefined) {
243
+ if (!compatibleType(value._pointerType._pointerTo, base)) fail();
244
+ return objectMemory(value, owners);
245
+ }
246
+ if (value?._arrayType !== undefined) {
247
+ if ((!compatibleType(value._arrayType, base) && !compatibleType(value._arrayType.elementType, base)) || value._arrayType._swapped_) fail();
248
+ return coerceObject(value, owners);
249
+ }
250
+ if (value?._isSimpleCDataInstance === true || value?._structDef !== undefined) {
251
+ if (typeof base === "function" && value instanceof base) return objectMemory(value, owners);
252
+ const kind = value.constructor?._type;
253
+ if ((base._charKind === "char" && kind === native.CType.STRING) || (base._charKind === "wchar" && kind === native.CType.WSTRING)) {
254
+ if (mirrorsActive) refresh(value._buffer);
255
+ return native.POINTER_SIZE === 8 ? value._buffer.readBigUInt64LE(0) : BigInt(value._buffer.readUInt32LE(0));
256
+ }
257
+ fail();
258
+ }
259
+ if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer || Buffer.isBuffer(value?._buffer)) return objectMemory(value, owners);
260
+ fail();
261
+ };
262
+ if (base._charKind === "wchar") Object.defineProperty(convert, "requiresOwners", { value: true });
263
+ return convert;
264
+ }
265
+
125
266
  /**
126
267
  * Converter for an argtype with a `from_param` method (Python protocol): it
127
268
  * receives the argument as passed, its result (or the result's
@@ -129,7 +270,8 @@ export function argumentConverters(argTypes, native) {
129
270
  * ArgumentError "argument N: <name>: <message>", as in Python.
130
271
  */
131
272
  function fromParamArgument(T, base, index) {
132
- return (a) => {
273
+ const converter = (a, owners) => {
274
+ retainArgument(owners, a);
133
275
  let converted;
134
276
  try {
135
277
  converted = T.from_param(a);
@@ -137,8 +279,11 @@ function fromParamArgument(T, base, index) {
137
279
  if (e instanceof ArgumentError) throw e;
138
280
  throw new ArgumentError(`argument ${index + 1}: ${e?.name ?? "Error"}: ${e?.message ?? String(e)}`, { cause: e });
139
281
  }
140
- return base(converted);
282
+ retainArgument(owners, converted);
283
+ return base(converted, owners);
141
284
  };
285
+ Object.defineProperty(converter, "requiresOwners", { value: true });
286
+ return converter;
142
287
  }
143
288
 
144
289
  const arrayTypeName = (T) => `${T.elementType?.name || "array"} * ${T.length}`;
@@ -161,15 +306,19 @@ function describeValue(a) {
161
306
  * @returns {Function} Converter
162
307
  */
163
308
  function arrayArgument(T, index) {
164
- return (a) => {
309
+ return (a, owners) => {
310
+ a = resolveArgument(a, owners, index);
311
+ retainArgument(owners, a);
165
312
  if (a !== null && typeof a === "object") {
166
313
  const arrayType = a._arrayType;
167
314
  if (arrayType !== undefined) {
168
- if (arrayType === T || (arrayType.elementType === T.elementType && arrayType.length === T.length)) return coerceObject(a);
315
+ if (arrayType === T || (arrayType.elementType === T.elementType && arrayType.length === T.length)) return coerceObject(a, owners);
169
316
  } else if (ArrayBuffer.isView(a) || a instanceof ArrayBuffer) {
170
- return coerceObject(a);
317
+ return coerceObject(a, owners);
171
318
  } else if (a._as_parameter_ !== undefined) {
172
- return a._as_parameter_;
319
+ const parameter = a._as_parameter_;
320
+ retainArgument(owners, parameter);
321
+ return parameter;
173
322
  }
174
323
  }
175
324
  throw new ArgumentError(`argument ${index + 1}: TypeError: expected ${arrayTypeName(T)} instance instead of ${describeValue(a)}`);
@@ -180,16 +329,22 @@ function arrayArgument(T, index) {
180
329
  * Convert all call arguments: declared ones with their converter, the rest
181
330
  * (variadic or without argtypes) with the Python default conversion.
182
331
  */
183
- export function convertArguments(args, converters) {
332
+ export function convertArguments(args, converters, owners) {
184
333
  const n = args.length;
185
334
  const declared = converters.length;
186
335
  const out = new Array(n);
187
336
  for (let i = 0; i < n; i++) {
188
- out[i] = i < declared ? converters[i](args[i]) : coerceVariadic(args[i]);
337
+ out[i] = i < declared ? converters[i](args[i], owners) : coerceVariadic(args[i], owners);
189
338
  }
190
339
  return out;
191
340
  }
192
341
 
342
+ function copyResultBytes(result) {
343
+ const bytes = Buffer.alloc(result.length);
344
+ bytes.set(result);
345
+ return bytes;
346
+ }
347
+
193
348
  /**
194
349
  * Python restype conversion done in JS: `POINTER(T)` returns a pointer object
195
350
  * (`null` for NULL), a CFUNCTYPE type returns a callable. Undefined when the
@@ -199,29 +354,50 @@ export function convertArguments(args, converters) {
199
354
  * @returns {Function|undefined} Converter from the native result
200
355
  */
201
356
  export function resultConverter(restype) {
357
+ if (isScalarSubclass(restype)) return (bytes) => scalarView(restype, bytes);
358
+ if (restype?._isVariantBool === true) return (result) => result !== 0;
202
359
  if (restype !== null && typeof restype === "object" && restype._pointerTo !== undefined) {
203
360
  return (r) => (r === null || r === 0n ? null : restype.fromAddress(r));
204
361
  }
205
362
  if (typeof restype === "function" && restype._isFuncPtr === true) {
206
363
  return (r) => (r === null || r === 0n ? null : restype(r));
207
364
  }
208
- // Struct/union per valore: il nativo restituisce i byte (opzione
209
- // `struct_buffer`, vedi structResult) in un Buffer riusato dalla funzione
210
- // a ogni chiamata, copiato qui nella memoria dell'istanza. Python:
211
- // un'istanza della classe.
365
+ // Snapshot before constructors/readers can reenter: toObject may keep
366
+ // array views or union getters over the native function's reusable buffer.
212
367
  if (typeof restype === "function" && typeof restype._buildStruct === "function") {
213
- return (r) => {
214
- const bytes = Buffer.alloc(r.length);
215
- bytes.set(r);
216
- return new restype(bytes);
217
- };
368
+ return (r) => new restype(copyResultBytes(r));
218
369
  }
219
370
  if (restype !== null && typeof restype === "object" && restype._isStructType === true) {
220
- return (r) => restype.toObject(r);
371
+ return (r) => restype.toObject(copyResultBytes(r));
221
372
  }
222
373
  return undefined;
223
374
  }
224
375
 
376
+ export function scalarResult(restype) {
377
+ return isScalarSubclass(restype);
378
+ }
379
+
380
+ export function resultCheck(restype, name, loader = "FFI") {
381
+ const check = restype?._check_retval_;
382
+ if (check !== undefined && typeof check !== "function") throw new TypeError("_check_retval_ must be callable");
383
+ const hresult = restype?._isHResult === true;
384
+ if (!hresult && check === undefined) return undefined;
385
+ return (result) => {
386
+ if (hresult) {
387
+ const value = result?._isSimpleCDataInstance === true ? result.value : result;
388
+ const number = typeof value === "bigint" ? Number(value) : value;
389
+ if (typeof number === "number" && number < 0) {
390
+ const hex = (number >>> 0).toString(16).padStart(8, "0").toUpperCase();
391
+ const error = new Error(`${loader} '${name}' failed with HRESULT 0x${hex}`);
392
+ error.hresult = number;
393
+ error.winerror = number >>> 0;
394
+ throw error;
395
+ }
396
+ }
397
+ return check === undefined ? result : check.call(restype, result);
398
+ };
399
+ }
400
+
225
401
  /**
226
402
  * True when `restype` is a struct or union returned by value: the native
227
403
  * function must then return its bytes (FFIFunction option `struct_buffer`),
@@ -245,13 +421,28 @@ export function structResult(restype) {
245
421
  * @returns {Function} Function to register with the native callback
246
422
  */
247
423
  export function adaptCallbackFunction(fn, argTypes, returnType, native) {
424
+ const scalarTypes = argTypes.map((type) => (isScalarSubclass(type) ? type : null));
425
+ const hasScalars = scalarTypes.some((type) => type !== null);
248
426
  const pointerTypes = argTypes.map((t) => (t !== null && typeof t === "object" && t._pointerTo !== undefined ? t : null));
249
427
  const hasPointers = pointerTypes.some((t) => t !== null);
250
428
  // Struct/union per valore: il nativo passa una copia in un Buffer.
251
429
  const structViews = argTypes.map(structView);
252
430
  const hasStructs = structViews.some((view) => view !== null);
431
+ const variantArgs = argTypes.map((type) => type?._isVariantBool === true);
432
+ const hasVariants = variantArgs.some(Boolean);
433
+ const variantResult = returnType?._isVariantBool === true;
253
434
  const toResult = stringResult(returnType, native);
254
435
  return function (...args) {
436
+ if (hasScalars) {
437
+ for (let i = 0; i < scalarTypes.length; i++) {
438
+ if (scalarTypes[i] !== null) args[i] = scalarView(scalarTypes[i], args[i]);
439
+ }
440
+ }
441
+ if (hasVariants) {
442
+ for (let i = 0; i < variantArgs.length; i++) {
443
+ if (variantArgs[i] && scalarTypes[i] === null) args[i] = args[i] !== 0;
444
+ }
445
+ }
255
446
  if (hasPointers) {
256
447
  for (let i = 0; i < pointerTypes.length; i++) {
257
448
  const T = pointerTypes[i];
@@ -266,8 +457,9 @@ export function adaptCallbackFunction(fn, argTypes, returnType, native) {
266
457
  }
267
458
  }
268
459
  const result = fn.apply(this, args);
460
+ if (variantResult) return returnType.from_param(result);
269
461
  if (toResult !== undefined && typeof result === "string") return toResult(result);
270
- return result !== null && typeof result === "object" ? coerceValue(result) : result;
462
+ return result !== null && (typeof result === "object" || typeof result === "function") ? coerceValue(result) : result;
271
463
  };
272
464
  }
273
465