node-ctypes 2.2.0 → 2.3.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 +71 -13
- 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 +86 -76
- package/lib/core/callback.js +10 -17
- package/lib/core/conversions.js +172 -4
- package/lib/core/funcptr.js +63 -46
- package/lib/core/lazy-loader.js +10 -4
- package/lib/core/types.js +196 -98
- package/lib/index.d.ts +163 -35
- package/lib/index.js +36 -26
- package/lib/memory/buffer.js +45 -16
- package/lib/memory/operations.js +55 -43
- package/lib/memory/pointer.js +135 -26
- package/lib/platform/constants.js +0 -1
- package/lib/platform/errors.js +48 -4
- package/lib/platform/find_library.js +78 -19
- package/lib/structures/Structure.js +258 -178
- package/lib/structures/Union.js +10 -21
- package/lib/structures/helpers/array.js +71 -4
- package/lib/structures/helpers/bitfield.js +66 -150
- package/lib/structures/helpers/common.js +115 -15
- package/lib/structures/helpers/layout.js +131 -0
- package/lib/structures/helpers/struct.js +142 -400
- package/lib/structures/helpers/union.js +130 -141
- package/lib/structures/helpers/wrap.js +3 -15
- package/lib/types/primitives.js +130 -101
- package/package.json +2 -1
package/lib/core/types.js
CHANGED
|
@@ -14,19 +14,90 @@
|
|
|
14
14
|
*
|
|
15
15
|
* - SimpleCData primitives (c_int32, ecc.)
|
|
16
16
|
* - POINTER
|
|
17
|
-
* - Bitfield:
|
|
18
|
-
*
|
|
19
|
-
*
|
|
17
|
+
* - Bitfield: i byte che contengono bitfield diventano campi uint8 agli
|
|
18
|
+
* offset del layout JS (con gcc-sysv un bitfield può condividere byte con
|
|
19
|
+
* altri campi, e un unico tipo per "cella" non riprodurrebbe gli offset).
|
|
20
|
+
* - Campi disallineati (`_pack_`): byte uint8 agli offset del layout JS.
|
|
20
21
|
* - Array: sia `array(SimpleCData, N)` sia `array(Structure/Union, N)`;
|
|
21
22
|
* per il secondo caso il native ArrayType è costruito lazy qui.
|
|
22
23
|
* - Nested Structure/Union (anche `_anonymous_`): ricorsione.
|
|
24
|
+
* - Classe base (Python: sottoclasse con _fields_): primo campo, come in C.
|
|
25
|
+
*
|
|
26
|
+
* Dimensione e allineamento sono quelli del layout JS (layout.js, `_align_`).
|
|
23
27
|
*/
|
|
24
28
|
|
|
29
|
+
// ArrayType nativi costruiti per gli array di Structure/Union (gli array JS
|
|
30
|
+
// espongono `_native` in sola lettura).
|
|
31
|
+
const nativeArrayTypes = new WeakMap();
|
|
32
|
+
|
|
33
|
+
// ArrayType nativi uint8[n] per i byte emessi come tali (vedi sotto).
|
|
34
|
+
const byteArrayTypes = new Map();
|
|
35
|
+
|
|
36
|
+
function byteRun(st, native, offset, length) {
|
|
37
|
+
if (length <= 0) return;
|
|
38
|
+
if (length === 1) {
|
|
39
|
+
st.addField(`__byte@${offset}`, native.CType.UINT8);
|
|
40
|
+
return;
|
|
41
|
+
}
|
|
42
|
+
let arrayType = byteArrayTypes.get(length);
|
|
43
|
+
if (arrayType === undefined) {
|
|
44
|
+
arrayType = new native.ArrayType(native.CType.UINT8, length);
|
|
45
|
+
byteArrayTypes.set(length, arrayType);
|
|
46
|
+
}
|
|
47
|
+
st.addField(`__bytes@${offset}`, arrayType);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const roundUp = (n, a) => Math.ceil(n / a) * a;
|
|
51
|
+
|
|
52
|
+
// Byte toccati da un bitfield (dentro la sua unità di `baseSize` byte).
|
|
53
|
+
function bitFieldBytes(f) {
|
|
54
|
+
const first = Math.floor(f.bitOffset / 8);
|
|
55
|
+
const last = Math.floor((f.bitOffset + f.bitSize - 1) / 8);
|
|
56
|
+
const bytes = [];
|
|
57
|
+
for (let b = first; b <= last; b++) {
|
|
58
|
+
bytes.push(f.offset + (f.swapped ? f.baseSize - 1 - b : b));
|
|
59
|
+
}
|
|
60
|
+
return bytes;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const nestedDefOf = (f) => {
|
|
64
|
+
if (f.isNested) return typeof f.type === "function" ? f.type._structDef || f.type._buildStruct?.() : f.type;
|
|
65
|
+
const element = f.isArray ? f.type?.elementType : undefined;
|
|
66
|
+
if (typeof element === "function" && typeof element._buildStruct === "function") return element._structDef || element._buildStruct();
|
|
67
|
+
return undefined;
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
// Campi (anche di struct annidate) a un offset non multiplo del loro
|
|
71
|
+
// allineamento C, come con `_pack_`: l'ABI x86-64 System V passa queste struct
|
|
72
|
+
// in memoria (vedi StructInfo::SetMemoryClass).
|
|
73
|
+
const unalignedDefs = new WeakMap();
|
|
74
|
+
function hasUnalignedFields(def) {
|
|
75
|
+
let result = unalignedDefs.get(def);
|
|
76
|
+
if (result === undefined) {
|
|
77
|
+
result = def.fields.some((f) => {
|
|
78
|
+
if (f.isBitField) return false;
|
|
79
|
+
if (!def.isUnion && f.offset % (f.naturalAlignment ?? f.alignment) !== 0) return true;
|
|
80
|
+
const nested = nestedDefOf(f);
|
|
81
|
+
return nested !== undefined && hasUnalignedFields(nested);
|
|
82
|
+
});
|
|
83
|
+
unalignedDefs.set(def, result);
|
|
84
|
+
}
|
|
85
|
+
return result;
|
|
86
|
+
}
|
|
87
|
+
|
|
25
88
|
/**
|
|
26
89
|
* Costruisce (o recupera cached) un native `StructType` corrispondente a un
|
|
27
90
|
* structDef/unionDef. Cacheato su `def._nativeStructType` per evitare
|
|
28
91
|
* ricostruzioni multiple sulla stessa def.
|
|
29
92
|
*
|
|
93
|
+
* La struct nativa ha gli offset, la dimensione e l'allineamento del layout
|
|
94
|
+
* JS (layout.js, `_pack_`, `_align_`, bitfield). Un campo resta del suo tipo
|
|
95
|
+
* (che conta per la classificazione dell'ABI: float/double vanno nei registri
|
|
96
|
+
* SSE) quando nella struct nativa cade allo stesso offset: offset allineato al
|
|
97
|
+
* suo allineamento C, non superiore a quello della struct. Altrimenti (campi
|
|
98
|
+
* disallineati da `_pack_`, byte dei bitfield) i suoi byte diventano uint8. Il
|
|
99
|
+
* padding non è emesso, se non prima di byte da collocare all'offset giusto.
|
|
100
|
+
*
|
|
30
101
|
* @param {Object} def - structDef o unionDef (output di `struct()`/`union()`
|
|
31
102
|
* o `_structDef` di una Structure class).
|
|
32
103
|
* @param {Object} native - modulo native (`require('ctypes.node')`).
|
|
@@ -35,109 +106,134 @@
|
|
|
35
106
|
*/
|
|
36
107
|
function _buildNativeStructType(def, native) {
|
|
37
108
|
if (def._nativeStructType) return def._nativeStructType;
|
|
38
|
-
const st = new native.StructType({ union: !!def.isUnion });
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
const cellKey = `${f.offset}:${f.baseSize}`;
|
|
61
|
-
if (emittedBitfieldCells.has(cellKey)) continue; // già emesso da un bitfield precedente nella stessa cell
|
|
62
|
-
emittedBitfieldCells.add(cellKey);
|
|
63
|
-
// Determina il CType del base type (es. c_uint32 → CType.UINT32).
|
|
64
|
-
// f.type è la SimpleCData class del base.
|
|
65
|
-
if (!f.type || typeof f.type._type !== "number") {
|
|
66
|
-
throw new Error(`Bitfield '${f.name}': base type senza _type numerico`);
|
|
67
|
-
}
|
|
68
|
-
// Usa un nome sintetico per la cell (non accessibile via field map —
|
|
69
|
-
// i bitfield individuali conservano i loro nomi e accedono al buffer
|
|
70
|
-
// direttamente via fieldReaders/fieldWriters precompilati).
|
|
71
|
-
const cellName = `__bitfield@${f.offset}`;
|
|
72
|
-
st.addField(cellName, f.type._type);
|
|
73
|
-
continue;
|
|
109
|
+
const st = new native.StructType({ union: !!def.isUnion, alignment: def.alignment, memoryClass: hasUnalignedFields(def) });
|
|
110
|
+
const fits = (alignment, offset) => alignment <= def.alignment && offset % alignment === 0;
|
|
111
|
+
|
|
112
|
+
// La classe base è il primo membro della struct (i suoi campi sono i primi
|
|
113
|
+
// di def.fields, agli stessi offset).
|
|
114
|
+
let fields = def.fields;
|
|
115
|
+
let position = 0;
|
|
116
|
+
if (def.base) {
|
|
117
|
+
if (fits(def.base.alignment, 0)) st.addField("__base__", _buildNativeStructType(def.base, native));
|
|
118
|
+
else byteRun(st, native, 0, def.base.size);
|
|
119
|
+
fields = def.fields.slice(def.base.fields.length);
|
|
120
|
+
position = def.isUnion ? 0 : def.base.size;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
if (def.isUnion) {
|
|
124
|
+
for (const f of fields) {
|
|
125
|
+
const size = f.isBitField ? f.baseSize : f.size;
|
|
126
|
+
const alignment = f.naturalAlignment ?? f.alignment;
|
|
127
|
+
if (!fits(alignment, 0)) byteRun(st, native, 0, size);
|
|
128
|
+
// Un bitfield occupa il proprio tipo base all'offset 0.
|
|
129
|
+
else if (f.isBitField) st.addField(`__bitfield_${f.name}`, bitFieldBaseType(f));
|
|
130
|
+
else addNativeField(st, f, native);
|
|
74
131
|
}
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
f.type._native.constructor?.name === "ArrayType";
|
|
83
|
-
if (native_is_array_type) {
|
|
84
|
-
st.addField(f.name, f.type._native, f.isAnonymous ? { anonymous: true } : undefined);
|
|
85
|
-
continue;
|
|
86
|
-
}
|
|
87
|
-
// Caso 2: lo shim JS ha Structure/Union come elementType. Costruiamo
|
|
88
|
-
// qui (lazy) un native ArrayType col native StructType dell'element.
|
|
89
|
-
// Questo abilita struct-by-value con array-of-struct fields.
|
|
90
|
-
const elementType = f.type?.elementType;
|
|
91
|
-
const count = f.type?.length;
|
|
92
|
-
if (elementType && typeof count === "number" &&
|
|
93
|
-
typeof elementType === "function" &&
|
|
94
|
-
(typeof elementType._buildStruct === "function" ||
|
|
95
|
-
typeof elementType._buildUnion === "function")) {
|
|
96
|
-
const elemDef = elementType._structDef || elementType._unionDef ||
|
|
97
|
-
elementType._buildStruct?.() || elementType._buildUnion?.();
|
|
98
|
-
const elemNative = _buildNativeStructType(elemDef, native);
|
|
99
|
-
const arrNative = new native.ArrayType(elemNative, count);
|
|
100
|
-
st.addField(f.name, arrNative, f.isAnonymous ? { anonymous: true } : undefined);
|
|
101
|
-
// Promuovi il native sullo shim per evitare ricostruzioni future.
|
|
102
|
-
f.type._native = arrNative;
|
|
103
|
-
continue;
|
|
104
|
-
}
|
|
105
|
-
throw new Error(
|
|
106
|
-
`Field '${f.name}': array-in-struct-by-value non riconosciuto. ` +
|
|
107
|
-
`Tipi supportati: array(SimpleCData, N), array(Structure/Union subclass, N). ` +
|
|
108
|
-
`Alternativa: passa la struct per puntatore.`,
|
|
109
|
-
);
|
|
132
|
+
} else {
|
|
133
|
+
// Campi e byte dei bitfield in ordine di offset.
|
|
134
|
+
const items = [];
|
|
135
|
+
const bitBytes = new Set();
|
|
136
|
+
for (const f of fields) {
|
|
137
|
+
if (f.isBitField) bitFieldBytes(f).forEach((b) => bitBytes.add(b));
|
|
138
|
+
else if (f.size > 0) items.push({ offset: f.offset, size: f.size, field: f });
|
|
110
139
|
}
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
140
|
+
for (const b of bitBytes) items.push({ offset: b, size: 1, field: null });
|
|
141
|
+
items.sort((a, b) => a.offset - b.offset);
|
|
142
|
+
|
|
143
|
+
let bytesFrom = -1; // inizio della sequenza di byte in corso
|
|
144
|
+
const flushBytes = () => {
|
|
145
|
+
if (bytesFrom >= 0) byteRun(st, native, bytesFrom, position - bytesFrom);
|
|
146
|
+
bytesFrom = -1;
|
|
147
|
+
};
|
|
148
|
+
const addBytes = (offset, size) => {
|
|
149
|
+
if (bytesFrom < 0) bytesFrom = position;
|
|
150
|
+
position = offset + size;
|
|
151
|
+
};
|
|
152
|
+
|
|
153
|
+
for (const { offset, size, field } of items) {
|
|
154
|
+
if (offset < position) continue; // byte già coperto
|
|
155
|
+
const alignment = field ? (field.naturalAlignment ?? field.alignment) : 1;
|
|
156
|
+
if (field && fits(alignment, offset)) {
|
|
157
|
+
// Il padding naturale prima del campo resta padding; un vuoto più
|
|
158
|
+
// grande (es. `_align_` di una struct annidata) diventa byte.
|
|
159
|
+
if (roundUp(position, alignment) !== offset) addBytes(offset, 0);
|
|
160
|
+
flushBytes();
|
|
161
|
+
addNativeField(st, field, native);
|
|
162
|
+
position = offset + size;
|
|
163
|
+
} else {
|
|
164
|
+
addBytes(offset, size);
|
|
120
165
|
}
|
|
121
|
-
const nestedNative = _buildNativeStructType(nestedDef, native);
|
|
122
|
-
st.addField(f.name, nestedNative, f.isAnonymous ? { anonymous: true } : undefined);
|
|
123
|
-
continue;
|
|
124
|
-
}
|
|
125
|
-
if (f.isPointer) {
|
|
126
|
-
st.addField(f.name, native.CType.POINTER);
|
|
127
|
-
continue;
|
|
128
|
-
}
|
|
129
|
-
// SimpleCData class: usa il suo _type numerico.
|
|
130
|
-
if (f.type && typeof f.type === "function" && f.type._isSimpleCData) {
|
|
131
|
-
st.addField(f.name, f.type._type);
|
|
132
|
-
continue;
|
|
133
166
|
}
|
|
134
|
-
|
|
167
|
+
flushBytes();
|
|
168
|
+
// Coda oltre l'arrotondamento all'allineamento (non accade con i layout
|
|
169
|
+
// di layout.js, ma la dimensione deve comunque coincidere).
|
|
170
|
+
if (roundUp(position, def.alignment) < def.size) byteRun(st, native, position, def.size - position);
|
|
135
171
|
}
|
|
136
172
|
|
|
173
|
+
const size = st.getSize();
|
|
174
|
+
if (size !== def.size || st.getAlignment() !== def.alignment) {
|
|
175
|
+
throw new Error(`Native layout of the structure (size ${size}, alignment ${st.getAlignment()}) differs from its definition (size ${def.size}, alignment ${def.alignment})`);
|
|
176
|
+
}
|
|
137
177
|
def._nativeStructType = st;
|
|
138
178
|
return st;
|
|
139
179
|
}
|
|
140
180
|
|
|
181
|
+
function bitFieldBaseType(f) {
|
|
182
|
+
if (!f.type || typeof f.type._type !== "number") {
|
|
183
|
+
throw new Error(`Bitfield '${f.name}': base type senza _type numerico`);
|
|
184
|
+
}
|
|
185
|
+
return f.type._type;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
function addNativeField(st, f, native) {
|
|
189
|
+
const options = f.isAnonymous ? { anonymous: true } : undefined;
|
|
190
|
+
if (f.isArray) {
|
|
191
|
+
// Array di primitive (o di struct native): `_native` è già un ArrayType.
|
|
192
|
+
const own = f.type?._native;
|
|
193
|
+
if (own && typeof own.getSize === "function" && own.constructor?.name === "ArrayType") {
|
|
194
|
+
st.addField(f.name, own, options);
|
|
195
|
+
return;
|
|
196
|
+
}
|
|
197
|
+
// Array di Structure/Union: ArrayType nativo costruito qui (una volta per tipo).
|
|
198
|
+
const elementType = f.type?.elementType;
|
|
199
|
+
const count = f.type?.length;
|
|
200
|
+
const elemDef = typeof elementType === "function" && typeof elementType._buildStruct === "function" ? elementType._structDef || elementType._buildStruct() : elementType?._isStructType === true ? elementType : undefined;
|
|
201
|
+
if (elemDef !== undefined && typeof count === "number") {
|
|
202
|
+
let arrNative = nativeArrayTypes.get(f.type);
|
|
203
|
+
if (arrNative === undefined) {
|
|
204
|
+
arrNative = new native.ArrayType(_buildNativeStructType(elemDef, native), count);
|
|
205
|
+
nativeArrayTypes.set(f.type, arrNative);
|
|
206
|
+
}
|
|
207
|
+
st.addField(f.name, arrNative, options);
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
throw new Error(`Field '${f.name}': array-in-struct-by-value non riconosciuto. ` + `Tipi supportati: array(SimpleCData, N), array(Structure/Union subclass o struct()/union(), N). ` + `Alternativa: passa la struct per puntatore.`);
|
|
211
|
+
}
|
|
212
|
+
if (f.isNested) {
|
|
213
|
+
// f.type è un structDef/unionDef (quando dichiarato via struct/union)
|
|
214
|
+
// o una Structure/Union class (quando dichiarato con class extends).
|
|
215
|
+
let nestedDef = f.type;
|
|
216
|
+
if (typeof f.type === "function") {
|
|
217
|
+
nestedDef = f.type._structDef || f.type._buildStruct?.();
|
|
218
|
+
}
|
|
219
|
+
if (!nestedDef || !Array.isArray(nestedDef.fields)) {
|
|
220
|
+
throw new Error(`Field '${f.name}': nested type non riconosciuto`);
|
|
221
|
+
}
|
|
222
|
+
st.addField(f.name, _buildNativeStructType(nestedDef, native), options);
|
|
223
|
+
return;
|
|
224
|
+
}
|
|
225
|
+
if (f.isPointer) {
|
|
226
|
+
st.addField(f.name, native.CType.POINTER);
|
|
227
|
+
return;
|
|
228
|
+
}
|
|
229
|
+
// SimpleCData class: usa il suo _type numerico.
|
|
230
|
+
if (f.type && typeof f.type === "function" && f.type._isSimpleCData) {
|
|
231
|
+
st.addField(f.name, f.type._type);
|
|
232
|
+
return;
|
|
233
|
+
}
|
|
234
|
+
throw new Error(`Field '${f.name}': tipo non riconosciuto durante _buildNativeStructType`);
|
|
235
|
+
}
|
|
236
|
+
|
|
141
237
|
/**
|
|
142
238
|
* Normalizza un tipo singolo nel formato atteso dal native FFIFunction.
|
|
143
239
|
*
|
|
@@ -204,9 +300,11 @@ export function _toNativeReturnType(type, native) {
|
|
|
204
300
|
}
|
|
205
301
|
|
|
206
302
|
/**
|
|
207
|
-
* Normalizza un array di tipi (batch). Non-array → pass-through.
|
|
303
|
+
* Normalizza un array di tipi di argomento (batch). Non-array → pass-through.
|
|
304
|
+
* Un tipo array come argomento è un puntatore, come in C e Python
|
|
305
|
+
* (`argtypes = [c_int * 4]` passa l'indirizzo dell'array).
|
|
208
306
|
*/
|
|
209
307
|
export function _toNativeTypes(types, native) {
|
|
210
308
|
if (!Array.isArray(types)) return types;
|
|
211
|
-
return types.map((type) => _toNativeType(type, native));
|
|
309
|
+
return types.map((type) => (type && (typeof type === "object" || typeof type === "function") && type._isArrayType === true ? native.CType.POINTER : _toNativeType(type, native)));
|
|
212
310
|
}
|