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/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.
|
|
@@ -935,9 +969,43 @@ export interface ArrayTypeDef<E = any> {
|
|
|
935
969
|
* Proxy interface for array index access and iteration.
|
|
936
970
|
* @category Structures
|
|
937
971
|
*/
|
|
938
|
-
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
|
+
> {
|
|
939
1003
|
[index: number]: T;
|
|
940
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[];
|
|
941
1009
|
/**
|
|
942
1010
|
* The Buffer of the array: for an array on native memory
|
|
943
1011
|
* ({@link ArrayTypeDef.from_address}) a Buffer over that memory, as
|
|
@@ -951,8 +1019,14 @@ export interface ArrayProxy<T = any> {
|
|
|
951
1019
|
* @category Structures
|
|
952
1020
|
*/
|
|
953
1021
|
export interface StructOptions {
|
|
954
|
-
/** If `true`, disables padding between fields. */
|
|
1022
|
+
/** If `true`, disables padding between fields (as `pack: 1`). */
|
|
955
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;
|
|
956
1030
|
}
|
|
957
1031
|
|
|
958
1032
|
/**
|
|
@@ -1241,6 +1315,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1241
1315
|
*/
|
|
1242
1316
|
static _pack_?: number | boolean;
|
|
1243
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
|
+
|
|
1244
1327
|
/**
|
|
1245
1328
|
* List of field names whose members are promoted to the parent struct.
|
|
1246
1329
|
*
|
|
@@ -1248,6 +1331,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1248
1331
|
*/
|
|
1249
1332
|
static _anonymous_?: ReadonlyArray<string>;
|
|
1250
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
|
+
|
|
1251
1343
|
/** Create instance with optional initial values. */
|
|
1252
1344
|
static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
|
|
1253
1345
|
|
|
@@ -1260,14 +1352,14 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1260
1352
|
*
|
|
1261
1353
|
* Python ctypes parity: `Structure.from_buffer(source, offset=0)`.
|
|
1262
1354
|
*/
|
|
1263
|
-
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;
|
|
1264
1356
|
|
|
1265
1357
|
/**
|
|
1266
1358
|
* Create an instance whose buffer is an independent copy of the source bytes.
|
|
1267
1359
|
*
|
|
1268
1360
|
* Python ctypes parity: `Structure.from_buffer_copy(source, offset=0)`.
|
|
1269
1361
|
*/
|
|
1270
|
-
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;
|
|
1271
1363
|
|
|
1272
1364
|
/**
|
|
1273
1365
|
* Create an instance that views raw memory at `address`. Caller is
|
|
@@ -1301,7 +1393,10 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1301
1393
|
/** Convert all fields to a plain JavaScript object (snapshot). */
|
|
1302
1394
|
toObject(): FieldsToInstance<F>;
|
|
1303
1395
|
|
|
1304
|
-
/**
|
|
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). */
|
|
1305
1400
|
[field: string]: any;
|
|
1306
1401
|
}
|
|
1307
1402
|
|
|
@@ -1624,6 +1719,13 @@ export function wstring_at(address: Buffer | bigint | number, size?: number): st
|
|
|
1624
1719
|
*/
|
|
1625
1720
|
export function addressof(ptr: Buffer | bigint | number): bigint;
|
|
1626
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
|
+
|
|
1627
1729
|
/**
|
|
1628
1730
|
* Copy memory from source to destination.
|
|
1629
1731
|
*
|
|
@@ -1631,9 +1733,6 @@ export function addressof(ptr: Buffer | bigint | number): bigint;
|
|
|
1631
1733
|
*
|
|
1632
1734
|
* @category Memory
|
|
1633
1735
|
*/
|
|
1634
|
-
/** Memory argument of {@link memmove} / {@link memset}: a buffer, a ctypes instance, a pointer or an address. */
|
|
1635
|
-
export type MemoryTarget = Uint8Array | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
|
|
1636
|
-
|
|
1637
1736
|
export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): void;
|
|
1638
1737
|
|
|
1639
1738
|
/**
|
|
@@ -1661,8 +1760,8 @@ export function memset(dst: MemoryTarget, value: number, count: number): void;
|
|
|
1661
1760
|
*
|
|
1662
1761
|
* @category Memory
|
|
1663
1762
|
*/
|
|
1664
|
-
export function readValue<T extends AnyType>(ptr:
|
|
1665
|
-
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;
|
|
1666
1765
|
|
|
1667
1766
|
/**
|
|
1668
1767
|
* Write a typed value to a buffer at a given offset.
|
|
@@ -1674,8 +1773,8 @@ export function readValue(ptr: Buffer | bigint | number | PointerInstance, type:
|
|
|
1674
1773
|
*
|
|
1675
1774
|
* @category Memory
|
|
1676
1775
|
*/
|
|
1677
|
-
export function writeValue<T extends AnyType>(ptr:
|
|
1678
|
-
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;
|
|
1679
1778
|
|
|
1680
1779
|
/**
|
|
1681
1780
|
* Get the size of a type in bytes.
|
|
@@ -1691,7 +1790,10 @@ export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type
|
|
|
1691
1790
|
*
|
|
1692
1791
|
* @category Memory
|
|
1693
1792
|
*/
|
|
1694
|
-
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;
|
|
1695
1797
|
|
|
1696
1798
|
/**
|
|
1697
1799
|
* Get the alignment requirement of a type in bytes.
|
|
@@ -1734,10 +1836,11 @@ export function struct<F extends Record<string, FieldSpec>>(fields: F, options?:
|
|
|
1734
1836
|
* For Python-like class syntax, use {@link Union} instead.
|
|
1735
1837
|
*
|
|
1736
1838
|
* @param fields - Object mapping field names to types
|
|
1839
|
+
* @param options - Union options (e.g. `{ pack: 1 }`)
|
|
1737
1840
|
*
|
|
1738
1841
|
* @category Structures
|
|
1739
1842
|
*/
|
|
1740
|
-
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>;
|
|
1741
1844
|
|
|
1742
1845
|
/**
|
|
1743
1846
|
* Factory that returns a Structure subclass with typed fields.
|
|
@@ -1747,7 +1850,7 @@ export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<
|
|
|
1747
1850
|
*
|
|
1748
1851
|
* @category Structures
|
|
1749
1852
|
*/
|
|
1750
|
-
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>>;
|
|
1751
1854
|
|
|
1752
1855
|
/**
|
|
1753
1856
|
* Factory that returns a Union subclass with typed fields.
|
|
@@ -1756,7 +1859,27 @@ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, opt
|
|
|
1756
1859
|
*
|
|
1757
1860
|
* @category Structures
|
|
1758
1861
|
*/
|
|
1759
|
-
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
|
+
}
|
|
1760
1883
|
|
|
1761
1884
|
/**
|
|
1762
1885
|
* Define a fixed-size array type.
|
|
@@ -1775,18 +1898,21 @@ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new
|
|
|
1775
1898
|
*
|
|
1776
1899
|
* @category Structures
|
|
1777
1900
|
*/
|
|
1778
|
-
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;
|
|
1779
1905
|
|
|
1780
1906
|
/**
|
|
1781
1907
|
* Alias of {@link array}. Python equivalent: `ctypes.ARRAY(type, length)`.
|
|
1782
1908
|
* @category Structures
|
|
1783
1909
|
*/
|
|
1784
|
-
export function ARRAY<E extends
|
|
1910
|
+
export function ARRAY<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
|
|
1785
1911
|
|
|
1786
1912
|
/**
|
|
1787
1913
|
* Define a bit field for use in struct `_fields_`.
|
|
1788
1914
|
*
|
|
1789
|
-
* @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
|
|
1790
1916
|
* @param bits - Number of bits
|
|
1791
1917
|
*
|
|
1792
1918
|
* @example
|
|
@@ -1801,7 +1927,7 @@ export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | Pointe
|
|
|
1801
1927
|
*
|
|
1802
1928
|
* @category Structures
|
|
1803
1929
|
*/
|
|
1804
|
-
export function bitfield(baseType:
|
|
1930
|
+
export function bitfield(baseType: SimpleCDataConstructor, bits: number): BitFieldDef;
|
|
1805
1931
|
|
|
1806
1932
|
/**
|
|
1807
1933
|
* Pass an object by reference (returns its underlying buffer).
|
|
@@ -1965,7 +2091,7 @@ export function set_last_error(code: number): number;
|
|
|
1965
2091
|
* @category Error Handling
|
|
1966
2092
|
*/
|
|
1967
2093
|
export class ArgumentError extends TypeError {
|
|
1968
|
-
constructor(message?: string);
|
|
2094
|
+
constructor(message?: string, options?: ErrorOptions);
|
|
1969
2095
|
}
|
|
1970
2096
|
|
|
1971
2097
|
/**
|
|
@@ -1985,11 +2111,12 @@ export function FormatError(code?: number): string;
|
|
|
1985
2111
|
* Python equivalent: `ctypes.WinError()`
|
|
1986
2112
|
*
|
|
1987
2113
|
* @param code - Error code (defaults to `GetLastError()`)
|
|
1988
|
-
* @
|
|
2114
|
+
* @param descr - Message (defaults to `FormatError(code)`)
|
|
2115
|
+
* @returns Error with `winerror`, `errno` (mapped as Python's OSError) and `strerror`
|
|
1989
2116
|
*
|
|
1990
2117
|
* @category Error Handling
|
|
1991
2118
|
*/
|
|
1992
|
-
export function WinError(code?: number): Error & { winerror: number };
|
|
2119
|
+
export function WinError(code?: number | null, descr?: string): Error & { winerror: number; errno: number; strerror: string };
|
|
1993
2120
|
|
|
1994
2121
|
// =============================================================================
|
|
1995
2122
|
// SimpleCData - Base class for simple C data types
|
|
@@ -2458,8 +2585,9 @@ export const DEFAULT_MODE: number;
|
|
|
2458
2585
|
* are provided (e.g. `"c"` → `"msvcrt.dll"`).
|
|
2459
2586
|
* - On Linux, the `ldconfig` cache and common library directories are
|
|
2460
2587
|
* searched for the best-matching `libNAME.so.VERSION`.
|
|
2461
|
-
* - On macOS,
|
|
2462
|
-
*
|
|
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).
|
|
2463
2591
|
*
|
|
2464
2592
|
* Returns `null` if the input is invalid. Returns a best-effort fallback
|
|
2465
2593
|
* (bare soname) if nothing is found, so the loader can still try its own
|
package/lib/index.js
CHANGED
|
@@ -44,7 +44,6 @@ import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as
|
|
|
44
44
|
import { FormatError as _FormatError, WinError as _WinError, ArgumentError } from "./platform/errors.js";
|
|
45
45
|
import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
|
|
46
46
|
import { array as _array } from "./structures/helpers/array.js";
|
|
47
|
-
import { _readBitField as _readBitFieldHelper, _writeBitField as _writeBitFieldHelper, _readUintFromBuffer, _writeUintToBuffer } from "./structures/helpers/bitfield.js";
|
|
48
47
|
import { union as _union } from "./structures/helpers/union.js";
|
|
49
48
|
import { struct as _struct } from "./structures/helpers/struct.js";
|
|
50
49
|
import { createStructureClass } from "./structures/Structure.js";
|
|
@@ -270,8 +269,18 @@ function ptrToBuffer(address, size) {
|
|
|
270
269
|
return _ptrToBuffer(address, size, native);
|
|
271
270
|
}
|
|
272
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
|
+
|
|
273
276
|
function POINTER(baseType) {
|
|
274
|
-
|
|
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;
|
|
275
284
|
}
|
|
276
285
|
|
|
277
286
|
/**
|
|
@@ -291,7 +300,7 @@ function POINTER(baseType) {
|
|
|
291
300
|
* ```
|
|
292
301
|
*/
|
|
293
302
|
function pointer(obj) {
|
|
294
|
-
return _pointer(obj,
|
|
303
|
+
return _pointer(obj, POINTER, sizeof, alloc, readValue, writeValue, c_void_p, native);
|
|
295
304
|
}
|
|
296
305
|
|
|
297
306
|
/**
|
|
@@ -320,8 +329,8 @@ function defineStruct(fields, options) {
|
|
|
320
329
|
/**
|
|
321
330
|
* Helper to define a JS class backed by a union definition.
|
|
322
331
|
*/
|
|
323
|
-
function defineUnion(fields) {
|
|
324
|
-
const def = union(fields);
|
|
332
|
+
function defineUnion(fields, options) {
|
|
333
|
+
const def = union(fields, options);
|
|
325
334
|
class AutoUnion extends Union {}
|
|
326
335
|
AutoUnion._structDef = def;
|
|
327
336
|
AutoUnion._fields_ = fields;
|
|
@@ -362,7 +371,17 @@ memoryDeps.Union = Union;
|
|
|
362
371
|
* console.log(arr[2]); // 42
|
|
363
372
|
*/
|
|
364
373
|
function array(elementType, count) {
|
|
365
|
-
|
|
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;
|
|
366
385
|
}
|
|
367
386
|
|
|
368
387
|
// ============================================================================
|
|
@@ -413,9 +432,9 @@ function FormatError(code) {
|
|
|
413
432
|
return _FormatError(code, WinDLL, alloc, c_uint32, c_void, c_void_p);
|
|
414
433
|
}
|
|
415
434
|
|
|
416
|
-
function WinError(code) {
|
|
417
|
-
if (code === undefined) code = native.getCapturedLastError();
|
|
418
|
-
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);
|
|
419
438
|
}
|
|
420
439
|
|
|
421
440
|
/**
|
|
@@ -424,26 +443,16 @@ function WinError(code) {
|
|
|
424
443
|
* @param {number} bits - Numero di bit
|
|
425
444
|
* @returns {Object} Definizione del bit field
|
|
426
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
|
+
|
|
427
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
|
+
}
|
|
428
453
|
return _bitfield(baseType, bits, sizeof);
|
|
429
454
|
}
|
|
430
455
|
|
|
431
|
-
/**
|
|
432
|
-
* Helper per leggere un valore bit field da un buffer
|
|
433
|
-
* @private
|
|
434
|
-
*/
|
|
435
|
-
function _readBitField(buf, offset, baseType, bitOffset, bitSize) {
|
|
436
|
-
return _readBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, sizeof);
|
|
437
|
-
}
|
|
438
|
-
|
|
439
|
-
/**
|
|
440
|
-
* Helper per scrivere un valore bit field in un buffer
|
|
441
|
-
* @private
|
|
442
|
-
*/
|
|
443
|
-
function _writeBitField(buf, offset, baseType, bitOffset, bitSize, newValue) {
|
|
444
|
-
return _writeBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, newValue, sizeof);
|
|
445
|
-
}
|
|
446
|
-
|
|
447
456
|
/**
|
|
448
457
|
* Helper per definire struct con supporto per:
|
|
449
458
|
* - Alignment corretto
|
|
@@ -698,7 +707,8 @@ export { POINTER_SIZE, WCHAR_SIZE, NULL } from "./platform/constants.js";
|
|
|
698
707
|
export const EXTERNAL_BUFFERS = externalBuffers;
|
|
699
708
|
|
|
700
709
|
// Python ctypes.util.find_library equivalent
|
|
701
|
-
|
|
710
|
+
import { find_library as findLibrary } from "./platform/find_library.js";
|
|
711
|
+
export const find_library = (name) => findLibrary(name, native);
|
|
702
712
|
|
|
703
713
|
// Lazy loader namespaces (Python's `ctypes.cdll.libname` / `ctypes.windll.libname`).
|
|
704
714
|
export const cdll = createLazyLoader(CDLL);
|
package/lib/memory/buffer.js
CHANGED
|
@@ -101,7 +101,7 @@ export function decodeWide(buf, wcharSize) {
|
|
|
101
101
|
for (let off = 0; off + 3 < buf.length; off += 4) {
|
|
102
102
|
const cp = buf.readUInt32LE(off);
|
|
103
103
|
if (cp === 0) break;
|
|
104
|
-
out += String.fromCodePoint(cp);
|
|
104
|
+
out += String.fromCodePoint(cp > 0x10ffff ? 0xfffd : cp);
|
|
105
105
|
}
|
|
106
106
|
return out;
|
|
107
107
|
}
|
|
@@ -392,7 +392,7 @@ export function create_unicode_buffer(init, size, native) {
|
|
|
392
392
|
* ```
|
|
393
393
|
*/
|
|
394
394
|
export function string_at(address, size, native) {
|
|
395
|
-
return native.readCString(address, size);
|
|
395
|
+
return native.readCString(stringSource(address, native), size);
|
|
396
396
|
}
|
|
397
397
|
|
|
398
398
|
/**
|
|
@@ -420,10 +420,20 @@ export function string_at(address, size, native) {
|
|
|
420
420
|
* ```
|
|
421
421
|
*/
|
|
422
422
|
export function wstring_at(address, size, native) {
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
423
|
+
return native.readWString(stringSource(address, native), size);
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/**
|
|
427
|
+
* Source of string_at / wstring_at, as Python's c_void_p.from_param: the
|
|
428
|
+
* memory of instances and arrays, the value of pointers, c_void_p, c_char_p
|
|
429
|
+
* and c_wchar_p, `_as_parameter_`. Buffer or address; NULL gives null.
|
|
430
|
+
*/
|
|
431
|
+
function stringSource(value, native) {
|
|
432
|
+
if (value === null || value === undefined || typeof value === "bigint" || typeof value === "number") return value;
|
|
433
|
+
// Array proxies pass Buffer.isBuffer but are resolved through _buffer.
|
|
434
|
+
if (Buffer.isBuffer(value) && value._buffer === undefined) return mirrorAddress(value) ?? value;
|
|
435
|
+
const memory = memoryOf(value, native, "address", true);
|
|
436
|
+
return memory instanceof Uint8Array && !Buffer.isBuffer(memory) ? Buffer.from(memory.buffer, memory.byteOffset, memory.byteLength) : memory;
|
|
427
437
|
}
|
|
428
438
|
|
|
429
439
|
/**
|
|
@@ -456,26 +466,44 @@ export function memmove(dst, src, count, native) {
|
|
|
456
466
|
if (typeof to !== "bigint") n = Math.min(n, to.length);
|
|
457
467
|
if (typeof from !== "bigint") n = Math.min(n, from.length);
|
|
458
468
|
if (n <= 0) return;
|
|
459
|
-
|
|
469
|
+
// TypedArray.set gestisce anche la sovrapposizione (stesso ArrayBuffer).
|
|
470
|
+
if (typeof to !== "bigint" && typeof from !== "bigint") to.set(n === from.length ? from : from.subarray(0, n));
|
|
460
471
|
else native.memmove(to, from, n);
|
|
461
472
|
}
|
|
462
473
|
|
|
463
|
-
// Memoria di un argomento di memmove/memset, come Python: Buffer,
|
|
464
|
-
//
|
|
474
|
+
// Memoria di un argomento di memmove/memset, come Python: Buffer, ogni
|
|
475
|
+
// TypedArray/DataView/ArrayBuffer (come vista a byte), istanze ctypes (struct,
|
|
476
|
+
// array, c_*), puntatori o un indirizzo (BigInt/number).
|
|
465
477
|
// Gli indirizzi (anche quello originale di una copia, memory/mirror.js) sono
|
|
466
478
|
// letti e scritti dal nativo, senza creare un Buffer esterno.
|
|
467
|
-
function memoryOf(value, native, name) {
|
|
479
|
+
function memoryOf(value, native, name, allowNull = false) {
|
|
468
480
|
if (value !== null && typeof value === "object") {
|
|
481
|
+
// c_void_p / c_char_p / c_wchar_p: the memory they point to, as in Python.
|
|
482
|
+
const T = value.constructor;
|
|
483
|
+
if (T?._isSimpleCData === true && (T._type === native.CType.POINTER || T._type === native.CType.STRING || T._type === native.CType.WSTRING)) {
|
|
484
|
+
const slot = value._buffer;
|
|
485
|
+
return addressOrNull(native.POINTER_SIZE === 8 ? slot.readBigUInt64LE(0) : BigInt(slot.readUInt32LE(0)), name, allowNull);
|
|
486
|
+
}
|
|
469
487
|
if (Buffer.isBuffer(value._buffer)) return mirrorAddress(value._buffer) ?? value._buffer;
|
|
470
|
-
if (value._pointerType !== undefined) return addressOrNull(value.address, name);
|
|
471
|
-
if (
|
|
488
|
+
if (value._pointerType !== undefined) return addressOrNull(value.address, name, allowNull);
|
|
489
|
+
if (ArrayBuffer.isView(value)) {
|
|
490
|
+
return mirrorAddress(value) ?? (value instanceof Uint8Array ? value : new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
|
|
491
|
+
}
|
|
492
|
+
if (value instanceof ArrayBuffer || (typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer)) {
|
|
493
|
+
return new Uint8Array(value);
|
|
494
|
+
}
|
|
495
|
+
if (value._as_parameter_ !== undefined) return memoryOf(value._as_parameter_, native, name, allowNull);
|
|
472
496
|
}
|
|
473
|
-
if (typeof value === "bigint" || typeof value === "number") return addressOrNull(value, name);
|
|
497
|
+
if (typeof value === "bigint" || typeof value === "number") return addressOrNull(value, name, allowNull);
|
|
498
|
+
if (allowNull && value === null) return null;
|
|
474
499
|
throw new TypeError(`${name} must be a Buffer, a ctypes instance, a pointer or an address`);
|
|
475
500
|
}
|
|
476
501
|
|
|
477
|
-
function addressOrNull(value, name) {
|
|
478
|
-
if (!value)
|
|
502
|
+
function addressOrNull(value, name, allowNull = false) {
|
|
503
|
+
if (!value) {
|
|
504
|
+
if (allowNull) return null;
|
|
505
|
+
throw new TypeError(`${name} is a NULL pointer`);
|
|
506
|
+
}
|
|
479
507
|
return BigInt(value);
|
|
480
508
|
}
|
|
481
509
|
|
|
@@ -502,7 +530,8 @@ function addressOrNull(value, name) {
|
|
|
502
530
|
export function memset(dst, value, count, native) {
|
|
503
531
|
const to = memoryOf(dst, native, "dst");
|
|
504
532
|
if (typeof to !== "bigint") {
|
|
505
|
-
|
|
533
|
+
// Come memmove, si ferma alla fine della memoria JS.
|
|
534
|
+
to.fill(value, 0, Math.max(0, Math.min(count, to.length)));
|
|
506
535
|
} else if (count > 0) {
|
|
507
536
|
native.memmove(to, Buffer.alloc(count, value), count);
|
|
508
537
|
}
|