node-ctypes 2.2.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.
- package/CHANGELOG.md +932 -0
- package/README.md +504 -99
- 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 +136 -109
- package/lib/core/callback.js +17 -20
- package/lib/core/conversions.js +376 -16
- package/lib/core/funcptr.js +148 -73
- package/lib/core/lazy-loader.js +10 -4
- package/lib/core/types.js +201 -98
- package/lib/index.d.ts +276 -83
- package/lib/index.js +44 -32
- package/lib/memory/buffer.js +82 -22
- package/lib/memory/operations.js +55 -45
- package/lib/memory/pointer.js +233 -57
- package/lib/platform/constants.js +0 -1
- package/lib/platform/errors.js +48 -4
- package/lib/platform/find_library.js +78 -19
- package/lib/platform/win_types.js +8 -3
- package/lib/structures/Structure.js +252 -203
- package/lib/structures/Union.js +10 -21
- package/lib/structures/helpers/array.js +102 -16
- package/lib/structures/helpers/bitfield.js +75 -150
- package/lib/structures/helpers/common.js +310 -21
- package/lib/structures/helpers/layout.js +145 -0
- package/lib/structures/helpers/struct.js +160 -419
- package/lib/structures/helpers/union.js +154 -155
- package/lib/structures/helpers/wrap.js +3 -15
- package/lib/types/SimpleCData.js +11 -32
- package/lib/types/primitives.js +160 -113
- package/lib/utils/cache.js +34 -2
- package/package.json +4 -1
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
*
|
|
6
6
|
* This module provides the `Structure` base class that users extend to create
|
|
7
7
|
* custom struct types with automatic field management, memory layout, and
|
|
8
|
-
*
|
|
8
|
+
* field accessors on the class prototype (as Python field descriptors).
|
|
9
9
|
*
|
|
10
10
|
* **Python ctypes Compatibility**:
|
|
11
11
|
* Direct equivalent to Python's `ctypes.Structure` class with `_fields_` attribute.
|
|
@@ -65,6 +65,8 @@
|
|
|
65
65
|
*/
|
|
66
66
|
|
|
67
67
|
import { kMirrorBase, mirrorBase, mirroredAccessors, mirrorsActive } from "../memory/mirror.js";
|
|
68
|
+
import { copyInstance, fieldsOf, inDllBuffer, sourceBytes } from "./helpers/common.js";
|
|
69
|
+
import { normalizePack } from "./helpers/layout.js";
|
|
68
70
|
|
|
69
71
|
/**
|
|
70
72
|
* Creates the Structure base class with required dependencies injected.
|
|
@@ -75,128 +77,123 @@ import { kMirrorBase, mirrorBase, mirroredAccessors, mirrorsActive } from "../me
|
|
|
75
77
|
* @returns {Class} Structure base class
|
|
76
78
|
* @private
|
|
77
79
|
*/
|
|
80
|
+
function isPlainObject(value) {
|
|
81
|
+
const proto = Object.getPrototypeOf(value);
|
|
82
|
+
return proto === Object.prototype || proto === null;
|
|
83
|
+
}
|
|
84
|
+
|
|
78
85
|
export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
79
86
|
// Buffer dell'istanza, letto dall'handler condiviso. Chiave privata e non
|
|
80
87
|
// `__buffer`, così riassegnare `__buffer` non cambia i campi (come prima).
|
|
81
88
|
const kBuffer = Symbol("buffer");
|
|
89
|
+
// Definizione (layout) propria di ogni classe, vedi `static get _structDef`.
|
|
90
|
+
const kStructDef = Symbol("structDef");
|
|
91
|
+
|
|
92
|
+
// Definizione con cui è stata creata l'istanza (layout dei suoi byte).
|
|
93
|
+
const kDef = Symbol("def");
|
|
94
|
+
// Istanze dei campi struct/union annidati, create al primo accesso: sono
|
|
95
|
+
// viste sulla memoria dell'istanza, quindi restano valide.
|
|
96
|
+
const kViews = Symbol("views");
|
|
97
|
+
// Nomi dei campi con un accessor installato da noi, per prototipo.
|
|
98
|
+
const installedNames = new WeakMap();
|
|
99
|
+
// Nomi che restano proprietà della libreria anche se usati come campi.
|
|
100
|
+
const reservedNames = new Set(["constructor", "_buffer", "__buffer", "_structDef", "__structDef"]);
|
|
101
|
+
|
|
102
|
+
// Percorso generale di un campo: istanza con un'altra definizione (creata
|
|
103
|
+
// prima di un'invalidazione del layout), copia di memoria nativa (Electron,
|
|
104
|
+
// memory/mirror.js), campi senza lettore precompilato (struct annidate,
|
|
105
|
+
// array, sotto-campi di _anonymous_).
|
|
106
|
+
function readField(inst, name) {
|
|
107
|
+
const def = inst[kDef];
|
|
108
|
+
const base = inst[kMirrorBase];
|
|
109
|
+
const read = (base !== undefined ? mirroredAccessors(def) : def).fieldReaders?.[name];
|
|
110
|
+
return read !== undefined ? read(inst[kBuffer], base) : def.get(inst[kBuffer], name);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
function writeField(inst, name, value) {
|
|
114
|
+
const def = inst[kDef];
|
|
115
|
+
const base = inst[kMirrorBase];
|
|
116
|
+
const write = (base !== undefined ? mirroredAccessors(def) : def).fieldWriters?.[name];
|
|
117
|
+
if (write !== undefined) write(inst[kBuffer], value, base);
|
|
118
|
+
else def.set(inst[kBuffer], name, value);
|
|
119
|
+
}
|
|
82
120
|
|
|
83
|
-
//
|
|
84
|
-
//
|
|
85
|
-
|
|
86
|
-
//
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
if (handler !== undefined) return handler;
|
|
94
|
-
|
|
95
|
-
// Lookup plana dei nomi (normali + sotto-campi anonymous) su oggetto
|
|
96
|
-
// null-proto: bracket access è inline-cached da V8 (più veloce di
|
|
97
|
-
// Map.has / Set.has che sono builtin megamorfici).
|
|
98
|
-
const allFieldNames = Object.create(null);
|
|
121
|
+
// Python: i campi sono descrittori della classe (CField), non attributi
|
|
122
|
+
// dell'istanza. Qui accessor sul prototipo della classe, condivisi da tutte
|
|
123
|
+
// le istanze: un Proxy per istanza costava ~20 ns per accesso. Il percorso
|
|
124
|
+
// veloce usa il lettore/scrittore precompilato della definizione della classe.
|
|
125
|
+
function installFieldAccessors(Ctor, def) {
|
|
126
|
+
const proto = Ctor.prototype;
|
|
127
|
+
for (const name of installedNames.get(proto) ?? []) {
|
|
128
|
+
delete proto[name];
|
|
129
|
+
}
|
|
130
|
+
const names = [];
|
|
99
131
|
for (const field of def.fields) {
|
|
100
|
-
|
|
132
|
+
names.push(field.name);
|
|
101
133
|
if (field.isAnonymous && field.type && Array.isArray(field.type.fields)) {
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
}
|
|
134
|
+
// Campi promossi (anche da campi anonimi annidati), come Python.
|
|
135
|
+
for (const subField of field.type.fields) names.push(subField.name);
|
|
136
|
+
for (const name of Object.keys(field.type.anonymousFieldNames ?? {})) names.push(name);
|
|
105
137
|
}
|
|
106
138
|
}
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
return undefined;
|
|
127
|
-
}
|
|
128
|
-
|
|
129
|
-
if (prop === "_buffer" || prop === "__buffer") return target[kBuffer];
|
|
130
|
-
if (prop === "_structDef" || prop === "__structDef") return def;
|
|
131
|
-
// La classe, non una sua copia legata (x.constructor === Point).
|
|
132
|
-
if (prop === "constructor") return target.constructor;
|
|
133
|
-
|
|
134
|
-
const method = target[prop];
|
|
135
|
-
if (typeof method === "function") {
|
|
136
|
-
// Bind al Proxy (receiver), NON al target raw. Un metodo custom
|
|
137
|
-
// come `mag2() { return this.x * this.x + ... }` dentro fa
|
|
138
|
-
// `this.x` che deve passare attraverso il Proxy get trap per
|
|
139
|
-
// leggere il field. Binding su `target` (istanza raw) salta
|
|
140
|
-
// il trap e ritorna undefined → NaN nei calcoli.
|
|
141
|
-
return method.bind(receiver);
|
|
142
|
-
}
|
|
143
|
-
|
|
144
|
-
return Reflect.get(target, prop, receiver);
|
|
145
|
-
},
|
|
146
|
-
set(target, prop, value, receiver) {
|
|
147
|
-
// FAST PATH: pre-compiled writer (null-proto obj, bracket access)
|
|
148
|
-
if (typeof prop === "string") {
|
|
149
|
-
const writer = writers !== undefined ? writers[prop] : undefined;
|
|
150
|
-
if (writer !== undefined) {
|
|
151
|
-
writer(target[kBuffer], value, target[kMirrorBase]);
|
|
152
|
-
return true;
|
|
153
|
-
}
|
|
154
|
-
if (allFieldNames[prop] === true) {
|
|
155
|
-
def.set(target[kBuffer], prop, value);
|
|
156
|
-
return true;
|
|
157
|
-
}
|
|
158
|
-
}
|
|
159
|
-
|
|
160
|
-
return Reflect.set(target, prop, value, receiver);
|
|
161
|
-
},
|
|
162
|
-
has(target, prop) {
|
|
163
|
-
if (typeof prop === "string" && allFieldNames[prop] === true) return true;
|
|
164
|
-
if (prop === "_buffer" || prop === "_structDef" || prop === "toObject") return true;
|
|
165
|
-
return Reflect.has(target, prop);
|
|
166
|
-
},
|
|
167
|
-
ownKeys(target) {
|
|
168
|
-
const keys = [];
|
|
169
|
-
for (const f of def.fields) {
|
|
170
|
-
if (f.isAnonymous && f.type && Array.isArray(f.type.fields)) {
|
|
171
|
-
for (const sf of f.type.fields) {
|
|
172
|
-
keys.push(sf.name);
|
|
139
|
+
const installed = [];
|
|
140
|
+
const nestedClasses = new Map();
|
|
141
|
+
for (const field of def.fields) {
|
|
142
|
+
if (field.isNested && !field.isAnonymous && field.cls !== undefined) nestedClasses.set(field.name, field);
|
|
143
|
+
}
|
|
144
|
+
for (const name of names) {
|
|
145
|
+
if (reservedNames.has(name)) continue;
|
|
146
|
+
const nested = nestedClasses.get(name);
|
|
147
|
+
if (nested !== undefined) {
|
|
148
|
+
const { cls, offset, size } = nested;
|
|
149
|
+
Object.defineProperty(proto, name, {
|
|
150
|
+
get() {
|
|
151
|
+
if (this[kDef] !== def) return readField(this, name);
|
|
152
|
+
let views = this[kViews];
|
|
153
|
+
if (views === undefined) views = this[kViews] = new Map();
|
|
154
|
+
let view = views.get(name);
|
|
155
|
+
if (view === undefined) {
|
|
156
|
+
view = new cls(this[kBuffer].subarray(offset, offset + size));
|
|
157
|
+
views.set(name, view);
|
|
173
158
|
}
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
159
|
+
return view;
|
|
160
|
+
},
|
|
161
|
+
set(value) {
|
|
162
|
+
writeField(this, name, value);
|
|
163
|
+
},
|
|
164
|
+
enumerable: false,
|
|
165
|
+
configurable: true,
|
|
166
|
+
});
|
|
167
|
+
installed.push(name);
|
|
168
|
+
continue;
|
|
169
|
+
}
|
|
170
|
+
const read = def.fieldReaders?.[name];
|
|
171
|
+
const write = def.fieldWriters?.[name];
|
|
172
|
+
Object.defineProperty(proto, name, {
|
|
173
|
+
get:
|
|
174
|
+
read !== undefined
|
|
175
|
+
? function () {
|
|
176
|
+
if (this[kDef] === def && this[kMirrorBase] === undefined) return read(this[kBuffer]);
|
|
177
|
+
return readField(this, name);
|
|
178
|
+
}
|
|
179
|
+
: function () {
|
|
180
|
+
return readField(this, name);
|
|
181
|
+
},
|
|
182
|
+
set:
|
|
183
|
+
write !== undefined
|
|
184
|
+
? function (value) {
|
|
185
|
+
if (this[kDef] === def && this[kMirrorBase] === undefined) write(this[kBuffer], value);
|
|
186
|
+
else writeField(this, name, value);
|
|
187
|
+
}
|
|
188
|
+
: function (value) {
|
|
189
|
+
writeField(this, name, value);
|
|
190
|
+
},
|
|
191
|
+
enumerable: false,
|
|
192
|
+
configurable: true,
|
|
193
|
+
});
|
|
194
|
+
installed.push(name);
|
|
195
|
+
}
|
|
196
|
+
installedNames.set(proto, installed);
|
|
200
197
|
}
|
|
201
198
|
|
|
202
199
|
// Scrittore precompilato del campo quando esiste, altrimenti def.set generico.
|
|
@@ -224,12 +221,12 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
224
221
|
* Structure base class for creating C-style structures.
|
|
225
222
|
*
|
|
226
223
|
* Users extend this class and define static `_fields_` to specify the struct layout.
|
|
227
|
-
* The constructor handles memory allocation
|
|
228
|
-
*
|
|
224
|
+
* The constructor handles memory allocation and field initialization; the
|
|
225
|
+
* fields are accessors of the class prototype (Python: field descriptors).
|
|
229
226
|
*
|
|
230
227
|
* **Key Features**:
|
|
231
228
|
* - Automatic memory layout based on `_fields_`
|
|
232
|
-
* -
|
|
229
|
+
* - Field accessors shared by all instances of the class
|
|
233
230
|
* - Support for positional arguments in constructor
|
|
234
231
|
* - Buffer wrapping for zero-copy operations
|
|
235
232
|
* - Anonymous field support via `_anonymous_`
|
|
@@ -285,14 +282,19 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
285
282
|
class Structure {
|
|
286
283
|
constructor(...args) {
|
|
287
284
|
const Ctor = this.constructor;
|
|
288
|
-
|
|
285
|
+
// Definizione propria della classe (percorso caldo di `new`: una lettura
|
|
286
|
+
// di proprietà invece di Object.hasOwn).
|
|
287
|
+
const own = Ctor[kStructDef];
|
|
288
|
+
const def = own !== undefined && own.owner === Ctor ? own.def : Ctor._buildStruct();
|
|
289
289
|
let buf;
|
|
290
290
|
|
|
291
291
|
// Support positional args: new Point(10,20)
|
|
292
292
|
// Un'istanza di struct/union come unico argomento è posizionale
|
|
293
293
|
// (Python: RECT(point)), non un oggetto di inizializzazione per nome.
|
|
294
294
|
const single = args.length === 1 ? args[0] : undefined;
|
|
295
|
-
|
|
295
|
+
// Solo un oggetto semplice è un'inizializzazione per nome: istanze
|
|
296
|
+
// ctypes (anche SimpleCData, Python: P(c_int(5))) sono posizionali.
|
|
297
|
+
const isNamedInit = typeof single === "object" && single !== null && isPlainObject(single);
|
|
296
298
|
if (isNamedInit) {
|
|
297
299
|
// alloc() restituisce un buffer già azzerato (Buffer.alloc)
|
|
298
300
|
buf = alloc(def.size);
|
|
@@ -312,21 +314,54 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
312
314
|
if (args.length > 0) {
|
|
313
315
|
// Positional mapping to non-anonymous declared fields order
|
|
314
316
|
const ordered = getPositionalFields(def);
|
|
315
|
-
|
|
317
|
+
if (args.length > ordered.length) throw new TypeError("too many initializers");
|
|
318
|
+
for (let i = 0; i < args.length; i++) {
|
|
316
319
|
setField(def, buf, ordered[i].name, args[i]);
|
|
317
320
|
}
|
|
318
321
|
}
|
|
319
322
|
}
|
|
320
323
|
|
|
321
|
-
// Store internal references on this (needed for methods like toObject)
|
|
322
|
-
this.__buffer = buf;
|
|
323
|
-
this.__structDef = def;
|
|
324
324
|
this[kBuffer] = buf;
|
|
325
|
+
this[kDef] = def;
|
|
326
|
+
this[kViews] = undefined;
|
|
325
327
|
// Indirizzo di una copia di memoria nativa (Electron), undefined altrimenti.
|
|
326
|
-
|
|
327
|
-
|
|
328
|
+
this[kMirrorBase] = mirrorsActive ? mirrorBase(buf) : undefined;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
// Memoria e definizione dell'istanza. Riassegnare `__buffer` crea una
|
|
332
|
+
// proprietà propria e non cambia la memoria dei campi.
|
|
333
|
+
get _buffer() {
|
|
334
|
+
return this[kBuffer];
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
get __buffer() {
|
|
338
|
+
return this[kBuffer];
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
set __buffer(value) {
|
|
342
|
+
Object.defineProperty(this, "__buffer", { value, writable: true, configurable: true });
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
get _structDef() {
|
|
346
|
+
return this[kDef];
|
|
347
|
+
}
|
|
328
348
|
|
|
329
|
-
|
|
349
|
+
get __structDef() {
|
|
350
|
+
return this[kDef];
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
get [Symbol.toStringTag]() {
|
|
354
|
+
return this.constructor.name || "Structure";
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
// I campi non sono proprietà proprie (come in Python): JSON.stringify e
|
|
358
|
+
// util.inspect li mostrano tramite toObject().
|
|
359
|
+
toJSON() {
|
|
360
|
+
return this.toObject();
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
[Symbol.for("nodejs.util.inspect.custom")](depth, options, inspect) {
|
|
364
|
+
return `${this.constructor.name || "Structure"} ${inspect(this.toObject(), options)}`;
|
|
330
365
|
}
|
|
331
366
|
|
|
332
367
|
// Static getters for size, alignment, and fields (enables use as nested type)
|
|
@@ -361,14 +396,10 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
361
396
|
* @returns {Structure} A new instance sharing memory with source.
|
|
362
397
|
*/
|
|
363
398
|
static from_buffer(source, offset = 0) {
|
|
364
|
-
if (!Buffer.isBuffer(source)) {
|
|
365
|
-
throw new TypeError("from_buffer: source must be a Buffer");
|
|
366
|
-
}
|
|
367
399
|
const def = this._structDef || this._buildStruct();
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
return new this(source.subarray(offset, offset + def.size));
|
|
400
|
+
const bytes = sourceBytes(source, offset, def.size, "from_buffer");
|
|
401
|
+
// Buffer: subarray (conserva la sincronizzazione delle copie native).
|
|
402
|
+
return new this(Buffer.isBuffer(bytes) ? bytes.subarray(offset, offset + def.size) : Buffer.from(bytes.buffer, bytes.byteOffset + offset, def.size));
|
|
372
403
|
}
|
|
373
404
|
|
|
374
405
|
/**
|
|
@@ -379,22 +410,13 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
379
410
|
*
|
|
380
411
|
* @param {Buffer|Uint8Array} source - Bytes to copy from.
|
|
381
412
|
* @param {number} [offset=0] - Byte offset into source.
|
|
382
|
-
* @returns {Structure} A new instance with
|
|
413
|
+
* @returns {Structure} A new instance with its own buffer.
|
|
383
414
|
*/
|
|
384
415
|
static from_buffer_copy(source, offset = 0) {
|
|
385
|
-
if (!Buffer.isBuffer(source) && !(source instanceof Uint8Array)) {
|
|
386
|
-
throw new TypeError("from_buffer_copy: source must be a Buffer or Uint8Array");
|
|
387
|
-
}
|
|
388
416
|
const def = this._structDef || this._buildStruct();
|
|
389
|
-
|
|
390
|
-
throw new RangeError(`from_buffer_copy: source too small (${source.length - offset} < ${def.size})`);
|
|
391
|
-
}
|
|
417
|
+
const bytes = sourceBytes(source, offset, def.size, "from_buffer_copy");
|
|
392
418
|
const copy = Buffer.alloc(def.size);
|
|
393
|
-
|
|
394
|
-
source.copy(copy, 0, offset, offset + def.size);
|
|
395
|
-
} else {
|
|
396
|
-
copy.set(source.subarray(offset, offset + def.size));
|
|
397
|
-
}
|
|
419
|
+
copyInstance(copy, 0, def.size, bytes, offset, def);
|
|
398
420
|
return new this(copy);
|
|
399
421
|
}
|
|
400
422
|
|
|
@@ -410,7 +432,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
410
432
|
*/
|
|
411
433
|
static from_address(address) {
|
|
412
434
|
if (!ptrToBuffer) {
|
|
413
|
-
throw new Error("from_address requires the native module (
|
|
435
|
+
throw new Error("from_address requires the native module (not loaded)");
|
|
414
436
|
}
|
|
415
437
|
const addr = typeof address === "bigint" ? address : BigInt(address);
|
|
416
438
|
const def = this._structDef || this._buildStruct();
|
|
@@ -423,83 +445,110 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
423
445
|
* Python ctypes parity: `S.in_dll(library, name)`.
|
|
424
446
|
*/
|
|
425
447
|
static in_dll(library, name) {
|
|
426
|
-
const
|
|
427
|
-
|
|
428
|
-
throw new TypeError("in_dll: first arg must be a Library (CDLL/WinDLL)");
|
|
429
|
-
}
|
|
430
|
-
const addr = nativeLib.symbol(name);
|
|
431
|
-
if (!addr) {
|
|
432
|
-
throw new Error(`in_dll: symbol '${name}' not found`);
|
|
433
|
-
}
|
|
434
|
-
return this.from_address(addr);
|
|
448
|
+
const def = this._structDef || this._buildStruct();
|
|
449
|
+
return new this(inDllBuffer(library, name, def.size, ptrToBuffer));
|
|
435
450
|
}
|
|
436
451
|
|
|
437
452
|
// Build the underlying struct definition and cache it on the constructor
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
453
|
+
// Definizione della classe stessa: una sottoclasse non eredita quella
|
|
454
|
+
// della base (ha un layout proprio, vedi _buildStruct).
|
|
455
|
+
static get _structDef() {
|
|
456
|
+
const own = this[kStructDef];
|
|
457
|
+
return own !== undefined && own.owner === this ? own.def : undefined;
|
|
458
|
+
}
|
|
442
459
|
|
|
460
|
+
static set _structDef(def) {
|
|
461
|
+
// null/undefined invalida la cache (il layout viene ricostruito).
|
|
462
|
+
if (def === null || def === undefined) {
|
|
463
|
+
delete this[kStructDef];
|
|
464
|
+
return;
|
|
465
|
+
}
|
|
466
|
+
// { owner, def }: una sottoclasse eredita la proprietà ma non è `owner`.
|
|
467
|
+
Object.defineProperty(this, kStructDef, { value: { owner: this, def }, configurable: true, writable: true });
|
|
468
|
+
installFieldAccessors(this, def);
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
// Classe base con un layout (Python: la sottoclasse ne estende i campi),
|
|
472
|
+
// null per le basi della libreria (Structure, Union, BigEndianStructure...).
|
|
473
|
+
static _baseLayoutClass() {
|
|
474
|
+
const parent = Object.getPrototypeOf(this);
|
|
475
|
+
for (let c = parent; typeof c === "function" && c.prototype instanceof Structure; c = Object.getPrototypeOf(c)) {
|
|
476
|
+
if (Object.hasOwn(c, "_fields_") || c._structDef !== undefined) return parent;
|
|
477
|
+
}
|
|
478
|
+
return null;
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
// `_fields_` della classe come coppie [name, type] nell'ordine dichiarato
|
|
482
|
+
// (un oggetto metterebbe prima i nomi come "1"), con i bitfield
|
|
483
|
+
// `[name, type, bits]` e (se `withAnonymous`) i campi di `_anonymous_`
|
|
484
|
+
// come { anonymous: true, type, cls }.
|
|
485
|
+
static _fieldMap(withAnonymous = true) {
|
|
486
|
+
const fields = Object.hasOwn(this, "_fields_") ? this._fields_ : {};
|
|
487
|
+
let entries;
|
|
443
488
|
if (Array.isArray(fields)) {
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
// Python-style bitfield: [name, type, bits]
|
|
449
|
-
if (entry.length >= 3 && typeof entry[2] === "number") {
|
|
450
|
-
mapFields[name] = bitfield(type, entry[2]);
|
|
451
|
-
} else {
|
|
452
|
-
mapFields[name] = type;
|
|
453
|
-
}
|
|
489
|
+
entries = fields.map((entry) => {
|
|
490
|
+
const valid = Array.isArray(entry) && typeof entry[0] === "string" && entry[1] != null && (entry.length === 2 || (entry.length === 3 && typeof entry[2] === "number"));
|
|
491
|
+
if (!valid) {
|
|
492
|
+
throw new TypeError("_fields_ must be a sequence of (name, C type) pairs or (name, C type, bit size) triples");
|
|
454
493
|
}
|
|
455
|
-
|
|
494
|
+
return entry.length === 3 ? [entry[0], bitfield(entry[1], entry[2])] : [entry[0], entry[1]];
|
|
495
|
+
});
|
|
456
496
|
} else if (typeof fields === "object" && fields !== null) {
|
|
457
|
-
|
|
497
|
+
entries = Object.entries(fields);
|
|
498
|
+
} else {
|
|
499
|
+
entries = [];
|
|
458
500
|
}
|
|
459
501
|
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
if (
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
anonType = anonType._structDef || anonType._buildStruct();
|
|
468
|
-
}
|
|
469
|
-
mapFields[anonName] = {
|
|
470
|
-
anonymous: true,
|
|
471
|
-
type: anonType,
|
|
472
|
-
};
|
|
502
|
+
if (withAnonymous && Array.isArray(this._anonymous_)) {
|
|
503
|
+
const anonymous = new Set(this._anonymous_);
|
|
504
|
+
entries = entries.map(([name, type]) => {
|
|
505
|
+
if (!anonymous.has(name)) return [name, type];
|
|
506
|
+
// Classe Structure/Union: la sua definizione, e la classe per le istanze.
|
|
507
|
+
if (typeof type === "function" && typeof type._buildStruct === "function") {
|
|
508
|
+
return [name, { anonymous: true, type: type._structDef || type._buildStruct(), cls: type }];
|
|
473
509
|
}
|
|
474
|
-
|
|
510
|
+
return [name, { anonymous: true, type }];
|
|
511
|
+
});
|
|
475
512
|
}
|
|
513
|
+
return entries;
|
|
514
|
+
}
|
|
476
515
|
|
|
516
|
+
// Opzioni di layout della classe (ereditate, come getattr in Python):
|
|
517
|
+
// `_pack_`, `_layout_`, `_align_` e byte order.
|
|
518
|
+
static _layoutOptions() {
|
|
477
519
|
const options = {};
|
|
478
|
-
if (this._pack_ !== undefined) {
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
// `true` is tolerated as an alias for `_pack_ = 1`. Anything else is
|
|
482
|
-
// rejected so we don't silently produce a mislaid struct.
|
|
483
|
-
const p = this._pack_;
|
|
484
|
-
if (p === true) {
|
|
485
|
-
options.pack = 1;
|
|
486
|
-
} else if (p === false) {
|
|
487
|
-
// explicit false = no packing, same as absent
|
|
488
|
-
} else if (typeof p === "number" && Number.isInteger(p) && p >= 1 && (p & (p - 1)) === 0) {
|
|
489
|
-
options.pack = p;
|
|
490
|
-
} else {
|
|
491
|
-
throw new TypeError(`_pack_ must be a positive power-of-two integer, got ${p}`);
|
|
492
|
-
}
|
|
493
|
-
if (options.pack !== undefined) options.packed = true;
|
|
520
|
+
if (this._pack_ !== undefined && this._pack_ !== null) {
|
|
521
|
+
options.pack = normalizePack(this._pack_);
|
|
522
|
+
options.packed = options.pack !== 0;
|
|
494
523
|
}
|
|
524
|
+
// Python ctypes: "ms" (Windows, or with _pack_) or "gcc-sysv" bitfield layout.
|
|
525
|
+
if (this._layout_ !== undefined) options.layout = this._layout_;
|
|
526
|
+
// Python ctypes: `_align_` raises the minimum alignment of the type.
|
|
527
|
+
if (this._align_ !== undefined) options.align = this._align_;
|
|
495
528
|
// Python ctypes: `_swappedbytes_` (or the BigEndianStructure /
|
|
496
529
|
// LittleEndianStructure base class) requests byte-swapped fields.
|
|
497
530
|
// We only officially support LE hosts, so `swapped: true` ⇒ BE layout.
|
|
498
531
|
if (this._swappedbytes_ === true || this._swapped_ === true) {
|
|
499
532
|
options.swapped = true;
|
|
500
533
|
}
|
|
534
|
+
return options;
|
|
535
|
+
}
|
|
501
536
|
|
|
502
|
-
|
|
537
|
+
// Build the underlying struct definition and cache it on the constructor
|
|
538
|
+
static _buildStruct() {
|
|
539
|
+
const own = this._structDef;
|
|
540
|
+
if (own !== undefined) return own;
|
|
541
|
+
const Base = this._baseLayoutClass();
|
|
542
|
+
const base = Base === null ? null : Base._structDef || Base._buildStruct();
|
|
543
|
+
// Python: una sottoclasse senza _fields_ propri ha il layout della base.
|
|
544
|
+
if (base !== null && !Object.hasOwn(this, "_fields_")) {
|
|
545
|
+
this._structDef = base;
|
|
546
|
+
return base;
|
|
547
|
+
}
|
|
548
|
+
if (base !== null && base.isUnion) {
|
|
549
|
+
throw new TypeError("a Structure cannot extend a Union");
|
|
550
|
+
}
|
|
551
|
+
const def = struct(this._fieldMap(), { ...this._layoutOptions(), base });
|
|
503
552
|
this._structDef = def;
|
|
504
553
|
return def;
|
|
505
554
|
}
|
|
@@ -559,7 +608,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
559
608
|
|
|
560
609
|
// Bulk operations for better performance
|
|
561
610
|
setFields(fields) {
|
|
562
|
-
for (const [name, value] of Object.entries(fields)) {
|
|
611
|
+
for (const [name, value] of Object.entries(fieldsOf(fields))) {
|
|
563
612
|
this.__structDef.set(this.__buffer, name, value);
|
|
564
613
|
}
|
|
565
614
|
}
|
|
@@ -572,7 +621,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
|
|
|
572
621
|
return result;
|
|
573
622
|
}
|
|
574
623
|
|
|
575
|
-
// bulk operations (
|
|
624
|
+
// bulk operations (fields read directly from the buffer - no cache needed)
|
|
576
625
|
withBulkUpdate(callback) {
|
|
577
626
|
return callback(this);
|
|
578
627
|
}
|
package/lib/structures/Union.js
CHANGED
|
@@ -82,29 +82,18 @@ export function createUnionClass(Structure, union, bitfield) {
|
|
|
82
82
|
*/
|
|
83
83
|
class Union extends Structure {
|
|
84
84
|
static _buildStruct() {
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
// Python-style bitfield: [name, type, bits]
|
|
93
|
-
if (entry.length >= 3 && typeof entry[2] === "number") {
|
|
94
|
-
mapFields[name] = bitfield(type, entry[2]);
|
|
95
|
-
} else {
|
|
96
|
-
mapFields[name] = type;
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
} else if (typeof fields === "object" && fields !== null) {
|
|
101
|
-
mapFields = fields;
|
|
85
|
+
if (this._structDef !== undefined) return this._structDef;
|
|
86
|
+
const Base = this._baseLayoutClass();
|
|
87
|
+
const base = Base === null ? null : Base._structDef || Base._buildStruct();
|
|
88
|
+
// Python: una sottoclasse senza _fields_ propri ha il layout della base.
|
|
89
|
+
if (base !== null && !Object.hasOwn(this, "_fields_")) {
|
|
90
|
+
this._structDef = base;
|
|
91
|
+
return base;
|
|
102
92
|
}
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
options.swapped = true;
|
|
93
|
+
if (base !== null && !base.isUnion) {
|
|
94
|
+
throw new TypeError("a Union cannot extend a Structure");
|
|
106
95
|
}
|
|
107
|
-
const def = union(
|
|
96
|
+
const def = union(this._fieldMap(), { ...this._layoutOptions(), base });
|
|
108
97
|
this._structDef = def;
|
|
109
98
|
return def;
|
|
110
99
|
}
|