node-ctypes 1.14.0 → 2.0.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.
- package/README.md +107 -36
- package/build/Release/ctypes-darwin-arm64.node +0 -0
- package/build/Release/ctypes-darwin-x64.node +0 -0
- package/build/Release/ctypes-linux-arm64-musl.node +0 -0
- package/build/Release/ctypes-linux-arm64.node +0 -0
- package/build/Release/ctypes-linux-x64-musl.node +0 -0
- package/build/Release/ctypes-linux-x64.node +0 -0
- package/build/Release/ctypes-win32-arm64.node +0 -0
- package/build/Release/ctypes-win32-x64.node +0 -0
- package/lib/core/Library.js +122 -202
- package/lib/core/callback.js +18 -3
- package/lib/core/conversions.js +120 -0
- package/lib/core/funcptr.js +74 -115
- package/lib/core/lazy-loader.js +6 -3
- package/lib/core/types.js +15 -1
- package/lib/index.d.ts +668 -128
- package/lib/index.js +108 -65
- package/lib/memory/buffer.js +161 -74
- package/lib/memory/operations.js +32 -7
- package/lib/memory/pointer.js +110 -26
- package/lib/platform/errors.js +20 -0
- package/lib/platform/win_types.js +340 -100
- package/lib/structures/Structure.js +160 -112
- package/lib/structures/helpers/array.js +191 -55
- package/lib/structures/helpers/bitfield.js +2 -1
- package/lib/structures/helpers/common.js +100 -1
- package/lib/structures/helpers/struct.js +29 -39
- package/lib/structures/helpers/union.js +26 -57
- package/lib/types/SimpleCData.js +4 -0
- package/lib/types/primitives.js +48 -18
- package/package.json +4 -2
package/lib/memory/operations.js
CHANGED
|
@@ -61,6 +61,14 @@ export function createMemoryOps(deps) {
|
|
|
61
61
|
if (type && type._buffer && type.constructor && type.constructor._isSimpleCData) {
|
|
62
62
|
return type.constructor._size;
|
|
63
63
|
}
|
|
64
|
+
// Structure/Union instance (Python: sizeof(instance))
|
|
65
|
+
if (type && typeof type === "object" && type._structDef !== undefined && typeof type._structDef.size === "number") {
|
|
66
|
+
return type._structDef.size;
|
|
67
|
+
}
|
|
68
|
+
// Buffer, create_string_buffer() o istanza di array: dimensione in byte
|
|
69
|
+
if (Buffer.isBuffer(type)) {
|
|
70
|
+
return type.byteLength;
|
|
71
|
+
}
|
|
64
72
|
// Structure class
|
|
65
73
|
if (typeof type === "function" && type.prototype instanceof getStructure()) {
|
|
66
74
|
const def = type._structDef || type._buildStruct();
|
|
@@ -76,9 +84,13 @@ export function createMemoryOps(deps) {
|
|
|
76
84
|
return type.size;
|
|
77
85
|
}
|
|
78
86
|
// Array type wrapper
|
|
79
|
-
if (typeof type === "object" && type !== null && typeof type.getSize === "function") {
|
|
87
|
+
if ((typeof type === "object" || (typeof type === "function" && type._isArrayType === true)) && type !== null && typeof type.getSize === "function") {
|
|
80
88
|
return type.getSize();
|
|
81
89
|
}
|
|
90
|
+
// CFUNCTYPE type: function pointer
|
|
91
|
+
if (typeof type === "function" && type._isFuncPtr === true) {
|
|
92
|
+
return deps.native.POINTER_SIZE;
|
|
93
|
+
}
|
|
82
94
|
throw new TypeError("sizeof: unsupported type. Use SimpleCData classes like c_int32, c_uint64, etc.");
|
|
83
95
|
}
|
|
84
96
|
|
|
@@ -86,23 +98,32 @@ export function createMemoryOps(deps) {
|
|
|
86
98
|
* Legge un valore tipato da buffer o da address raw.
|
|
87
99
|
* Python: analogo a dereferenziare `pointer.contents`.
|
|
88
100
|
*/
|
|
101
|
+
// Un oggetto puntatore (POINTER(T)) vale il suo Buffer o il suo indirizzo:
|
|
102
|
+
// es. gli argomenti POINTER dei callback passati a readValue/writeValue.
|
|
103
|
+
const pointerTarget = (ptr) => (ptr._buffer !== null ? ptr._buffer : ptr.address);
|
|
104
|
+
|
|
89
105
|
function readValue(ptr, type, offset = 0) {
|
|
90
106
|
if (typeof offset !== "number" || offset < 0) {
|
|
91
107
|
throw new RangeError("offset must be a non-negative number");
|
|
92
108
|
}
|
|
109
|
+
if (ptr !== null && typeof ptr === "object" && ptr._pointerType !== undefined) {
|
|
110
|
+
ptr = pointerTarget(ptr);
|
|
111
|
+
}
|
|
93
112
|
|
|
94
113
|
// SimpleCData class: usa _reader diretto
|
|
95
114
|
if (typeof type === "function" && type._isSimpleCData) {
|
|
96
115
|
if (Buffer.isBuffer(ptr)) {
|
|
97
116
|
const size = type._size || sizeof(type);
|
|
98
117
|
if (offset + size > ptr.length) {
|
|
99
|
-
throw new RangeError(
|
|
100
|
-
`Read would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`,
|
|
101
|
-
);
|
|
118
|
+
throw new RangeError(`Read would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`);
|
|
102
119
|
}
|
|
103
120
|
return type._reader(ptr, offset);
|
|
104
121
|
}
|
|
105
122
|
if (typeof ptr === "bigint" || typeof ptr === "number") {
|
|
123
|
+
const nativeType = deps.nativeReadTypes !== undefined ? deps.nativeReadTypes.get(type) : undefined;
|
|
124
|
+
if (nativeType !== undefined && ptr !== 0n && ptr !== 0) {
|
|
125
|
+
return deps.native.readValue(ptr, nativeType, offset);
|
|
126
|
+
}
|
|
106
127
|
const size = type._size || sizeof(type);
|
|
107
128
|
const buf = ptrToBuffer(ptr, size + offset);
|
|
108
129
|
return type._reader(buf, offset);
|
|
@@ -135,6 +156,12 @@ export function createMemoryOps(deps) {
|
|
|
135
156
|
if (typeof offset !== "number" || offset < 0) {
|
|
136
157
|
throw new RangeError("offset must be a non-negative number");
|
|
137
158
|
}
|
|
159
|
+
if (ptr !== null && typeof ptr === "object" && ptr._pointerType !== undefined) {
|
|
160
|
+
ptr = pointerTarget(ptr);
|
|
161
|
+
if (typeof ptr === "bigint") {
|
|
162
|
+
ptr = ptrToBuffer(ptr, offset + sizeof(type));
|
|
163
|
+
}
|
|
164
|
+
}
|
|
138
165
|
|
|
139
166
|
// SimpleCData class: usa _writer diretto
|
|
140
167
|
if (typeof type === "function" && type._isSimpleCData) {
|
|
@@ -143,9 +170,7 @@ export function createMemoryOps(deps) {
|
|
|
143
170
|
}
|
|
144
171
|
const size = type._size || sizeof(type);
|
|
145
172
|
if (offset + size > ptr.length) {
|
|
146
|
-
throw new RangeError(
|
|
147
|
-
`Write would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`,
|
|
148
|
-
);
|
|
173
|
+
throw new RangeError(`Write would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`);
|
|
149
174
|
}
|
|
150
175
|
type._writer(ptr, offset, value);
|
|
151
176
|
return type._size;
|
package/lib/memory/pointer.js
CHANGED
|
@@ -26,6 +26,8 @@
|
|
|
26
26
|
* ```
|
|
27
27
|
*/
|
|
28
28
|
|
|
29
|
+
import { writePointerField } from "../structures/helpers/common.js";
|
|
30
|
+
|
|
29
31
|
/**
|
|
30
32
|
* Gets the memory address of a buffer or pointer.
|
|
31
33
|
*
|
|
@@ -53,8 +55,10 @@
|
|
|
53
55
|
* ```
|
|
54
56
|
*/
|
|
55
57
|
export function addressOf(ptr, alloc, native) {
|
|
56
|
-
// Object wrapper (SimpleCData, Structure, Union, array proxy) → unwrap al Buffer
|
|
57
|
-
|
|
58
|
+
// Object wrapper (SimpleCData, Structure, Union, array proxy) → unwrap al Buffer.
|
|
59
|
+
// Le istanze di array sono Proxy su un Buffer: Buffer.isBuffer() è vero in JS
|
|
60
|
+
// ma il nativo non vede un Buffer, quindi si usa sempre `_buffer` se presente.
|
|
61
|
+
if (ptr && typeof ptr === "object" && Buffer.isBuffer(ptr._buffer)) {
|
|
58
62
|
ptr = ptr._buffer;
|
|
59
63
|
}
|
|
60
64
|
if (Buffer.isBuffer(ptr)) {
|
|
@@ -298,6 +302,17 @@ export function ptrToBuffer(address, size, native) {
|
|
|
298
302
|
return native.ptrToBuffer(address, size);
|
|
299
303
|
}
|
|
300
304
|
|
|
305
|
+
// Indice per chiavi composte solo da cifre ("0", "12"); -1 altrimenti.
|
|
306
|
+
// Equivale a /^\d+$/ + parseInt senza eseguire una regex ad ogni accesso.
|
|
307
|
+
function digitIndex(prop) {
|
|
308
|
+
if (typeof prop !== "string" || prop.length === 0) return -1;
|
|
309
|
+
for (let i = 0; i < prop.length; i++) {
|
|
310
|
+
const c = prop.charCodeAt(i);
|
|
311
|
+
if (c < 48 || c > 57) return -1;
|
|
312
|
+
}
|
|
313
|
+
return parseInt(prop, 10);
|
|
314
|
+
}
|
|
315
|
+
|
|
301
316
|
/**
|
|
302
317
|
* Creates a POINTER type for a base type.
|
|
303
318
|
*
|
|
@@ -365,7 +380,9 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
365
380
|
typeof baseType._buildStruct !== "function" &&
|
|
366
381
|
typeof baseType._buildUnion !== "function" &&
|
|
367
382
|
!baseType._pointerTo &&
|
|
368
|
-
!baseType._isStructType
|
|
383
|
+
!baseType._isStructType &&
|
|
384
|
+
!baseType._isArrayType &&
|
|
385
|
+
!baseType._isFuncPtr;
|
|
369
386
|
|
|
370
387
|
// Se non è thunk, `baseType` rimane il valore passato e `baseSize` è
|
|
371
388
|
// calcolabile subito. Se è thunk, entrambi vengono rimpiazzati al primo
|
|
@@ -390,9 +407,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
390
407
|
baseSize = typeof baseType === "object" ? baseType.size : sizeof(baseType);
|
|
391
408
|
}
|
|
392
409
|
|
|
393
|
-
const typeName = isLazyThunk
|
|
394
|
-
? "lazy"
|
|
395
|
-
: typeof baseType === "object" ? "struct" : baseType._type || baseType.name || "unknown";
|
|
410
|
+
const typeName = isLazyThunk ? "lazy" : typeof baseType === "object" ? "struct" : baseType._type || baseType.name || "unknown";
|
|
396
411
|
|
|
397
412
|
/**
|
|
398
413
|
* Helper to get buffer's memory address using native writeValue
|
|
@@ -406,6 +421,46 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
406
421
|
return BigInt(tempBuf.readUInt32LE(0));
|
|
407
422
|
}
|
|
408
423
|
|
|
424
|
+
// Python: per tipi semplici e Structure/Union `contents` (e p[i] per le struct)
|
|
425
|
+
// è un'istanza viva sulla memoria puntata, non una copia del valore.
|
|
426
|
+
const hasInstances = () => typeof baseType === "function" && (baseType._isSimpleCData === true || typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function");
|
|
427
|
+
const isStructBase = () => typeof baseType === "function" && (typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function");
|
|
428
|
+
|
|
429
|
+
// POINTER(POINTER(T)) / POINTER(CFUNCTYPE): elementi puntatore, letti come
|
|
430
|
+
// oggetto puntatore / funzione (NULL → null) e scritti come indirizzo.
|
|
431
|
+
const isPointerBase = () => (typeof baseType === "object" && baseType !== null && baseType._pointerTo !== undefined) || (typeof baseType === "function" && baseType._isFuncPtr === true);
|
|
432
|
+
|
|
433
|
+
function readPointerAt(buffer, address, offset) {
|
|
434
|
+
const inBuffer = buffer && offset + baseSize <= buffer.length;
|
|
435
|
+
const src = inBuffer ? buffer : native.ptrToBuffer(address + BigInt(offset), baseSize);
|
|
436
|
+
const off = inBuffer ? offset : 0;
|
|
437
|
+
const target = baseSize === 8 ? src.readBigUInt64LE(off) : BigInt(src.readUInt32LE(off));
|
|
438
|
+
if (target === 0n) return null;
|
|
439
|
+
return typeof baseType === "function" ? baseType(target) : baseType.fromAddress(target);
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
function writePointerAt(buffer, address, offset, value) {
|
|
443
|
+
const inBuffer = buffer && offset + baseSize <= buffer.length;
|
|
444
|
+
writePointerField(inBuffer ? buffer : native.ptrToBuffer(address + BigInt(offset), baseSize), inBuffer ? offset : 0, value, baseSize);
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
function instanceAt(buffer, address, offset) {
|
|
448
|
+
if (buffer && offset + baseSize <= buffer.length) {
|
|
449
|
+
return baseType.from_buffer(buffer, offset);
|
|
450
|
+
}
|
|
451
|
+
return baseType.from_address(address + BigInt(offset));
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
// Lettura a un indirizzo senza Buffer associato: per le primitive
|
|
455
|
+
// readValue(indirizzo) evita il Buffer esterno di ptrToBuffer.
|
|
456
|
+
function readAtAddress(addr) {
|
|
457
|
+
if (typeof baseType === "function" && baseType._isSimpleCData) {
|
|
458
|
+
return readValue(addr, baseType, 0);
|
|
459
|
+
}
|
|
460
|
+
const buf = native.ptrToBuffer(addr, baseSize);
|
|
461
|
+
return readValue(buf, baseType, 0);
|
|
462
|
+
}
|
|
463
|
+
|
|
409
464
|
/**
|
|
410
465
|
* Creates a pointer instance with Python ctypes-compatible API.
|
|
411
466
|
* Supports .contents property and [index] access for pointer arithmetic.
|
|
@@ -443,27 +498,41 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
443
498
|
},
|
|
444
499
|
|
|
445
500
|
/**
|
|
446
|
-
* Python ctypes compatible:
|
|
447
|
-
*
|
|
501
|
+
* Python ctypes compatible: the pointed object. For simple types and
|
|
502
|
+
* Structure/Union classes it is a live instance on the pointed memory
|
|
503
|
+
* (`p.contents.value`, `p.contents.x`); assigning an instance re-points
|
|
504
|
+
* the pointer to it, assigning a plain value writes it.
|
|
448
505
|
*/
|
|
449
506
|
get contents() {
|
|
450
507
|
if (_address === 0n && !_buffer) {
|
|
451
508
|
throw new Error("NULL pointer access");
|
|
452
509
|
}
|
|
510
|
+
if (isPointerBase()) {
|
|
511
|
+
return readPointerAt(_buffer, _address, 0);
|
|
512
|
+
}
|
|
513
|
+
if (hasInstances()) {
|
|
514
|
+
return instanceAt(_buffer, _address, 0);
|
|
515
|
+
}
|
|
453
516
|
if (_buffer) {
|
|
454
517
|
// We have the actual buffer, read from it
|
|
455
518
|
return readValue(_buffer, baseType, 0);
|
|
456
519
|
}
|
|
457
|
-
|
|
458
|
-
const buf = native.ptrToBuffer(_address, baseSize);
|
|
459
|
-
return readValue(buf, baseType, 0);
|
|
520
|
+
return readAtAddress(_address);
|
|
460
521
|
},
|
|
461
522
|
|
|
462
523
|
set contents(value) {
|
|
524
|
+
// Python: assegnare un'istanza ri-punta il puntatore a quell'istanza.
|
|
525
|
+
if (value !== null && typeof value === "object" && (value._isSimpleCDataInstance === true || value._structDef !== undefined) && Buffer.isBuffer(value._buffer)) {
|
|
526
|
+
_buffer = value._buffer;
|
|
527
|
+
_address = getBufferAddress(value._buffer);
|
|
528
|
+
return;
|
|
529
|
+
}
|
|
463
530
|
if (_address === 0n && !_buffer) {
|
|
464
531
|
throw new Error("NULL pointer access");
|
|
465
532
|
}
|
|
466
|
-
if (
|
|
533
|
+
if (isPointerBase()) {
|
|
534
|
+
writePointerAt(_buffer, _address, 0, value);
|
|
535
|
+
} else if (_buffer) {
|
|
467
536
|
writeValue(_buffer, baseType, value, 0);
|
|
468
537
|
} else {
|
|
469
538
|
const buf = native.ptrToBuffer(_address, baseSize);
|
|
@@ -548,31 +617,41 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
548
617
|
return new Proxy(instance, {
|
|
549
618
|
get(target, prop, receiver) {
|
|
550
619
|
// Numeric index access: p[0], p[1], etc.
|
|
551
|
-
|
|
552
|
-
|
|
620
|
+
const index = digitIndex(prop);
|
|
621
|
+
if (index >= 0) {
|
|
553
622
|
if (target.isNull) {
|
|
554
623
|
throw new Error("NULL pointer access");
|
|
555
624
|
}
|
|
556
625
|
const offset = index * baseSize;
|
|
626
|
+
if (isPointerBase()) {
|
|
627
|
+
return readPointerAt(_buffer, _address, offset);
|
|
628
|
+
}
|
|
629
|
+
if (isStructBase()) {
|
|
630
|
+
return instanceAt(_buffer, _address, offset);
|
|
631
|
+
}
|
|
557
632
|
if (_buffer && offset + baseSize <= _buffer.length) {
|
|
633
|
+
if (typeof baseType === "function" && baseType._isSimpleCData) {
|
|
634
|
+
return baseType._reader(_buffer, offset);
|
|
635
|
+
}
|
|
558
636
|
return readValue(_buffer, baseType, offset);
|
|
559
637
|
}
|
|
560
|
-
|
|
561
|
-
const addr = _address + BigInt(offset);
|
|
562
|
-
const buf = native.ptrToBuffer(addr, baseSize);
|
|
563
|
-
return readValue(buf, baseType, 0);
|
|
638
|
+
return readAtAddress(_address + BigInt(offset));
|
|
564
639
|
}
|
|
565
640
|
return Reflect.get(target, prop, receiver);
|
|
566
641
|
},
|
|
567
642
|
|
|
568
643
|
set(target, prop, value, receiver) {
|
|
569
644
|
// Numeric index access: p[0] = value, p[1] = value, etc.
|
|
570
|
-
|
|
571
|
-
|
|
645
|
+
const index = digitIndex(prop);
|
|
646
|
+
if (index >= 0) {
|
|
572
647
|
if (target.isNull) {
|
|
573
648
|
throw new Error("NULL pointer access");
|
|
574
649
|
}
|
|
575
650
|
const offset = index * baseSize;
|
|
651
|
+
if (isPointerBase()) {
|
|
652
|
+
writePointerAt(_buffer, _address, offset, value);
|
|
653
|
+
return true;
|
|
654
|
+
}
|
|
576
655
|
if (_buffer && offset + baseSize <= _buffer.length) {
|
|
577
656
|
writeValue(_buffer, baseType, value, offset);
|
|
578
657
|
return true;
|
|
@@ -595,8 +674,14 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
595
674
|
// Getter dinamici: se `baseType` è un thunk, viene risolto al primo
|
|
596
675
|
// accesso — così l'uso come `POINTER(() => Node)` in field type resta
|
|
597
676
|
// Python-compatibile senza forzare l'utente a invalidare manualmente.
|
|
598
|
-
get _pointerTo() {
|
|
599
|
-
|
|
677
|
+
get _pointerTo() {
|
|
678
|
+
resolveIfLazy();
|
|
679
|
+
return baseType;
|
|
680
|
+
},
|
|
681
|
+
get _baseSize() {
|
|
682
|
+
resolveIfLazy();
|
|
683
|
+
return baseSize;
|
|
684
|
+
},
|
|
600
685
|
size: native.POINTER_SIZE,
|
|
601
686
|
|
|
602
687
|
/**
|
|
@@ -679,7 +764,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
679
764
|
* ```javascript
|
|
680
765
|
* const x = new c_int32(42);
|
|
681
766
|
* const p = pointer(x);
|
|
682
|
-
* console.log(p.contents); // 42
|
|
767
|
+
* console.log(p.contents.value); // 42
|
|
683
768
|
* p.contents = 100;
|
|
684
769
|
* console.log(x.value); // 100
|
|
685
770
|
* ```
|
|
@@ -699,9 +784,8 @@ export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c
|
|
|
699
784
|
// SimpleCData instance - use the class itself (c_int32, c_double, etc.)
|
|
700
785
|
baseType = obj.constructor;
|
|
701
786
|
} else if (obj._structDef) {
|
|
702
|
-
// Structure/Union instance
|
|
703
|
-
|
|
704
|
-
baseType = obj._structDef;
|
|
787
|
+
// Structure/Union instance: the class, so `.contents` is an instance of it (Python parity)
|
|
788
|
+
baseType = typeof obj.constructor === "function" && obj.constructor._fields_ !== undefined ? obj.constructor : obj._structDef;
|
|
705
789
|
} else {
|
|
706
790
|
baseType = c_void_p;
|
|
707
791
|
}
|
package/lib/platform/errors.js
CHANGED
|
@@ -120,3 +120,23 @@ export function WinError(code, WinDLL, alloc, c_uint32, c_void, c_void_p) {
|
|
|
120
120
|
err.winerror = code;
|
|
121
121
|
return err;
|
|
122
122
|
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Raised when a foreign function call cannot convert one of the passed
|
|
126
|
+
* arguments (Python ctypes `ctypes.ArgumentError`). Subclass of `TypeError`.
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
* ```javascript
|
|
130
|
+
* try {
|
|
131
|
+
* abs("12");
|
|
132
|
+
* } catch (e) {
|
|
133
|
+
* if (e instanceof ArgumentError) console.log(e.message); // "argument 1: TypeError: ..."
|
|
134
|
+
* }
|
|
135
|
+
* ```
|
|
136
|
+
*/
|
|
137
|
+
export class ArgumentError extends TypeError {
|
|
138
|
+
constructor(message) {
|
|
139
|
+
super(message);
|
|
140
|
+
this.name = "ArgumentError";
|
|
141
|
+
}
|
|
142
|
+
}
|