node-ctypes 2.1.1 → 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 +98 -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 +193 -3
- package/lib/core/funcptr.js +67 -52
- package/lib/core/lazy-loader.js +10 -4
- package/lib/core/types.js +196 -98
- package/lib/index.d.ts +193 -47
- package/lib/index.js +51 -28
- package/lib/memory/buffer.js +66 -19
- package/lib/memory/mirror.js +283 -0
- package/lib/memory/operations.js +59 -42
- package/lib/memory/pointer.js +180 -61
- 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 +260 -172
- package/lib/structures/Union.js +10 -21
- package/lib/structures/helpers/array.js +235 -92
- 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 +144 -400
- package/lib/structures/helpers/union.js +132 -142
- package/lib/structures/helpers/wrap.js +29 -17
- package/lib/types/SimpleCData.js +14 -7
- package/lib/types/primitives.js +130 -101
- package/package.json +2 -1
package/lib/index.d.ts
CHANGED
|
@@ -172,7 +172,11 @@ export class Library {
|
|
|
172
172
|
*/
|
|
173
173
|
symbol(name: string): bigint;
|
|
174
174
|
|
|
175
|
-
/**
|
|
175
|
+
/**
|
|
176
|
+
* Close the library and release resources. Functions obtained from it
|
|
177
|
+
* throw when called afterwards. Throws while a call to one of its
|
|
178
|
+
* functions is in progress (from a callback, or a pending `callAsync()`).
|
|
179
|
+
*/
|
|
176
180
|
close(): void;
|
|
177
181
|
|
|
178
182
|
/** Library file path. */
|
|
@@ -312,13 +316,22 @@ export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends
|
|
|
312
316
|
*/
|
|
313
317
|
export interface LibraryOptions {
|
|
314
318
|
/**
|
|
315
|
-
* `dlopen` flags combined with `
|
|
319
|
+
* `dlopen` flags combined with `RTLD_NOW` (e.g. {@link RTLD_GLOBAL}).
|
|
316
320
|
* Ignored on Windows. Default: {@link DEFAULT_MODE}.
|
|
317
321
|
*
|
|
318
322
|
* Python ctypes parity: the `mode` argument of `CDLL(name, mode)`.
|
|
319
323
|
*/
|
|
320
324
|
mode?: number;
|
|
321
325
|
|
|
326
|
+
/**
|
|
327
|
+
* `LoadLibraryExW` flags (Windows only). Default: `LOAD_LIBRARY_SEARCH_DEFAULT_DIRS`,
|
|
328
|
+
* plus `LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR` (with the path made absolute) when the
|
|
329
|
+
* name contains a path separator.
|
|
330
|
+
*
|
|
331
|
+
* Python ctypes parity: the `winmode` argument of `CDLL(name, winmode=...)`.
|
|
332
|
+
*/
|
|
333
|
+
winmode?: number;
|
|
334
|
+
|
|
322
335
|
/**
|
|
323
336
|
* Maximum size of the internal function cache. Default: 1000.
|
|
324
337
|
*/
|
|
@@ -370,7 +383,11 @@ export class CDLL {
|
|
|
370
383
|
*/
|
|
371
384
|
symbol(name: string): bigint;
|
|
372
385
|
|
|
373
|
-
/**
|
|
386
|
+
/**
|
|
387
|
+
* Close the library and clear the function cache. Functions obtained from
|
|
388
|
+
* it throw when called afterwards. Throws while a call to one of its
|
|
389
|
+
* functions is in progress (from a callback, or a pending `callAsync()`).
|
|
390
|
+
*/
|
|
374
391
|
close(): void;
|
|
375
392
|
|
|
376
393
|
/** Close the library at the end of a `using` block. */
|
|
@@ -790,11 +807,27 @@ type PointerContents<T> = IsAny<T> extends true ? any : T extends SimpleCDataCon
|
|
|
790
807
|
type CharArrayValue<E, Else> = IsAny<E> extends true ? Else : [E] extends [SimpleCDataConstructor<"char">] ? string : [E] extends [SimpleCDataConstructor<"wchar">] ? string : Else;
|
|
791
808
|
|
|
792
809
|
/**
|
|
793
|
-
* Array instance: a Buffer with index access;
|
|
794
|
-
*
|
|
810
|
+
* Array instance: a Buffer with index access; the Array methods (`slice`, `map`,
|
|
811
|
+
* `includes`, ...) work on the elements, as Python's sequence operations.
|
|
812
|
+
* `c_char` arrays also expose `.value`/`.raw` and `c_wchar` arrays `.value`.
|
|
795
813
|
* @category Structures
|
|
796
814
|
*/
|
|
797
|
-
export type ArrayInstance<E = any> = Buffer
|
|
815
|
+
export type ArrayInstance<E = any> = Omit<Buffer, ElementMethod | "length" | "toJSON"> &
|
|
816
|
+
(IsAny<E> extends true
|
|
817
|
+
? ArrayProxy<any>
|
|
818
|
+
: [E] extends [SimpleCDataConstructor<"char">]
|
|
819
|
+
? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & CharBufferValue & CharSlice
|
|
820
|
+
: [E] extends [SimpleCDataConstructor<"wchar">]
|
|
821
|
+
? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & WideBufferValue & CharSlice
|
|
822
|
+
: ArrayProxy<ArrayElement<E>>);
|
|
823
|
+
|
|
824
|
+
/** Array methods that work on the elements of an array instance; the Buffer methods (`readInt32LE`, `subarray`, ...) work on the bytes. */
|
|
825
|
+
type ElementMethod = Exclude<keyof ArrayProxy, number | typeof Symbol.iterator | "length" | "toJSON">;
|
|
826
|
+
|
|
827
|
+
/** `c_char` / `c_wchar` arrays: a slice is a string (Python: bytes / str). */
|
|
828
|
+
interface CharSlice {
|
|
829
|
+
slice(start?: number, end?: number): string;
|
|
830
|
+
}
|
|
798
831
|
|
|
799
832
|
/**
|
|
800
833
|
* Text accessors of `c_char` buffers (arrays, {@link create_string_buffer}).
|
|
@@ -824,17 +857,18 @@ type ArgsFromCTypes<TArgs extends readonly any[]> = {
|
|
|
824
857
|
};
|
|
825
858
|
|
|
826
859
|
/** JS argument accepted for a function parameter of type `T`. */
|
|
827
|
-
type JsArgFromFFIType<T> = T extends StructureClass ? Buffer | { _buffer: Buffer } | Record<string, any> : JsArgFromCType<T>;
|
|
860
|
+
type JsArgFromFFIType<T> = T extends StructureClass ? Buffer | { _buffer: Buffer } | Record<string, any> : T extends ArrayTypeDef<infer E> ? ArrayInstance<E> | ArrayBufferView | ArrayBuffer | { readonly _as_parameter_: unknown } : JsArgFromCType<T>;
|
|
828
861
|
|
|
829
862
|
/** Function arguments for `argtypes` `TArgs` (`any[]` when not a literal tuple). */
|
|
830
863
|
type FFIArgs<TArgs extends readonly any[]> = FFIType[] extends TArgs ? any[] : { [K in keyof TArgs]: JsArgFromFFIType<TArgs[K]> };
|
|
831
864
|
|
|
832
865
|
/**
|
|
833
866
|
* JS value returned by a function with `restype` `T`. As in Python, a
|
|
834
|
-
* `POINTER(T)` restype returns a {@link PointerInstance}
|
|
835
|
-
* restype a callable function (`null` for NULL)
|
|
867
|
+
* `POINTER(T)` restype returns a {@link PointerInstance}, a {@link CFUNCTYPE}
|
|
868
|
+
* restype a callable function (`null` for NULL) and a Structure/Union class an
|
|
869
|
+
* instance of that class.
|
|
836
870
|
*/
|
|
837
|
-
type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends StructureClass ?
|
|
871
|
+
type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
|
|
838
872
|
|
|
839
873
|
/**
|
|
840
874
|
* A union type definition created by the {@link union} function.
|
|
@@ -914,15 +948,70 @@ export interface ArrayTypeDef<E = any> {
|
|
|
914
948
|
create(values?: ReadonlyArray<ArrayElementArg<E>> | string): ArrayInstance<E>;
|
|
915
949
|
/** Wrap an existing buffer as an array with index access. */
|
|
916
950
|
wrap(buffer: Buffer): ArrayInstance<E>;
|
|
951
|
+
/**
|
|
952
|
+
* Array sharing the memory of `source` from `offset` (Python:
|
|
953
|
+
* `(c_int * 3).from_buffer(source, offset)`).
|
|
954
|
+
*/
|
|
955
|
+
from_buffer(source: Buffer | Uint8Array | { _buffer: Buffer }, offset?: number): ArrayInstance<E>;
|
|
956
|
+
/** Array with a copy of the bytes of `source` from `offset` (Python: `from_buffer_copy`). */
|
|
957
|
+
from_buffer_copy(source: Buffer | Uint8Array | { _buffer: Buffer }, offset?: number): ArrayInstance<E>;
|
|
958
|
+
/**
|
|
959
|
+
* Array on the memory at `address` (Python: `(c_int * 3).from_address(address)`).
|
|
960
|
+
* Its `_buffer` is a Buffer over that memory, as Python's
|
|
961
|
+
* `memoryview((c_char * n).from_address(address))`; where
|
|
962
|
+
* {@link EXTERNAL_BUFFERS} is `false` it is a copy kept in sync by the
|
|
963
|
+
* array's element accesses.
|
|
964
|
+
*/
|
|
965
|
+
from_address(address: bigint | number): ArrayInstance<E>;
|
|
917
966
|
}
|
|
918
967
|
|
|
919
968
|
/**
|
|
920
969
|
* Proxy interface for array index access and iteration.
|
|
921
970
|
* @category Structures
|
|
922
971
|
*/
|
|
923
|
-
export interface ArrayProxy<T = any>
|
|
972
|
+
export interface ArrayProxy<T = any> extends Pick<
|
|
973
|
+
T[],
|
|
974
|
+
| "at"
|
|
975
|
+
| "copyWithin"
|
|
976
|
+
| "entries"
|
|
977
|
+
| "every"
|
|
978
|
+
| "fill"
|
|
979
|
+
| "filter"
|
|
980
|
+
| "find"
|
|
981
|
+
| "findIndex"
|
|
982
|
+
| "findLast"
|
|
983
|
+
| "findLastIndex"
|
|
984
|
+
| "forEach"
|
|
985
|
+
| "includes"
|
|
986
|
+
| "indexOf"
|
|
987
|
+
| "join"
|
|
988
|
+
| "keys"
|
|
989
|
+
| "lastIndexOf"
|
|
990
|
+
| "map"
|
|
991
|
+
| "reduce"
|
|
992
|
+
| "reduceRight"
|
|
993
|
+
| "reverse"
|
|
994
|
+
| "slice"
|
|
995
|
+
| "some"
|
|
996
|
+
| "sort"
|
|
997
|
+
| "toLocaleString"
|
|
998
|
+
| "toReversed"
|
|
999
|
+
| "toSorted"
|
|
1000
|
+
| "values"
|
|
1001
|
+
| "with"
|
|
1002
|
+
> {
|
|
924
1003
|
[index: number]: T;
|
|
925
1004
|
[Symbol.iterator](): Iterator<T>;
|
|
1005
|
+
/** Number of elements (Python `len(arr)`); the size in bytes is `byteLength`. */
|
|
1006
|
+
readonly length: number;
|
|
1007
|
+
/** The elements, for `JSON.stringify`. */
|
|
1008
|
+
toJSON(): T[];
|
|
1009
|
+
/**
|
|
1010
|
+
* The Buffer of the array: for an array on native memory
|
|
1011
|
+
* ({@link ArrayTypeDef.from_address}) a Buffer over that memory, as
|
|
1012
|
+
* Python's `memoryview()` (a copy where {@link EXTERNAL_BUFFERS} is `false`).
|
|
1013
|
+
*/
|
|
1014
|
+
readonly _buffer: Buffer;
|
|
926
1015
|
}
|
|
927
1016
|
|
|
928
1017
|
/**
|
|
@@ -930,8 +1019,14 @@ export interface ArrayProxy<T = any> {
|
|
|
930
1019
|
* @category Structures
|
|
931
1020
|
*/
|
|
932
1021
|
export interface StructOptions {
|
|
933
|
-
/** If `true`, disables padding between fields. */
|
|
1022
|
+
/** If `true`, disables padding between fields (as `pack: 1`). */
|
|
934
1023
|
packed?: boolean;
|
|
1024
|
+
/** Maximum field alignment in bytes, as Python's `_pack_`. */
|
|
1025
|
+
pack?: number;
|
|
1026
|
+
/** Bit field layout, as Python's `_layout_` (`"ms"` with `pack`, otherwise the platform's). */
|
|
1027
|
+
layout?: "gcc-sysv" | "ms";
|
|
1028
|
+
/** Minimum alignment in bytes, as Python's `_align_`. */
|
|
1029
|
+
align?: number;
|
|
935
1030
|
}
|
|
936
1031
|
|
|
937
1032
|
/**
|
|
@@ -1220,6 +1315,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1220
1315
|
*/
|
|
1221
1316
|
static _pack_?: number | boolean;
|
|
1222
1317
|
|
|
1318
|
+
/**
|
|
1319
|
+
* Bit field layout, as Python's `_layout_`: `"gcc-sysv"` (default except on
|
|
1320
|
+
* Windows) or `"ms"` (default on Windows and with `_pack_`).
|
|
1321
|
+
*/
|
|
1322
|
+
static _layout_?: "gcc-sysv" | "ms";
|
|
1323
|
+
|
|
1324
|
+
/** Minimum alignment in bytes, as Python's `_align_`. */
|
|
1325
|
+
static _align_?: number;
|
|
1326
|
+
|
|
1223
1327
|
/**
|
|
1224
1328
|
* List of field names whose members are promoted to the parent struct.
|
|
1225
1329
|
*
|
|
@@ -1227,6 +1331,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1227
1331
|
*/
|
|
1228
1332
|
static _anonymous_?: ReadonlyArray<string>;
|
|
1229
1333
|
|
|
1334
|
+
/** Size in bytes (Python: `sizeof(cls)`). */
|
|
1335
|
+
static readonly size: number;
|
|
1336
|
+
|
|
1337
|
+
/** Alignment in bytes (Python: `alignment(cls)`). */
|
|
1338
|
+
static readonly alignment: number;
|
|
1339
|
+
|
|
1340
|
+
/** Field descriptors, in layout order. */
|
|
1341
|
+
static readonly fields: FieldDef[];
|
|
1342
|
+
|
|
1230
1343
|
/** Create instance with optional initial values. */
|
|
1231
1344
|
static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
|
|
1232
1345
|
|
|
@@ -1239,14 +1352,14 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1239
1352
|
*
|
|
1240
1353
|
* Python ctypes parity: `Structure.from_buffer(source, offset=0)`.
|
|
1241
1354
|
*/
|
|
1242
|
-
static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: Buffer, offset?: number): ThisT;
|
|
1355
|
+
static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
|
|
1243
1356
|
|
|
1244
1357
|
/**
|
|
1245
1358
|
* Create an instance whose buffer is an independent copy of the source bytes.
|
|
1246
1359
|
*
|
|
1247
1360
|
* Python ctypes parity: `Structure.from_buffer_copy(source, offset=0)`.
|
|
1248
1361
|
*/
|
|
1249
|
-
static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source:
|
|
1362
|
+
static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
|
|
1250
1363
|
|
|
1251
1364
|
/**
|
|
1252
1365
|
* Create an instance that views raw memory at `address`. Caller is
|
|
@@ -1280,7 +1393,10 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1280
1393
|
/** Convert all fields to a plain JavaScript object (snapshot). */
|
|
1281
1394
|
toObject(): FieldsToInstance<F>;
|
|
1282
1395
|
|
|
1283
|
-
/**
|
|
1396
|
+
/** The fields, for `JSON.stringify` (same as {@link toObject}). */
|
|
1397
|
+
toJSON(): FieldsToInstance<F>;
|
|
1398
|
+
|
|
1399
|
+
/** Fields: accessors of the class (not own properties, as in Python). */
|
|
1284
1400
|
[field: string]: any;
|
|
1285
1401
|
}
|
|
1286
1402
|
|
|
@@ -1603,6 +1719,13 @@ export function wstring_at(address: Buffer | bigint | number, size?: number): st
|
|
|
1603
1719
|
*/
|
|
1604
1720
|
export function addressof(ptr: Buffer | bigint | number): bigint;
|
|
1605
1721
|
|
|
1722
|
+
/**
|
|
1723
|
+
* Memory argument of {@link memmove} / {@link memset}: a buffer (any typed
|
|
1724
|
+
* array, DataView or ArrayBuffer, as bytes), a ctypes instance, a pointer or an
|
|
1725
|
+
* address.
|
|
1726
|
+
*/
|
|
1727
|
+
export type MemoryTarget = ArrayBufferView | ArrayBufferLike | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
|
|
1728
|
+
|
|
1606
1729
|
/**
|
|
1607
1730
|
* Copy memory from source to destination.
|
|
1608
1731
|
*
|
|
@@ -1610,9 +1733,6 @@ export function addressof(ptr: Buffer | bigint | number): bigint;
|
|
|
1610
1733
|
*
|
|
1611
1734
|
* @category Memory
|
|
1612
1735
|
*/
|
|
1613
|
-
/** Memory argument of {@link memmove} / {@link memset}: a buffer, a ctypes instance, a pointer or an address. */
|
|
1614
|
-
export type MemoryTarget = Uint8Array | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
|
|
1615
|
-
|
|
1616
1736
|
export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): void;
|
|
1617
1737
|
|
|
1618
1738
|
/**
|
|
@@ -1640,8 +1760,8 @@ export function memset(dst: MemoryTarget, value: number, count: number): void;
|
|
|
1640
1760
|
*
|
|
1641
1761
|
* @category Memory
|
|
1642
1762
|
*/
|
|
1643
|
-
export function readValue<T extends AnyType>(ptr:
|
|
1644
|
-
export function readValue(ptr:
|
|
1763
|
+
export function readValue<T extends AnyType>(ptr: MemorySource, type: T, offset?: number): JsFromCType<T>;
|
|
1764
|
+
export function readValue(ptr: MemorySource, type: AnyType | StructureClass, offset?: number): any;
|
|
1645
1765
|
|
|
1646
1766
|
/**
|
|
1647
1767
|
* Write a typed value to a buffer at a given offset.
|
|
@@ -1653,8 +1773,8 @@ export function readValue(ptr: Buffer | bigint | number | PointerInstance, type:
|
|
|
1653
1773
|
*
|
|
1654
1774
|
* @category Memory
|
|
1655
1775
|
*/
|
|
1656
|
-
export function writeValue<T extends AnyType>(ptr:
|
|
1657
|
-
export function writeValue(ptr:
|
|
1776
|
+
export function writeValue<T extends AnyType>(ptr: MemorySource, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
|
|
1777
|
+
export function writeValue(ptr: MemorySource, type: AnyType | StructureClass, value: any, offset?: number): number | void;
|
|
1658
1778
|
|
|
1659
1779
|
/**
|
|
1660
1780
|
* Get the size of a type in bytes.
|
|
@@ -1670,7 +1790,10 @@ export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type
|
|
|
1670
1790
|
*
|
|
1671
1791
|
* @category Memory
|
|
1672
1792
|
*/
|
|
1673
|
-
export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> |
|
|
1793
|
+
export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> | ArrayBufferView): number;
|
|
1794
|
+
|
|
1795
|
+
/** Memory read/written by {@link readValue} / {@link writeValue}: a buffer, a ctypes instance, a pointer or an address. */
|
|
1796
|
+
type MemorySource = Buffer | ArrayBufferView | { _buffer: Buffer } | bigint | number | PointerInstance;
|
|
1674
1797
|
|
|
1675
1798
|
/**
|
|
1676
1799
|
* Get the alignment requirement of a type in bytes.
|
|
@@ -1688,18 +1811,6 @@ export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass
|
|
|
1688
1811
|
*/
|
|
1689
1812
|
export function alignment(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any>): number;
|
|
1690
1813
|
|
|
1691
|
-
/**
|
|
1692
|
-
* Create a Buffer view of native memory at a given address.
|
|
1693
|
-
*
|
|
1694
|
-
* **Warning:** Use with caution — the buffer is not bounds-checked.
|
|
1695
|
-
*
|
|
1696
|
-
* @param address - Native memory address
|
|
1697
|
-
* @param size - Number of bytes
|
|
1698
|
-
*
|
|
1699
|
-
* @category Memory
|
|
1700
|
-
*/
|
|
1701
|
-
export function ptrToBuffer(address: bigint | number, size: number): Buffer;
|
|
1702
|
-
|
|
1703
1814
|
/**
|
|
1704
1815
|
* Define a struct using the functional API.
|
|
1705
1816
|
*
|
|
@@ -1725,10 +1836,11 @@ export function struct<F extends Record<string, FieldSpec>>(fields: F, options?:
|
|
|
1725
1836
|
* For Python-like class syntax, use {@link Union} instead.
|
|
1726
1837
|
*
|
|
1727
1838
|
* @param fields - Object mapping field names to types
|
|
1839
|
+
* @param options - Union options (e.g. `{ pack: 1 }`)
|
|
1728
1840
|
*
|
|
1729
1841
|
* @category Structures
|
|
1730
1842
|
*/
|
|
1731
|
-
export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<F>;
|
|
1843
|
+
export function union<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): UnionDef<F>;
|
|
1732
1844
|
|
|
1733
1845
|
/**
|
|
1734
1846
|
* Factory that returns a Structure subclass with typed fields.
|
|
@@ -1738,7 +1850,7 @@ export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<
|
|
|
1738
1850
|
*
|
|
1739
1851
|
* @category Structures
|
|
1740
1852
|
*/
|
|
1741
|
-
export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions):
|
|
1853
|
+
export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Structure<F> & FieldsToInstance<F>>;
|
|
1742
1854
|
|
|
1743
1855
|
/**
|
|
1744
1856
|
* Factory that returns a Union subclass with typed fields.
|
|
@@ -1747,7 +1859,27 @@ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, opt
|
|
|
1747
1859
|
*
|
|
1748
1860
|
* @category Structures
|
|
1749
1861
|
*/
|
|
1750
|
-
export function defineUnion<F extends Record<string, FieldSpec>>(fields: F):
|
|
1862
|
+
export function defineUnion<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Union<F> & FieldsToInstance<F>>;
|
|
1863
|
+
|
|
1864
|
+
/**
|
|
1865
|
+
* Class returned by {@link defineStruct} / {@link defineUnion}: the statics of
|
|
1866
|
+
* {@link Structure} and a constructor with positional values (field order),
|
|
1867
|
+
* an object of field values or a Buffer.
|
|
1868
|
+
* @category Structures
|
|
1869
|
+
*/
|
|
1870
|
+
export interface DefinedClass<F extends Record<string, FieldSpec>, I> {
|
|
1871
|
+
new (values?: Partial<FieldsToInstance<F>> | Buffer): I;
|
|
1872
|
+
new (...values: any[]): I;
|
|
1873
|
+
readonly size: number;
|
|
1874
|
+
readonly alignment: number;
|
|
1875
|
+
readonly fields: FieldDef[];
|
|
1876
|
+
create(values?: Partial<FieldsToInstance<F>> | Buffer): I;
|
|
1877
|
+
toObject(bufOrInstance: Buffer | I): FieldsToInstance<F>;
|
|
1878
|
+
from_buffer(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
|
|
1879
|
+
from_buffer_copy(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
|
|
1880
|
+
from_address(address: bigint | number): I;
|
|
1881
|
+
in_dll(library: CDLL | Library, name: string): I;
|
|
1882
|
+
}
|
|
1751
1883
|
|
|
1752
1884
|
/**
|
|
1753
1885
|
* Define a fixed-size array type.
|
|
@@ -1766,18 +1898,21 @@ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new
|
|
|
1766
1898
|
*
|
|
1767
1899
|
* @category Structures
|
|
1768
1900
|
*/
|
|
1769
|
-
export function array<E extends
|
|
1901
|
+
export function array<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
|
|
1902
|
+
|
|
1903
|
+
/** Element types of {@link array}: C types, structures and unions (classes or definitions), arrays, pointers, function pointers. */
|
|
1904
|
+
type ArrayElementType = SimpleCDataConstructor | StructDef | UnionDef | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory;
|
|
1770
1905
|
|
|
1771
1906
|
/**
|
|
1772
1907
|
* Alias of {@link array}. Python equivalent: `ctypes.ARRAY(type, length)`.
|
|
1773
1908
|
* @category Structures
|
|
1774
1909
|
*/
|
|
1775
|
-
export function ARRAY<E extends
|
|
1910
|
+
export function ARRAY<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
|
|
1776
1911
|
|
|
1777
1912
|
/**
|
|
1778
1913
|
* Define a bit field for use in struct `_fields_`.
|
|
1779
1914
|
*
|
|
1780
|
-
* @param baseType - The underlying integer type (e.g. `c_uint32`)
|
|
1915
|
+
* @param baseType - The underlying integer type (e.g. `c_uint32`) or `c_bool`; other types raise TypeError, as in Python
|
|
1781
1916
|
* @param bits - Number of bits
|
|
1782
1917
|
*
|
|
1783
1918
|
* @example
|
|
@@ -1792,7 +1927,7 @@ export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | Pointe
|
|
|
1792
1927
|
*
|
|
1793
1928
|
* @category Structures
|
|
1794
1929
|
*/
|
|
1795
|
-
export function bitfield(baseType:
|
|
1930
|
+
export function bitfield(baseType: SimpleCDataConstructor, bits: number): BitFieldDef;
|
|
1796
1931
|
|
|
1797
1932
|
/**
|
|
1798
1933
|
* Pass an object by reference (returns its underlying buffer).
|
|
@@ -1956,7 +2091,7 @@ export function set_last_error(code: number): number;
|
|
|
1956
2091
|
* @category Error Handling
|
|
1957
2092
|
*/
|
|
1958
2093
|
export class ArgumentError extends TypeError {
|
|
1959
|
-
constructor(message?: string);
|
|
2094
|
+
constructor(message?: string, options?: ErrorOptions);
|
|
1960
2095
|
}
|
|
1961
2096
|
|
|
1962
2097
|
/**
|
|
@@ -1976,11 +2111,12 @@ export function FormatError(code?: number): string;
|
|
|
1976
2111
|
* Python equivalent: `ctypes.WinError()`
|
|
1977
2112
|
*
|
|
1978
2113
|
* @param code - Error code (defaults to `GetLastError()`)
|
|
1979
|
-
* @
|
|
2114
|
+
* @param descr - Message (defaults to `FormatError(code)`)
|
|
2115
|
+
* @returns Error with `winerror`, `errno` (mapped as Python's OSError) and `strerror`
|
|
1980
2116
|
*
|
|
1981
2117
|
* @category Error Handling
|
|
1982
2118
|
*/
|
|
1983
|
-
export function WinError(code?: number): Error & { winerror: number };
|
|
2119
|
+
export function WinError(code?: number | null, descr?: string): Error & { winerror: number; errno: number; strerror: string };
|
|
1984
2120
|
|
|
1985
2121
|
// =============================================================================
|
|
1986
2122
|
// SimpleCData - Base class for simple C data types
|
|
@@ -2393,6 +2529,15 @@ export const SimpleCData: SimpleCDataConstructor;
|
|
|
2393
2529
|
*/
|
|
2394
2530
|
export const POINTER_SIZE: number;
|
|
2395
2531
|
|
|
2532
|
+
/**
|
|
2533
|
+
* `false` where the runtime does not allow Buffers over native memory
|
|
2534
|
+
* (Electron, or `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`). ctypes instances on
|
|
2535
|
+
* native memory (`from_address`, `in_dll`, pointers) then work on a
|
|
2536
|
+
* synchronized copy, and their `_buffer` is that copy.
|
|
2537
|
+
* @category Constants
|
|
2538
|
+
*/
|
|
2539
|
+
export const EXTERNAL_BUFFERS: boolean;
|
|
2540
|
+
|
|
2396
2541
|
/**
|
|
2397
2542
|
* Size of `wchar_t` in bytes (2 on Windows, 4 on Unix).
|
|
2398
2543
|
* @category Constants
|
|
@@ -2440,8 +2585,9 @@ export const DEFAULT_MODE: number;
|
|
|
2440
2585
|
* are provided (e.g. `"c"` → `"msvcrt.dll"`).
|
|
2441
2586
|
* - On Linux, the `ldconfig` cache and common library directories are
|
|
2442
2587
|
* searched for the best-matching `libNAME.so.VERSION`.
|
|
2443
|
-
* - On macOS,
|
|
2444
|
-
*
|
|
2588
|
+
* - On macOS, the `DYLD_*` paths, the dyld fallback directories, Homebrew and
|
|
2589
|
+
* the framework directories are searched, including the dyld shared cache
|
|
2590
|
+
* (system libraries and frameworks are not on disk since macOS 11).
|
|
2445
2591
|
*
|
|
2446
2592
|
* Returns `null` if the input is invalid. Returns a best-effort fallback
|
|
2447
2593
|
* (bare soname) if nothing is found, so the loader can still try its own
|
package/lib/index.js
CHANGED
|
@@ -39,11 +39,11 @@ import {
|
|
|
39
39
|
memset as _memset,
|
|
40
40
|
} from "./memory/buffer.js";
|
|
41
41
|
import { createMemoryOps } from "./memory/operations.js";
|
|
42
|
+
import { enableMirrors, wrapNative } from "./memory/mirror.js";
|
|
42
43
|
import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as _ptrToBuffer, POINTER as _POINTER, pointer as _pointer } from "./memory/pointer.js";
|
|
43
44
|
import { FormatError as _FormatError, WinError as _WinError, ArgumentError } from "./platform/errors.js";
|
|
44
45
|
import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
|
|
45
46
|
import { array as _array } from "./structures/helpers/array.js";
|
|
46
|
-
import { _readBitField as _readBitFieldHelper, _writeBitField as _writeBitFieldHelper, _readUintFromBuffer, _writeUintToBuffer } from "./structures/helpers/bitfield.js";
|
|
47
47
|
import { union as _union } from "./structures/helpers/union.js";
|
|
48
48
|
import { struct as _struct } from "./structures/helpers/struct.js";
|
|
49
49
|
import { createStructureClass } from "./structures/Structure.js";
|
|
@@ -98,7 +98,14 @@ const findNativeModule = () => {
|
|
|
98
98
|
};
|
|
99
99
|
|
|
100
100
|
const require = createRequire(import.meta.url);
|
|
101
|
-
const
|
|
101
|
+
const rawNative = require(findNativeModule());
|
|
102
|
+
|
|
103
|
+
// Senza Buffer esterni (Electron) le view sulla memoria nativa diventano copie
|
|
104
|
+
// sincronizzate (memory/mirror.js). NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 forza la
|
|
105
|
+
// stessa modalità su Node.js, per provarla senza Electron.
|
|
106
|
+
const externalBuffers = rawNative.externalBuffersAllowed !== false && process.env.NODE_CTYPES_NO_EXTERNAL_BUFFERS !== "1";
|
|
107
|
+
if (!externalBuffers) enableMirrors(rawNative);
|
|
108
|
+
const native = externalBuffers ? rawNative : wrapNative(rawNative);
|
|
102
109
|
|
|
103
110
|
// Initialize platform constants from native module
|
|
104
111
|
_initConstants(native);
|
|
@@ -256,12 +263,24 @@ function cast(ptr, targetType) {
|
|
|
256
263
|
return _cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native);
|
|
257
264
|
}
|
|
258
265
|
|
|
266
|
+
// Uso interno (from_address, cast, ...): una view della memoria nativa, o una
|
|
267
|
+
// copia sincronizzata dove i Buffer esterni non sono permessi.
|
|
259
268
|
function ptrToBuffer(address, size) {
|
|
260
269
|
return _ptrToBuffer(address, size, native);
|
|
261
270
|
}
|
|
262
271
|
|
|
272
|
+
// Python: POINTER(T) is POINTER(T) e (T * n) is (T * n): un tipo per base.
|
|
273
|
+
const pointerTypes = new WeakMap();
|
|
274
|
+
const arrayTypes = new WeakMap();
|
|
275
|
+
|
|
263
276
|
function POINTER(baseType) {
|
|
264
|
-
|
|
277
|
+
const cacheable = baseType !== null && (typeof baseType === "object" || typeof baseType === "function");
|
|
278
|
+
let type = cacheable ? pointerTypes.get(baseType) : undefined;
|
|
279
|
+
if (type === undefined) {
|
|
280
|
+
type = _POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native);
|
|
281
|
+
if (cacheable) pointerTypes.set(baseType, type);
|
|
282
|
+
}
|
|
283
|
+
return type;
|
|
265
284
|
}
|
|
266
285
|
|
|
267
286
|
/**
|
|
@@ -281,7 +300,7 @@ function POINTER(baseType) {
|
|
|
281
300
|
* ```
|
|
282
301
|
*/
|
|
283
302
|
function pointer(obj) {
|
|
284
|
-
return _pointer(obj,
|
|
303
|
+
return _pointer(obj, POINTER, sizeof, alloc, readValue, writeValue, c_void_p, native);
|
|
285
304
|
}
|
|
286
305
|
|
|
287
306
|
/**
|
|
@@ -310,8 +329,8 @@ function defineStruct(fields, options) {
|
|
|
310
329
|
/**
|
|
311
330
|
* Helper to define a JS class backed by a union definition.
|
|
312
331
|
*/
|
|
313
|
-
function defineUnion(fields) {
|
|
314
|
-
const def = union(fields);
|
|
332
|
+
function defineUnion(fields, options) {
|
|
333
|
+
const def = union(fields, options);
|
|
315
334
|
class AutoUnion extends Union {}
|
|
316
335
|
AutoUnion._structDef = def;
|
|
317
336
|
AutoUnion._fields_ = fields;
|
|
@@ -352,7 +371,17 @@ memoryDeps.Union = Union;
|
|
|
352
371
|
* console.log(arr[2]); // 42
|
|
353
372
|
*/
|
|
354
373
|
function array(elementType, count) {
|
|
355
|
-
|
|
374
|
+
const cacheable = elementType !== null && (typeof elementType === "object" || typeof elementType === "function");
|
|
375
|
+
let byCount = cacheable ? arrayTypes.get(elementType) : undefined;
|
|
376
|
+
let type = byCount?.get(count);
|
|
377
|
+
if (type === undefined) {
|
|
378
|
+
type = _array(elementType, count, sizeof, alloc, readValue, writeValue, Structure, Union, ArrayType, c_void_p, ptrToBuffer);
|
|
379
|
+
if (cacheable) {
|
|
380
|
+
if (byCount === undefined) arrayTypes.set(elementType, (byCount = new Map()));
|
|
381
|
+
byCount.set(count, type);
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
return type;
|
|
356
385
|
}
|
|
357
386
|
|
|
358
387
|
// ============================================================================
|
|
@@ -403,9 +432,9 @@ function FormatError(code) {
|
|
|
403
432
|
return _FormatError(code, WinDLL, alloc, c_uint32, c_void, c_void_p);
|
|
404
433
|
}
|
|
405
434
|
|
|
406
|
-
function WinError(code) {
|
|
407
|
-
if (code === undefined) code = native.getCapturedLastError();
|
|
408
|
-
return _WinError(code, WinDLL, alloc, c_uint32, c_void, c_void_p);
|
|
435
|
+
function WinError(code, descr) {
|
|
436
|
+
if (code === undefined || code === null) code = native.getCapturedLastError();
|
|
437
|
+
return _WinError(code, WinDLL, alloc, c_uint32, c_void, c_void_p, descr ?? undefined);
|
|
409
438
|
}
|
|
410
439
|
|
|
411
440
|
/**
|
|
@@ -414,26 +443,16 @@ function WinError(code) {
|
|
|
414
443
|
* @param {number} bits - Numero di bit
|
|
415
444
|
* @returns {Object} Definizione del bit field
|
|
416
445
|
*/
|
|
446
|
+
// Python: bitfield solo su interi e c_bool.
|
|
447
|
+
const bitFieldTypes = new Set([CType.INT8, CType.UINT8, CType.INT16, CType.UINT16, CType.INT32, CType.UINT32, CType.INT64, CType.UINT64, CType.LONG, CType.ULONG, CType.SIZE_T, CType.SSIZE_T, CType.BOOL]);
|
|
448
|
+
|
|
417
449
|
function bitfield(baseType, bits) {
|
|
450
|
+
if (typeof baseType === "function" && baseType._isSimpleCData === true && !bitFieldTypes.has(baseType._type)) {
|
|
451
|
+
throw new TypeError(`bit fields not allowed for type ${baseType.name}`);
|
|
452
|
+
}
|
|
418
453
|
return _bitfield(baseType, bits, sizeof);
|
|
419
454
|
}
|
|
420
455
|
|
|
421
|
-
/**
|
|
422
|
-
* Helper per leggere un valore bit field da un buffer
|
|
423
|
-
* @private
|
|
424
|
-
*/
|
|
425
|
-
function _readBitField(buf, offset, baseType, bitOffset, bitSize) {
|
|
426
|
-
return _readBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, sizeof);
|
|
427
|
-
}
|
|
428
|
-
|
|
429
|
-
/**
|
|
430
|
-
* Helper per scrivere un valore bit field in un buffer
|
|
431
|
-
* @private
|
|
432
|
-
*/
|
|
433
|
-
function _writeBitField(buf, offset, baseType, bitOffset, bitSize, newValue) {
|
|
434
|
-
return _writeBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, newValue, sizeof);
|
|
435
|
-
}
|
|
436
|
-
|
|
437
456
|
/**
|
|
438
457
|
* Helper per definire struct con supporto per:
|
|
439
458
|
* - Alignment corretto
|
|
@@ -595,7 +614,6 @@ export {
|
|
|
595
614
|
writeValue,
|
|
596
615
|
sizeof,
|
|
597
616
|
alignment,
|
|
598
|
-
ptrToBuffer,
|
|
599
617
|
|
|
600
618
|
// Strutture
|
|
601
619
|
struct,
|
|
@@ -684,8 +702,13 @@ export {
|
|
|
684
702
|
// Re-export constants from platform module
|
|
685
703
|
export { POINTER_SIZE, WCHAR_SIZE, NULL } from "./platform/constants.js";
|
|
686
704
|
|
|
705
|
+
// false dove i Buffer su memoria nativa non sono permessi (Electron): le
|
|
706
|
+
// istanze su memoria nativa usano una copia sincronizzata (memory/mirror.js).
|
|
707
|
+
export const EXTERNAL_BUFFERS = externalBuffers;
|
|
708
|
+
|
|
687
709
|
// Python ctypes.util.find_library equivalent
|
|
688
|
-
|
|
710
|
+
import { find_library as findLibrary } from "./platform/find_library.js";
|
|
711
|
+
export const find_library = (name) => findLibrary(name, native);
|
|
689
712
|
|
|
690
713
|
// Lazy loader namespaces (Python's `ctypes.cdll.libname` / `ctypes.windll.libname`).
|
|
691
714
|
export const cdll = createLazyLoader(CDLL);
|