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
package/lib/index.d.ts
CHANGED
|
@@ -134,7 +134,7 @@ export type FFIType = AnyType | StructureClass | PointerTypeDef | ArrayTypeDef |
|
|
|
134
134
|
* @example
|
|
135
135
|
* ```javascript
|
|
136
136
|
* import { Version } from 'node-ctypes';
|
|
137
|
-
* console.log(Version.toString()); // "2.
|
|
137
|
+
* console.log(Version.toString()); // "2.4.0"
|
|
138
138
|
* ```
|
|
139
139
|
*
|
|
140
140
|
* @category Library Loading
|
|
@@ -172,13 +172,20 @@ export class Library {
|
|
|
172
172
|
*/
|
|
173
173
|
symbol(name: string): bigint;
|
|
174
174
|
|
|
175
|
-
/**
|
|
175
|
+
/**
|
|
176
|
+
* Logically close the library. 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
|
+
* Existing `in_dll()` views and dependent memory remain valid and defer
|
|
180
|
+
* native handle release until their last owner is collected.
|
|
181
|
+
* Physical unloading depends on the OS loader; musl keeps modules resident.
|
|
182
|
+
*/
|
|
176
183
|
close(): void;
|
|
177
184
|
|
|
178
185
|
/** Library file path. */
|
|
179
186
|
readonly path: string;
|
|
180
187
|
|
|
181
|
-
/** Whether the library is
|
|
188
|
+
/** Whether the logical library handle is open (not a physical-unload probe). */
|
|
182
189
|
readonly loaded: boolean;
|
|
183
190
|
}
|
|
184
191
|
|
|
@@ -221,6 +228,7 @@ export interface FFIFunction {
|
|
|
221
228
|
|
|
222
229
|
/** The function address as BigInt. */
|
|
223
230
|
readonly address: bigint;
|
|
231
|
+
readonly _as_parameter_: bigint;
|
|
224
232
|
|
|
225
233
|
/**
|
|
226
234
|
* Error checking callback, called after every invocation (`null` when not set).
|
|
@@ -244,8 +252,8 @@ export interface NativeFFIFunction<TArgs extends readonly FFIType[] = FFIType[],
|
|
|
244
252
|
/** Call the native function asynchronously on a worker thread. */
|
|
245
253
|
callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
|
|
246
254
|
|
|
247
|
-
/** Set (or clear with `null`) the
|
|
248
|
-
setErrcheck(callback:
|
|
255
|
+
/** Set (or clear with `null`) the hook captured at each call's entry, including async calls. */
|
|
256
|
+
setErrcheck(callback: NativeErrcheckCallback<TArgs, TRet> | null): void;
|
|
249
257
|
|
|
250
258
|
/** `GetLastError()` (Windows) or `errno` captured after the last call, with `use_last_error`. */
|
|
251
259
|
getCapturedLastError(): number;
|
|
@@ -260,6 +268,13 @@ export interface NativeFFIFunction<TArgs extends readonly FFIType[] = FFIType[],
|
|
|
260
268
|
readonly address: bigint;
|
|
261
269
|
}
|
|
262
270
|
|
|
271
|
+
/**
|
|
272
|
+
* Low-level errcheck: `func` is the native handle, invoked with `.call()`,
|
|
273
|
+
* not a directly callable JavaScript function.
|
|
274
|
+
* @category Library Loading
|
|
275
|
+
*/
|
|
276
|
+
export type NativeErrcheckCallback<TArgs extends readonly FFIType[] = FFIType[], TRet extends FFIType | null = FFIType> = (result: any, func: NativeFFIFunction<TArgs, TRet>, args: any[]) => any;
|
|
277
|
+
|
|
263
278
|
/**
|
|
264
279
|
* Strongly-typed FFI function returned by `CDLL.func` when the
|
|
265
280
|
* argument types and return type are given as a literal tuple and constant respectively.
|
|
@@ -274,6 +289,7 @@ export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends
|
|
|
274
289
|
callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
|
|
275
290
|
readonly funcName: string;
|
|
276
291
|
readonly address: bigint;
|
|
292
|
+
readonly _as_parameter_: bigint;
|
|
277
293
|
errcheck: ErrcheckCallback | null;
|
|
278
294
|
}
|
|
279
295
|
|
|
@@ -312,13 +328,22 @@ export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends
|
|
|
312
328
|
*/
|
|
313
329
|
export interface LibraryOptions {
|
|
314
330
|
/**
|
|
315
|
-
* `dlopen` flags combined with `
|
|
331
|
+
* `dlopen` flags combined with `RTLD_NOW` (e.g. {@link RTLD_GLOBAL}).
|
|
316
332
|
* Ignored on Windows. Default: {@link DEFAULT_MODE}.
|
|
317
333
|
*
|
|
318
334
|
* Python ctypes parity: the `mode` argument of `CDLL(name, mode)`.
|
|
319
335
|
*/
|
|
320
336
|
mode?: number;
|
|
321
337
|
|
|
338
|
+
/**
|
|
339
|
+
* `LoadLibraryExW` flags (Windows only). Default: `LOAD_LIBRARY_SEARCH_DEFAULT_DIRS`,
|
|
340
|
+
* plus `LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR` (with the path made absolute) when the
|
|
341
|
+
* name contains a path separator.
|
|
342
|
+
*
|
|
343
|
+
* Python ctypes parity: the `winmode` argument of `CDLL(name, winmode=...)`.
|
|
344
|
+
*/
|
|
345
|
+
winmode?: number;
|
|
346
|
+
|
|
322
347
|
/**
|
|
323
348
|
* Maximum size of the internal function cache. Default: 1000.
|
|
324
349
|
*/
|
|
@@ -361,6 +386,7 @@ export class CDLL {
|
|
|
361
386
|
*/
|
|
362
387
|
/** Typed overload: narrows args/return when argTypes is a literal tuple. */
|
|
363
388
|
func<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(name: string, returnType: TRet, argTypes: TArgs, options?: FunctionOptions): TypedFFIFunction<TArgs, TRet>;
|
|
389
|
+
func(name: string): TypedFFIFunction<readonly FFIType[], typeof c_int32>;
|
|
364
390
|
func(name: string, returnType: FFIType | null, argTypes?: FFIType[], options?: FunctionOptions): FFIFunction;
|
|
365
391
|
|
|
366
392
|
/**
|
|
@@ -370,7 +396,14 @@ export class CDLL {
|
|
|
370
396
|
*/
|
|
371
397
|
symbol(name: string): bigint;
|
|
372
398
|
|
|
373
|
-
/**
|
|
399
|
+
/**
|
|
400
|
+
* Close the library and clear the function cache. Functions obtained from
|
|
401
|
+
* it throw when called afterwards. Throws while a call to one of its
|
|
402
|
+
* functions is in progress (from a callback, or a pending `callAsync()`).
|
|
403
|
+
* Existing `in_dll()` views defer native handle release until their dependent
|
|
404
|
+
* memory is collected, but new calls and symbol lookups are rejected.
|
|
405
|
+
* Physical unloading depends on the OS loader; musl keeps modules resident.
|
|
406
|
+
*/
|
|
374
407
|
close(): void;
|
|
375
408
|
|
|
376
409
|
/** Close the library at the end of a `using` block. */
|
|
@@ -380,7 +413,7 @@ export class CDLL {
|
|
|
380
413
|
* Create a native callback bound to this library's context.
|
|
381
414
|
* Call `release()` when it is no longer needed.
|
|
382
415
|
*/
|
|
383
|
-
callback(fn:
|
|
416
|
+
callback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): Callback;
|
|
384
417
|
|
|
385
418
|
/**
|
|
386
419
|
* Read the snapshotted `GetLastError()` (Windows) or `errno` from the most
|
|
@@ -402,7 +435,7 @@ export class CDLL {
|
|
|
402
435
|
/** Library file path. */
|
|
403
436
|
readonly path: string;
|
|
404
437
|
|
|
405
|
-
/** Whether the
|
|
438
|
+
/** Whether the logical handle is open, independently of physical module residency. */
|
|
406
439
|
readonly loaded: boolean;
|
|
407
440
|
|
|
408
441
|
/**
|
|
@@ -489,8 +522,8 @@ export class OleDLL extends WinDLL {
|
|
|
489
522
|
}
|
|
490
523
|
|
|
491
524
|
/**
|
|
492
|
-
* `HRESULT` return type marker.
|
|
493
|
-
*
|
|
525
|
+
* `HRESULT` return type marker. Explicit use as restype enables failure checks
|
|
526
|
+
* for all library loaders and prototype callers, before errcheck.
|
|
494
527
|
*
|
|
495
528
|
* Python equivalent: `ctypes.HRESULT`
|
|
496
529
|
*
|
|
@@ -575,6 +608,7 @@ export const oledll: LibraryNamespace<OleDLL> | undefined;
|
|
|
575
608
|
* @category Callbacks
|
|
576
609
|
*/
|
|
577
610
|
export interface CallbackWrapper {
|
|
611
|
+
readonly _callback: Callback;
|
|
578
612
|
/** The callback function pointer, passable to native functions. */
|
|
579
613
|
readonly pointer: bigint;
|
|
580
614
|
|
|
@@ -593,6 +627,7 @@ export interface CallbackWrapper {
|
|
|
593
627
|
* @category Callbacks
|
|
594
628
|
*/
|
|
595
629
|
export interface ThreadSafeCallbackWrapper extends CallbackWrapper {
|
|
630
|
+
readonly _callback: ThreadSafeCallback;
|
|
596
631
|
/** Keep the Node.js event loop alive until released (the default). */
|
|
597
632
|
ref(): this;
|
|
598
633
|
|
|
@@ -611,10 +646,8 @@ export class Callback {
|
|
|
611
646
|
constructor(fn: Function, returnType: AnyType, argTypes?: AnyType[]);
|
|
612
647
|
/** The callback function pointer, passable to native functions. */
|
|
613
648
|
readonly pointer: bigint;
|
|
614
|
-
/**
|
|
649
|
+
/** Return the function pointer, throwing if the callback has been released. */
|
|
615
650
|
getPointer(): bigint;
|
|
616
|
-
/** Same as `pointer`: lets the callback be passed directly as an argument. */
|
|
617
|
-
readonly _as_parameter_: bigint;
|
|
618
651
|
/** Release the callback and free native resources. Must be called when done. */
|
|
619
652
|
release(): void;
|
|
620
653
|
/**
|
|
@@ -714,7 +747,11 @@ export type FieldSpec = AnyType | StructDef | ArrayTypeDef | BitFieldDef | Anony
|
|
|
714
747
|
*/
|
|
715
748
|
export type JsFromCType<T> =
|
|
716
749
|
T extends SimpleCDataConstructor<infer Tag>
|
|
717
|
-
?
|
|
750
|
+
? T extends { prototype: infer Instance }
|
|
751
|
+
? IsAny<Instance> extends true
|
|
752
|
+
? JsFromTag<Tag>
|
|
753
|
+
: Instance
|
|
754
|
+
: JsFromTag<Tag>
|
|
718
755
|
: T extends BitFieldDef
|
|
719
756
|
? number
|
|
720
757
|
: T extends PointerTypeDef<infer B>
|
|
@@ -772,10 +809,10 @@ type FieldValue<F extends Record<string, FieldSpec>, K extends keyof F> = string
|
|
|
772
809
|
type FieldArg<F extends Record<string, FieldSpec>, K extends keyof F> = string extends keyof F ? any : JsArgFromCType<F[K]>;
|
|
773
810
|
|
|
774
811
|
/**
|
|
775
|
-
*
|
|
776
|
-
*
|
|
812
|
+
* Numeric elements and scalar subclass instances are typed; other element
|
|
813
|
+
* representations retain the existing permissive array API.
|
|
777
814
|
*/
|
|
778
|
-
type ArrayElement<E> = IsAny<E> extends true ? any : JsFromCType<E> extends number ? number : any;
|
|
815
|
+
type ArrayElement<E> = IsAny<E> extends true ? any : JsFromCType<E> extends SimpleCDataInstance<unknown> ? JsFromCType<E> : JsFromCType<E> extends number ? number : any;
|
|
779
816
|
|
|
780
817
|
/** Element accepted when writing an array of `E`. */
|
|
781
818
|
type ArrayElementArg<E> = IsAny<E> extends true ? any : E extends StructureClass ? Buffer | Record<string, any> : JsArgFromCType<E>;
|
|
@@ -784,17 +821,44 @@ type ArrayElementArg<E> = IsAny<E> extends true ? any : E extends StructureClass
|
|
|
784
821
|
type PointerValue<T> = IsAny<T> extends true ? any : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
|
|
785
822
|
|
|
786
823
|
/** `p.contents`: a live instance on the pointed memory (Python parity). */
|
|
787
|
-
type PointerContents<T> =
|
|
824
|
+
type PointerContents<T> =
|
|
825
|
+
IsAny<T> extends true
|
|
826
|
+
? any
|
|
827
|
+
: T extends SimpleCDataConstructor<infer Tag>
|
|
828
|
+
? T extends { prototype: infer Instance }
|
|
829
|
+
? IsAny<Instance> extends true
|
|
830
|
+
? SimpleCDataInstance<JsFromTag<Tag>>
|
|
831
|
+
: Instance
|
|
832
|
+
: SimpleCDataInstance<JsFromTag<Tag>>
|
|
833
|
+
: T extends StructureClass
|
|
834
|
+
? InstanceType<T>
|
|
835
|
+
: JsFromCType<T>;
|
|
788
836
|
|
|
789
837
|
/** `string` for `c_char`/`c_wchar` arrays (read as text, as Python), otherwise `Else`. */
|
|
790
838
|
type CharArrayValue<E, Else> = IsAny<E> extends true ? Else : [E] extends [SimpleCDataConstructor<"char">] ? string : [E] extends [SimpleCDataConstructor<"wchar">] ? string : Else;
|
|
791
839
|
|
|
792
840
|
/**
|
|
793
|
-
* Array instance: a Buffer with index access;
|
|
794
|
-
*
|
|
841
|
+
* Array instance: a Buffer with index access; the Array methods (`slice`, `map`,
|
|
842
|
+
* `includes`, ...) work on the elements, as Python's sequence operations.
|
|
843
|
+
* `c_char` arrays also expose `.value`/`.raw` and `c_wchar` arrays `.value`.
|
|
795
844
|
* @category Structures
|
|
796
845
|
*/
|
|
797
|
-
export type ArrayInstance<E = any> = Buffer
|
|
846
|
+
export type ArrayInstance<E = any> = Omit<Buffer, ElementMethod | "length" | "toJSON" | number> &
|
|
847
|
+
(IsAny<E> extends true
|
|
848
|
+
? ArrayProxy<any>
|
|
849
|
+
: [E] extends [SimpleCDataConstructor<"char">]
|
|
850
|
+
? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & CharBufferValue & CharSlice
|
|
851
|
+
: [E] extends [SimpleCDataConstructor<"wchar">]
|
|
852
|
+
? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & WideBufferValue & CharSlice
|
|
853
|
+
: ArrayProxy<ArrayElement<E>>);
|
|
854
|
+
|
|
855
|
+
/** Array methods that work on the elements of an array instance; the Buffer methods (`readInt32LE`, `subarray`, ...) work on the bytes. */
|
|
856
|
+
type ElementMethod = Exclude<keyof ArrayProxy, number | typeof Symbol.iterator | "length" | "toJSON">;
|
|
857
|
+
|
|
858
|
+
/** `c_char` / `c_wchar` arrays: a slice is a string (Python: bytes / str). */
|
|
859
|
+
interface CharSlice {
|
|
860
|
+
slice(start?: number, end?: number): string;
|
|
861
|
+
}
|
|
798
862
|
|
|
799
863
|
/**
|
|
800
864
|
* Text accessors of `c_char` buffers (arrays, {@link create_string_buffer}).
|
|
@@ -824,17 +888,19 @@ type ArgsFromCTypes<TArgs extends readonly any[]> = {
|
|
|
824
888
|
};
|
|
825
889
|
|
|
826
890
|
/** JS argument accepted for a function parameter of type `T`. */
|
|
827
|
-
type JsArgFromFFIType<T> =
|
|
891
|
+
type JsArgFromFFIType<T> =
|
|
892
|
+
{ readonly _as_parameter_: unknown } | (T extends StructureClass ? Buffer | { _buffer: Buffer } | Record<string, any> : T extends ArrayTypeDef<infer E> ? ArrayInstance<E> | ArrayBufferView | ArrayBuffer : JsArgFromCType<T>);
|
|
828
893
|
|
|
829
894
|
/** Function arguments for `argtypes` `TArgs` (`any[]` when not a literal tuple). */
|
|
830
895
|
type FFIArgs<TArgs extends readonly any[]> = FFIType[] extends TArgs ? any[] : { [K in keyof TArgs]: JsArgFromFFIType<TArgs[K]> };
|
|
831
896
|
|
|
832
897
|
/**
|
|
833
898
|
* 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)
|
|
899
|
+
* `POINTER(T)` restype returns a {@link PointerInstance}, a {@link CFUNCTYPE}
|
|
900
|
+
* restype a callable function (`null` for NULL) and a Structure/Union class an
|
|
901
|
+
* instance of that class.
|
|
836
902
|
*/
|
|
837
|
-
type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends StructureClass ?
|
|
903
|
+
type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends { _check_retval_: (...args: never[]) => infer Result } ? Result : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
|
|
838
904
|
|
|
839
905
|
/**
|
|
840
906
|
* A union type definition created by the {@link union} function.
|
|
@@ -935,9 +1001,43 @@ export interface ArrayTypeDef<E = any> {
|
|
|
935
1001
|
* Proxy interface for array index access and iteration.
|
|
936
1002
|
* @category Structures
|
|
937
1003
|
*/
|
|
938
|
-
export interface ArrayProxy<T = any>
|
|
1004
|
+
export interface ArrayProxy<T = any> extends Pick<
|
|
1005
|
+
T[],
|
|
1006
|
+
| "at"
|
|
1007
|
+
| "copyWithin"
|
|
1008
|
+
| "entries"
|
|
1009
|
+
| "every"
|
|
1010
|
+
| "fill"
|
|
1011
|
+
| "filter"
|
|
1012
|
+
| "find"
|
|
1013
|
+
| "findIndex"
|
|
1014
|
+
| "findLast"
|
|
1015
|
+
| "findLastIndex"
|
|
1016
|
+
| "forEach"
|
|
1017
|
+
| "includes"
|
|
1018
|
+
| "indexOf"
|
|
1019
|
+
| "join"
|
|
1020
|
+
| "keys"
|
|
1021
|
+
| "lastIndexOf"
|
|
1022
|
+
| "map"
|
|
1023
|
+
| "reduce"
|
|
1024
|
+
| "reduceRight"
|
|
1025
|
+
| "reverse"
|
|
1026
|
+
| "slice"
|
|
1027
|
+
| "some"
|
|
1028
|
+
| "sort"
|
|
1029
|
+
| "toLocaleString"
|
|
1030
|
+
| "toReversed"
|
|
1031
|
+
| "toSorted"
|
|
1032
|
+
| "values"
|
|
1033
|
+
| "with"
|
|
1034
|
+
> {
|
|
939
1035
|
[index: number]: T;
|
|
940
1036
|
[Symbol.iterator](): Iterator<T>;
|
|
1037
|
+
/** Number of elements (Python `len(arr)`); the size in bytes is `byteLength`. */
|
|
1038
|
+
readonly length: number;
|
|
1039
|
+
/** The elements, for `JSON.stringify`. */
|
|
1040
|
+
toJSON(): T[];
|
|
941
1041
|
/**
|
|
942
1042
|
* The Buffer of the array: for an array on native memory
|
|
943
1043
|
* ({@link ArrayTypeDef.from_address}) a Buffer over that memory, as
|
|
@@ -951,8 +1051,14 @@ export interface ArrayProxy<T = any> {
|
|
|
951
1051
|
* @category Structures
|
|
952
1052
|
*/
|
|
953
1053
|
export interface StructOptions {
|
|
954
|
-
/** If `true`, disables padding between fields. */
|
|
1054
|
+
/** If `true`, disables padding between fields (as `pack: 1`). */
|
|
955
1055
|
packed?: boolean;
|
|
1056
|
+
/** Maximum field alignment in bytes, as Python's `_pack_`. */
|
|
1057
|
+
pack?: number | boolean | bigint | string | null;
|
|
1058
|
+
/** Bit field layout, as Python's `_layout_` (`"ms"` with `pack`, otherwise the platform's). */
|
|
1059
|
+
layout?: "gcc-sysv" | "ms";
|
|
1060
|
+
/** Minimum alignment in bytes, as Python's `_align_`. */
|
|
1061
|
+
align?: number;
|
|
956
1062
|
}
|
|
957
1063
|
|
|
958
1064
|
/**
|
|
@@ -1164,23 +1270,32 @@ export interface PointerTypeDef<T = any> {
|
|
|
1164
1270
|
|
|
1165
1271
|
/**
|
|
1166
1272
|
* Low-level native struct type. Prefer {@link Structure} for most use cases.
|
|
1273
|
+
* Mutable only until captured by a field, array, prepared function/callback
|
|
1274
|
+
* signature or native value. Finalization includes nested descriptors.
|
|
1275
|
+
* Create a new descriptor rather than modifying a finalized layout.
|
|
1167
1276
|
* @category Structures
|
|
1168
1277
|
*/
|
|
1169
1278
|
export class StructType {
|
|
1170
|
-
constructor(
|
|
1171
|
-
|
|
1279
|
+
constructor(options?: { union?: boolean; alignment?: number; memoryClass?: boolean });
|
|
1280
|
+
/** Append a field while the builder is open; throws after finalization. */
|
|
1281
|
+
addField(name: string, type: number | StructType | ArrayType | { readonly _native: ArrayType }, options?: { anonymous?: boolean }): this;
|
|
1282
|
+
/** Query without finalizing an unused builder. */
|
|
1172
1283
|
getSize(): number;
|
|
1284
|
+
/** Query without finalizing an unused builder. */
|
|
1173
1285
|
getAlignment(): number;
|
|
1174
|
-
|
|
1286
|
+
/** Materialize a value and finalize its layout. */
|
|
1287
|
+
create(values?: Record<string, unknown>): Record<string, unknown> & { readonly _buffer: Buffer };
|
|
1175
1288
|
read(buffer: Buffer): Record<string, any>;
|
|
1289
|
+
toObject(source: Buffer | { readonly _buffer: Buffer }): Record<string, unknown>;
|
|
1176
1290
|
}
|
|
1177
1291
|
|
|
1178
1292
|
/**
|
|
1179
1293
|
* Low-level native array type. Prefer {@link array} for most use cases.
|
|
1294
|
+
* Captures and finalizes an aggregate element's layout, including at length zero.
|
|
1180
1295
|
* @category Structures
|
|
1181
1296
|
*/
|
|
1182
1297
|
export class ArrayType {
|
|
1183
|
-
constructor(elementType:
|
|
1298
|
+
constructor(elementType: number | StructType, count: number);
|
|
1184
1299
|
getSize(): number;
|
|
1185
1300
|
getLength(): number;
|
|
1186
1301
|
getAlignment(): number;
|
|
@@ -1239,7 +1354,16 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1239
1354
|
* Maximum field alignment in bytes, as Python's `_pack_` (`1` = no padding).
|
|
1240
1355
|
* `true` is accepted as `1`.
|
|
1241
1356
|
*/
|
|
1242
|
-
static _pack_?: number | boolean;
|
|
1357
|
+
static _pack_?: number | boolean | bigint | string | null;
|
|
1358
|
+
|
|
1359
|
+
/**
|
|
1360
|
+
* Bit field layout, as Python's `_layout_`: `"gcc-sysv"` (default except on
|
|
1361
|
+
* Windows) or `"ms"` (default on Windows and with `_pack_`).
|
|
1362
|
+
*/
|
|
1363
|
+
static _layout_?: "gcc-sysv" | "ms";
|
|
1364
|
+
|
|
1365
|
+
/** Minimum alignment in bytes, as Python's `_align_`. */
|
|
1366
|
+
static _align_?: number;
|
|
1243
1367
|
|
|
1244
1368
|
/**
|
|
1245
1369
|
* List of field names whose members are promoted to the parent struct.
|
|
@@ -1248,6 +1372,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1248
1372
|
*/
|
|
1249
1373
|
static _anonymous_?: ReadonlyArray<string>;
|
|
1250
1374
|
|
|
1375
|
+
/** Size in bytes (Python: `sizeof(cls)`). */
|
|
1376
|
+
static readonly size: number;
|
|
1377
|
+
|
|
1378
|
+
/** Alignment in bytes (Python: `alignment(cls)`). */
|
|
1379
|
+
static readonly alignment: number;
|
|
1380
|
+
|
|
1381
|
+
/** Field descriptors, in layout order. */
|
|
1382
|
+
static readonly fields: FieldDef[];
|
|
1383
|
+
|
|
1251
1384
|
/** Create instance with optional initial values. */
|
|
1252
1385
|
static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
|
|
1253
1386
|
|
|
@@ -1260,14 +1393,14 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1260
1393
|
*
|
|
1261
1394
|
* Python ctypes parity: `Structure.from_buffer(source, offset=0)`.
|
|
1262
1395
|
*/
|
|
1263
|
-
static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: Buffer, offset?: number): ThisT;
|
|
1396
|
+
static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
|
|
1264
1397
|
|
|
1265
1398
|
/**
|
|
1266
1399
|
* Create an instance whose buffer is an independent copy of the source bytes.
|
|
1267
1400
|
*
|
|
1268
1401
|
* Python ctypes parity: `Structure.from_buffer_copy(source, offset=0)`.
|
|
1269
1402
|
*/
|
|
1270
|
-
static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source:
|
|
1403
|
+
static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
|
|
1271
1404
|
|
|
1272
1405
|
/**
|
|
1273
1406
|
* Create an instance that views raw memory at `address`. Caller is
|
|
@@ -1301,7 +1434,10 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
|
|
|
1301
1434
|
/** Convert all fields to a plain JavaScript object (snapshot). */
|
|
1302
1435
|
toObject(): FieldsToInstance<F>;
|
|
1303
1436
|
|
|
1304
|
-
/**
|
|
1437
|
+
/** The fields, for `JSON.stringify` (same as {@link toObject}). */
|
|
1438
|
+
toJSON(): FieldsToInstance<F>;
|
|
1439
|
+
|
|
1440
|
+
/** Fields: accessors of the class (not own properties, as in Python). */
|
|
1305
1441
|
[field: string]: any;
|
|
1306
1442
|
}
|
|
1307
1443
|
|
|
@@ -1430,7 +1566,11 @@ export function load(path: string | null): Library;
|
|
|
1430
1566
|
*
|
|
1431
1567
|
* @category Callbacks
|
|
1432
1568
|
*/
|
|
1433
|
-
|
|
1569
|
+
type CallbackRestype = SimpleCDataConstructor | PointerTypeDef | FuncPtrFactory | number | null;
|
|
1570
|
+
type CallbackArgs<T extends readonly FFIType[]> = { -readonly [K in keyof T]: JsFromCType<T[K]> };
|
|
1571
|
+
type CallbackResult<T> = T extends null | SimpleCDataConstructor<"void"> ? void : T extends StructureClass | StructDef | ArrayTypeDef ? never : JsArgFromCType<T> | (T extends SimpleCDataConstructor ? InstanceType<T> : never);
|
|
1572
|
+
|
|
1573
|
+
export function callback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): CallbackWrapper;
|
|
1434
1574
|
|
|
1435
1575
|
/**
|
|
1436
1576
|
* Create a thread-safe callback that can be invoked from any thread.
|
|
@@ -1445,7 +1585,7 @@ export function callback(fn: Function, returnType: AnyType | null, argTypes?: An
|
|
|
1445
1585
|
*
|
|
1446
1586
|
* @category Callbacks
|
|
1447
1587
|
*/
|
|
1448
|
-
export function threadSafeCallback(fn:
|
|
1588
|
+
export function threadSafeCallback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): ThreadSafeCallbackWrapper;
|
|
1449
1589
|
|
|
1450
1590
|
/**
|
|
1451
1591
|
* Create a function pointer type with cdecl calling convention.
|
|
@@ -1482,8 +1622,8 @@ export function threadSafeCallback(fn: Function, returnType: AnyType | null, arg
|
|
|
1482
1622
|
* @category Function Pointers
|
|
1483
1623
|
*/
|
|
1484
1624
|
export interface ParamFlag {
|
|
1485
|
-
/**
|
|
1486
|
-
dir: "in" | "out";
|
|
1625
|
+
/** OUT allocates a pointee; INOUT uses and returns the supplied instance. */
|
|
1626
|
+
dir: "in" | "out" | "inout";
|
|
1487
1627
|
/** Parameter name, used for the named-call form `fn({ name: value, ... })`. */
|
|
1488
1628
|
name: string;
|
|
1489
1629
|
/** Optional default value; applied when the caller omits this `in` param. */
|
|
@@ -1495,47 +1635,54 @@ export interface ParamFlag {
|
|
|
1495
1635
|
*
|
|
1496
1636
|
* @category Function Pointers
|
|
1497
1637
|
*/
|
|
1498
|
-
export interface FuncPtrFactory {
|
|
1638
|
+
export interface FuncPtrFactory<TRet extends FFIType | null = FFIType | null, TArgs extends readonly FFIType[] = readonly FFIType[]> {
|
|
1499
1639
|
/** Call with a raw address to produce a caller. */
|
|
1500
|
-
(address: bigint | number):
|
|
1640
|
+
(address: bigint | number): TypedFFIFunction<TArgs, TRet>;
|
|
1641
|
+
new (address: bigint | number): TypedFFIFunction<TArgs, TRet>;
|
|
1501
1642
|
/**
|
|
1502
1643
|
* Call with a JS function to produce a C-callable callback closure, usable
|
|
1503
1644
|
* as argument or struct field of this type. Keep it referenced while C may
|
|
1504
1645
|
* call it; `release()` frees it.
|
|
1505
1646
|
*/
|
|
1506
|
-
(fn: (...args:
|
|
1647
|
+
(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>): CallbackWrapper;
|
|
1648
|
+
new (fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>): CallbackWrapper;
|
|
1507
1649
|
/**
|
|
1508
1650
|
* Bind an exported function of a library, optionally with paramflags.
|
|
1509
1651
|
* Python: `prototype((name, dll))` / `prototype((name, dll), paramflags)`.
|
|
1510
1652
|
*/
|
|
1511
|
-
(spec: readonly [name: string, library: CDLL]
|
|
1653
|
+
(spec: readonly [name: string, library: CDLL]): TypedFFIFunction<TArgs, TRet>;
|
|
1654
|
+
(spec: readonly [name: string, library: CDLL], paramflags: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): FFIFunction;
|
|
1512
1655
|
|
|
1656
|
+
/** Shared metadata; assigning it does not recompile the captured signature. */
|
|
1513
1657
|
restype: FFIType | null;
|
|
1658
|
+
/** Shared metadata; mutating it does not recompile the captured signature. */
|
|
1514
1659
|
argtypes: FFIType[];
|
|
1515
1660
|
readonly _isFuncPtr: true;
|
|
1516
1661
|
|
|
1517
1662
|
/**
|
|
1518
1663
|
* Bind the factory to a library export with Python-style paramflags.
|
|
1519
|
-
* Out params are allocated automatically and returned
|
|
1664
|
+
* Out params are allocated automatically and returned alone (one value or
|
|
1665
|
+
* an array). Returning the original `args` from errcheck keeps this behavior.
|
|
1666
|
+
* `callAsync()` uses the same output processing and per-call hook snapshot.
|
|
1520
1667
|
*
|
|
1521
1668
|
* Python ctypes parity: `prototype((name, lib), paramflags)`.
|
|
1522
1669
|
*
|
|
1523
1670
|
* @example
|
|
1524
1671
|
* ```javascript
|
|
1525
|
-
* const proto = WINFUNCTYPE(
|
|
1672
|
+
* const proto = WINFUNCTYPE(DWORD, HWND, LPDWORD);
|
|
1526
1673
|
* const fn = proto.bind(user32, "GetWindowThreadProcessId", [
|
|
1527
1674
|
* { dir: "in", name: "hWnd" },
|
|
1528
1675
|
* { dir: "out", name: "pid" },
|
|
1529
|
-
* { dir: "out", name: "tid" },
|
|
1530
1676
|
* ]);
|
|
1531
|
-
* const
|
|
1532
|
-
* const
|
|
1677
|
+
* const pid = fn(hwnd); // positional; thread ID is discarded
|
|
1678
|
+
* const pid2 = fn({ hWnd: hwnd }); // named
|
|
1679
|
+
* const pid3 = await fn.callAsync(hwnd); // async, same output processing
|
|
1533
1680
|
* ```
|
|
1534
1681
|
*/
|
|
1535
|
-
bind(library: CDLL, symbolName: string, paramflags: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>):
|
|
1682
|
+
bind(library: CDLL, symbolName: string, paramflags: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): FFIFunction;
|
|
1536
1683
|
}
|
|
1537
1684
|
|
|
1538
|
-
export function CFUNCTYPE
|
|
1685
|
+
export function CFUNCTYPE<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(restype: TRet, ...argtypes: TArgs): FuncPtrFactory<TRet, TArgs>;
|
|
1539
1686
|
|
|
1540
1687
|
/**
|
|
1541
1688
|
* Create a function pointer type with stdcall calling convention (Windows).
|
|
@@ -1550,7 +1697,7 @@ export function CFUNCTYPE(restype: FFIType | null, ...argtypes: FFIType[]): Func
|
|
|
1550
1697
|
*
|
|
1551
1698
|
* @category Callbacks
|
|
1552
1699
|
*/
|
|
1553
|
-
export function WINFUNCTYPE
|
|
1700
|
+
export function WINFUNCTYPE<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(restype: TRet, ...argtypes: TArgs): FuncPtrFactory<TRet, TArgs>;
|
|
1554
1701
|
|
|
1555
1702
|
/**
|
|
1556
1703
|
* Create a C string buffer (null-terminated).
|
|
@@ -1622,7 +1769,14 @@ export function wstring_at(address: Buffer | bigint | number, size?: number): st
|
|
|
1622
1769
|
*
|
|
1623
1770
|
* @category Memory
|
|
1624
1771
|
*/
|
|
1625
|
-
export function addressof(ptr: Buffer | bigint | number): bigint;
|
|
1772
|
+
export function addressof(ptr: ArrayBufferView | ArrayBuffer | { readonly _buffer: Buffer } | PointerInstance | bigint | number): bigint;
|
|
1773
|
+
|
|
1774
|
+
/**
|
|
1775
|
+
* Memory argument of {@link memmove} / {@link memset}: a buffer (any typed
|
|
1776
|
+
* array, DataView or ArrayBuffer, as bytes), a ctypes instance, a pointer or an
|
|
1777
|
+
* address.
|
|
1778
|
+
*/
|
|
1779
|
+
export type MemoryTarget = ArrayBufferView | ArrayBufferLike | { readonly _buffer: Buffer } | { readonly _as_parameter_: unknown } | PointerInstance | bigint | number | null;
|
|
1626
1780
|
|
|
1627
1781
|
/**
|
|
1628
1782
|
* Copy memory from source to destination.
|
|
@@ -1631,10 +1785,7 @@ export function addressof(ptr: Buffer | bigint | number): bigint;
|
|
|
1631
1785
|
*
|
|
1632
1786
|
* @category Memory
|
|
1633
1787
|
*/
|
|
1634
|
-
|
|
1635
|
-
export type MemoryTarget = Uint8Array | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
|
|
1636
|
-
|
|
1637
|
-
export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): void;
|
|
1788
|
+
export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): bigint;
|
|
1638
1789
|
|
|
1639
1790
|
/**
|
|
1640
1791
|
* Fill memory with a byte value.
|
|
@@ -1643,7 +1794,7 @@ export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): vo
|
|
|
1643
1794
|
*
|
|
1644
1795
|
* @category Memory
|
|
1645
1796
|
*/
|
|
1646
|
-
export function memset(dst: MemoryTarget, value: number, count: number):
|
|
1797
|
+
export function memset(dst: MemoryTarget, value: number, count: number): bigint;
|
|
1647
1798
|
|
|
1648
1799
|
/**
|
|
1649
1800
|
* Read a typed value from a buffer at a given offset.
|
|
@@ -1661,8 +1812,8 @@ export function memset(dst: MemoryTarget, value: number, count: number): void;
|
|
|
1661
1812
|
*
|
|
1662
1813
|
* @category Memory
|
|
1663
1814
|
*/
|
|
1664
|
-
export function readValue<T extends AnyType>(ptr:
|
|
1665
|
-
export function readValue(ptr:
|
|
1815
|
+
export function readValue<T extends AnyType>(ptr: MemorySource, type: T, offset?: number): JsFromCType<T>;
|
|
1816
|
+
export function readValue(ptr: MemorySource, type: AnyType | StructureClass, offset?: number): any;
|
|
1666
1817
|
|
|
1667
1818
|
/**
|
|
1668
1819
|
* Write a typed value to a buffer at a given offset.
|
|
@@ -1674,8 +1825,8 @@ export function readValue(ptr: Buffer | bigint | number | PointerInstance, type:
|
|
|
1674
1825
|
*
|
|
1675
1826
|
* @category Memory
|
|
1676
1827
|
*/
|
|
1677
|
-
export function writeValue<T extends AnyType>(ptr:
|
|
1678
|
-
export function writeValue(ptr:
|
|
1828
|
+
export function writeValue<T extends AnyType>(ptr: MemorySource, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
|
|
1829
|
+
export function writeValue(ptr: MemorySource, type: AnyType | StructureClass, value: any, offset?: number): number | void;
|
|
1679
1830
|
|
|
1680
1831
|
/**
|
|
1681
1832
|
* Get the size of a type in bytes.
|
|
@@ -1691,7 +1842,10 @@ export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type
|
|
|
1691
1842
|
*
|
|
1692
1843
|
* @category Memory
|
|
1693
1844
|
*/
|
|
1694
|
-
export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> |
|
|
1845
|
+
export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> | ArrayBufferView): number;
|
|
1846
|
+
|
|
1847
|
+
/** Memory read/written by {@link readValue} / {@link writeValue}: a buffer, a ctypes instance, a pointer or an address. */
|
|
1848
|
+
type MemorySource = Buffer | ArrayBufferView | { _buffer: Buffer } | bigint | number | PointerInstance;
|
|
1695
1849
|
|
|
1696
1850
|
/**
|
|
1697
1851
|
* Get the alignment requirement of a type in bytes.
|
|
@@ -1734,10 +1888,11 @@ export function struct<F extends Record<string, FieldSpec>>(fields: F, options?:
|
|
|
1734
1888
|
* For Python-like class syntax, use {@link Union} instead.
|
|
1735
1889
|
*
|
|
1736
1890
|
* @param fields - Object mapping field names to types
|
|
1891
|
+
* @param options - Union options (e.g. `{ pack: 1 }`)
|
|
1737
1892
|
*
|
|
1738
1893
|
* @category Structures
|
|
1739
1894
|
*/
|
|
1740
|
-
export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<F>;
|
|
1895
|
+
export function union<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): UnionDef<F>;
|
|
1741
1896
|
|
|
1742
1897
|
/**
|
|
1743
1898
|
* Factory that returns a Structure subclass with typed fields.
|
|
@@ -1747,7 +1902,7 @@ export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<
|
|
|
1747
1902
|
*
|
|
1748
1903
|
* @category Structures
|
|
1749
1904
|
*/
|
|
1750
|
-
export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions):
|
|
1905
|
+
export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Structure<F> & FieldsToInstance<F>>;
|
|
1751
1906
|
|
|
1752
1907
|
/**
|
|
1753
1908
|
* Factory that returns a Union subclass with typed fields.
|
|
@@ -1756,11 +1911,35 @@ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, opt
|
|
|
1756
1911
|
*
|
|
1757
1912
|
* @category Structures
|
|
1758
1913
|
*/
|
|
1759
|
-
export function defineUnion<F extends Record<string, FieldSpec>>(fields: F):
|
|
1914
|
+
export function defineUnion<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Union<F> & FieldsToInstance<F>>;
|
|
1915
|
+
|
|
1916
|
+
/**
|
|
1917
|
+
* Class returned by {@link defineStruct} / {@link defineUnion}: the statics of
|
|
1918
|
+
* {@link Structure} and a constructor with positional values (field order),
|
|
1919
|
+
* an object of field values or a Buffer.
|
|
1920
|
+
* @category Structures
|
|
1921
|
+
*/
|
|
1922
|
+
export interface DefinedClass<F extends Record<string, FieldSpec>, I> {
|
|
1923
|
+
new (values?: Partial<FieldsToInstance<F>> | Buffer): I;
|
|
1924
|
+
new (...values: any[]): I;
|
|
1925
|
+
readonly size: number;
|
|
1926
|
+
readonly alignment: number;
|
|
1927
|
+
readonly fields: FieldDef[];
|
|
1928
|
+
create(values?: Partial<FieldsToInstance<F>> | Buffer): I;
|
|
1929
|
+
toObject(bufOrInstance: Buffer | I): FieldsToInstance<F>;
|
|
1930
|
+
from_buffer(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
|
|
1931
|
+
from_buffer_copy(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
|
|
1932
|
+
from_address(address: bigint | number): I;
|
|
1933
|
+
in_dll(library: CDLL | Library, name: string): I;
|
|
1934
|
+
}
|
|
1760
1935
|
|
|
1761
1936
|
/**
|
|
1762
1937
|
* Define a fixed-size array type.
|
|
1763
1938
|
*
|
|
1939
|
+
* Weakly interned by element type and count: live types keep their identity,
|
|
1940
|
+
* including when retained by instances, signatures or containing types.
|
|
1941
|
+
* The cache does not keep unused types alive.
|
|
1942
|
+
*
|
|
1764
1943
|
* Python equivalent: `c_int * 5`
|
|
1765
1944
|
*
|
|
1766
1945
|
* @param elementType - Type of each element
|
|
@@ -1775,18 +1954,21 @@ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new
|
|
|
1775
1954
|
*
|
|
1776
1955
|
* @category Structures
|
|
1777
1956
|
*/
|
|
1778
|
-
export function array<E extends
|
|
1957
|
+
export function array<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
|
|
1958
|
+
|
|
1959
|
+
/** Element types of {@link array}: C types, structures and unions (classes or definitions), arrays, pointers, function pointers. */
|
|
1960
|
+
type ArrayElementType = SimpleCDataConstructor | StructDef | UnionDef | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory;
|
|
1779
1961
|
|
|
1780
1962
|
/**
|
|
1781
1963
|
* Alias of {@link array}. Python equivalent: `ctypes.ARRAY(type, length)`.
|
|
1782
1964
|
* @category Structures
|
|
1783
1965
|
*/
|
|
1784
|
-
export function ARRAY<E extends
|
|
1966
|
+
export function ARRAY<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
|
|
1785
1967
|
|
|
1786
1968
|
/**
|
|
1787
1969
|
* Define a bit field for use in struct `_fields_`.
|
|
1788
1970
|
*
|
|
1789
|
-
* @param baseType - The underlying integer type (e.g. `c_uint32`)
|
|
1971
|
+
* @param baseType - The underlying integer type (e.g. `c_uint32`) or `c_bool`; other types raise TypeError, as in Python
|
|
1790
1972
|
* @param bits - Number of bits
|
|
1791
1973
|
*
|
|
1792
1974
|
* @example
|
|
@@ -1801,18 +1983,25 @@ export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | Pointe
|
|
|
1801
1983
|
*
|
|
1802
1984
|
* @category Structures
|
|
1803
1985
|
*/
|
|
1804
|
-
export function bitfield(baseType:
|
|
1986
|
+
export function bitfield(baseType: SimpleCDataConstructor, bits: number): BitFieldDef;
|
|
1805
1987
|
|
|
1806
1988
|
/**
|
|
1807
|
-
* Pass an object by reference
|
|
1989
|
+
* Pass an object by reference, retaining its owner and applying a signed byte offset.
|
|
1990
|
+
* In-range references are Buffer views; out-of-range offsets are address carriers.
|
|
1808
1991
|
*
|
|
1809
1992
|
* Python equivalent: `ctypes.byref`
|
|
1810
1993
|
*
|
|
1811
1994
|
* @param obj - A Buffer, SimpleCData instance, or any object with a `_buffer` property
|
|
1995
|
+
* @param offset - Signed byte offset; the caller is responsible for valid external memory
|
|
1812
1996
|
*
|
|
1813
1997
|
* @category Pointers
|
|
1814
1998
|
*/
|
|
1815
|
-
export
|
|
1999
|
+
export interface ByRefAddress {
|
|
2000
|
+
readonly address: bigint;
|
|
2001
|
+
readonly _as_parameter_: bigint;
|
|
2002
|
+
}
|
|
2003
|
+
export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }, offset?: 0): Buffer;
|
|
2004
|
+
export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }, offset: number): Buffer | ByRefAddress;
|
|
1816
2005
|
|
|
1817
2006
|
/**
|
|
1818
2007
|
* Interpret a pointer as a different type.
|
|
@@ -1842,8 +2031,8 @@ export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }):
|
|
|
1842
2031
|
*
|
|
1843
2032
|
* @category Pointers
|
|
1844
2033
|
*/
|
|
1845
|
-
export function cast<T>(ptr:
|
|
1846
|
-
export function cast(ptr:
|
|
2034
|
+
export function cast<T>(ptr: MemorySource | ArrayBuffer | ByRefAddress | null, targetType: PointerTypeDef<T>): PointerInstance<T>;
|
|
2035
|
+
export function cast(ptr: MemorySource | ArrayBuffer | ByRefAddress | null, targetType: AnyType | StructDef | StructureClass): any;
|
|
1847
2036
|
|
|
1848
2037
|
/**
|
|
1849
2038
|
* Create a pointer type for a given base type.
|
|
@@ -1965,7 +2154,7 @@ export function set_last_error(code: number): number;
|
|
|
1965
2154
|
* @category Error Handling
|
|
1966
2155
|
*/
|
|
1967
2156
|
export class ArgumentError extends TypeError {
|
|
1968
|
-
constructor(message?: string);
|
|
2157
|
+
constructor(message?: string, options?: ErrorOptions);
|
|
1969
2158
|
}
|
|
1970
2159
|
|
|
1971
2160
|
/**
|
|
@@ -1985,11 +2174,12 @@ export function FormatError(code?: number): string;
|
|
|
1985
2174
|
* Python equivalent: `ctypes.WinError()`
|
|
1986
2175
|
*
|
|
1987
2176
|
* @param code - Error code (defaults to `GetLastError()`)
|
|
1988
|
-
* @
|
|
2177
|
+
* @param descr - Message (defaults to `FormatError(code)`)
|
|
2178
|
+
* @returns Error with `winerror`, `errno` (mapped as Python's OSError) and `strerror`
|
|
1989
2179
|
*
|
|
1990
2180
|
* @category Error Handling
|
|
1991
2181
|
*/
|
|
1992
|
-
export function WinError(code?: number): Error & { winerror: number };
|
|
2182
|
+
export function WinError(code?: number | null, descr?: string): Error & { winerror: number; errno: number; strerror: string };
|
|
1993
2183
|
|
|
1994
2184
|
// =============================================================================
|
|
1995
2185
|
// SimpleCData - Base class for simple C data types
|
|
@@ -2019,13 +2209,13 @@ export interface SimpleCDataConstructor<Tag extends string = string> {
|
|
|
2019
2209
|
_writer(buf: Buffer, offset: number, value: JsArgFromTag<Tag>): void;
|
|
2020
2210
|
|
|
2021
2211
|
/** Create an instance that aliases an existing Buffer (zero-copy). */
|
|
2022
|
-
from_buffer(buffer: Buffer, offset?: number):
|
|
2212
|
+
from_buffer<T extends SimpleCDataConstructor<Tag>>(this: T, buffer: ArrayBufferView | { readonly _buffer: Buffer }, offset?: number): InstanceType<T>;
|
|
2023
2213
|
/** Create an instance whose buffer is a copy of the source bytes. */
|
|
2024
|
-
from_buffer_copy(buffer: Buffer, offset?: number):
|
|
2214
|
+
from_buffer_copy<T extends SimpleCDataConstructor<Tag>>(this: T, buffer: ArrayBufferView | { readonly _buffer: Buffer }, offset?: number): InstanceType<T>;
|
|
2025
2215
|
/** Create an instance viewing raw memory at the given address. */
|
|
2026
|
-
from_address(address: bigint | number):
|
|
2216
|
+
from_address<T extends SimpleCDataConstructor<Tag>>(this: T, address: bigint | number): InstanceType<T>;
|
|
2027
2217
|
/** Bind this type to an exported global variable in a shared library. */
|
|
2028
|
-
in_dll(library: CDLL | Library, name: string):
|
|
2218
|
+
in_dll<T extends SimpleCDataConstructor<Tag>>(this: T, library: CDLL | Library, name: string): InstanceType<T>;
|
|
2029
2219
|
}
|
|
2030
2220
|
|
|
2031
2221
|
/**
|
|
@@ -2097,6 +2287,8 @@ export interface SimpleCDataInstance<T = any> {
|
|
|
2097
2287
|
toString(): string;
|
|
2098
2288
|
toJSON(): T;
|
|
2099
2289
|
valueOf(): T;
|
|
2290
|
+
/** OUT conversion; defaults to the value for builtins and the instance for subclasses. */
|
|
2291
|
+
__ctypes_from_outparam__(): unknown;
|
|
2100
2292
|
}
|
|
2101
2293
|
|
|
2102
2294
|
// =============================================================================
|
|
@@ -2458,8 +2650,9 @@ export const DEFAULT_MODE: number;
|
|
|
2458
2650
|
* are provided (e.g. `"c"` → `"msvcrt.dll"`).
|
|
2459
2651
|
* - On Linux, the `ldconfig` cache and common library directories are
|
|
2460
2652
|
* searched for the best-matching `libNAME.so.VERSION`.
|
|
2461
|
-
* - On macOS,
|
|
2462
|
-
*
|
|
2653
|
+
* - On macOS, the `DYLD_*` paths, the dyld fallback directories, Homebrew and
|
|
2654
|
+
* the framework directories are searched, including the dyld shared cache
|
|
2655
|
+
* (system libraries and frameworks are not on disk since macOS 11).
|
|
2463
2656
|
*
|
|
2464
2657
|
* Returns `null` if the input is invalid. Returns a best-effort fallback
|
|
2465
2658
|
* (bare soname) if nothing is found, so the loader can still try its own
|